Compare commits

...
8 Commits
57 changed files with 693 additions and 46 deletions
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
# Planning with Files
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+1 -1
View File
@@ -10,7 +10,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Installs across 60+ agents.",
"version": "3.18.0"
"version": "3.18.2"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.18.0",
"version": "3.18.2",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Works across 60+ agents and includes Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese.",
"author": {
"name": "OthmanAdi",
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"${CODEBUDDY_PLUGIN_ROOT}/scripts/skill-hook.sh\" \"$HOME/.codebuddy/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.18.0",
"version": "3.18.2",
"description": "Persistent project planning for Codex. Opt-in lifecycle hooks inject selected plan context; automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs Markdown-declared commands. No network upload path.",
"author": {
"name": "OthmanAdi",
+2 -2
View File
@@ -37,10 +37,10 @@ if [ -f "$PLAN_FILE" ]; then
if [ -n "$PWF_PYTHON" ] && [ -f "$PWF_PYTHON" ] && [ -f "${HOOK_DIR}/context_frame.py" ]; then
if [ -n "$PLAN_DIR" ]; then ATTEST_FILE="${PLAN_DIR}/.attestation"; else ATTEST_FILE=".plan-attestation"; fi
if [ -n "$PLAN_DIR" ]; then MODE_FILE="${PLAN_DIR}/.mode"; else MODE_FILE=".mode"; fi
PWF_MODE=$("$PWF_PYTHON" -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import context_frame as c; raw=c.read_optional_regular_bytes(Path(sys.argv[2]), max_source_bytes=256); tokens=[] if raw is None else raw.decode("ascii", errors="strict").split(); allowed={"autonomous", "gate", "inject-smart"}; print("unsafe" if any(t not in allowed for t in tokens) else ("gated" if "gate" in tokens else ("autonomous" if "autonomous" in tokens else "legacy")))' "$HOOK_DIR" "$MODE_FILE" 2>/dev/null) || PWF_MODE="unsafe"
PWF_MODE=$("$PWF_PYTHON" -I -X utf8 -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import context_frame as c; raw=c.read_optional_regular_bytes(Path(sys.argv[2]), max_source_bytes=256); tokens=[] if raw is None else raw.decode("ascii", errors="strict").split(); allowed={"autonomous", "gate", "inject-smart"}; print("unsafe" if any(t not in allowed for t in tokens) else ("gated" if "gate" in tokens else ("autonomous" if "autonomous" in tokens else "legacy")))' "$HOOK_DIR" "$MODE_FILE" 2>/dev/null) || PWF_MODE="unsafe"
case "$PWF_MODE" in
autonomous|gated) echo '{"decision": "allow"}'; exit 0 ;;
legacy) "$PWF_PYTHON" "${HOOK_DIR}/context_frame.py" plan "$PLAN_FILE" --head 30 --attestation "$ATTEST_FILE" --mode "$MODE_FILE" >&2 ;;
legacy) "$PWF_PYTHON" -I -X utf8 "${HOOK_DIR}/context_frame.py" plan "$PLAN_FILE" --head 30 --attestation "$ATTEST_FILE" --mode "$MODE_FILE" >&2 ;;
*) : ;;
esac
fi
+1 -1
View File
@@ -12,7 +12,7 @@ SKILL_DIR="$CODEX_ROOT/skills/planning-with-files"
PYTHON_BIN="${PYTHON_BIN:-$(command -v python3 || command -v python)}"
if [ -n "$PYTHON_BIN" ] && [ -f "$SKILL_DIR/scripts/session-catchup.py" ]; then
"$PYTHON_BIN" "$SKILL_DIR/scripts/session-catchup.py" --no-history "$(pwd)"
"$PYTHON_BIN" -I -X utf8 "$SKILL_DIR/scripts/session-catchup.py" --no-history "$(pwd)"
fi
sh "$SCRIPT_DIR/user-prompt-submit.sh"
+5 -5
View File
@@ -23,7 +23,7 @@ validate_python_candidate() {
case "$_tp_lower" in
*/microsoft/windowsapps/*) return 1 ;;
esac
"$_tp_candidate" -c 'import sys' >/dev/null 2>&1 || return 1
"$_tp_candidate" -I -X utf8 -c 'import sys' >/dev/null 2>&1 || return 1
printf '%s\n' "$_tp_candidate"
}
@@ -61,7 +61,7 @@ if [ -n "${PWF_PLAN_ROOT:-}" ]; then
esac
PIN_PYTHON="$(trusted_python explicit 2>/dev/null)" || PIN_PYTHON=""
[ -n "$PIN_PYTHON" ] || { echo "[planning-with-files] PWF_PLAN_ROOT could not be validated; nothing injected."; exit 0; }
PIN_REAL=$("$PIN_PYTHON" -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import codex_hook_adapter as a; root=a.effective_plan_root(Path.cwd()); print(root or "")' "$HOOK_DIR" 2>/dev/null) || PIN_REAL=""
PIN_REAL=$("$PIN_PYTHON" -I -X utf8 -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import codex_hook_adapter as a; root=a.effective_plan_root(Path.cwd()); print(root or "")' "$HOOK_DIR" 2>/dev/null) || PIN_REAL=""
[ -n "$PIN_REAL" ] || { echo "[planning-with-files] PWF_PLAN_ROOT must stay within the current workspace; nothing injected."; exit 0; }
if [ -n "$PIN_REAL" ] && [ -d "$PIN_REAL" ]; then
PWF_PLAN_ROOT="$PIN_REAL"
@@ -145,7 +145,7 @@ else
if [ -z "$PWF_PYTHON" ]; then
PWF_SESSION_ADMISSION="refused"
else
PWF_SESSION_ADMISSION=$("$PWF_PYTHON" -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import codex_hook_adapter as a; root=a.effective_plan_root(Path.cwd());
PWF_SESSION_ADMISSION=$("$PWF_PYTHON" -I -X utf8 -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import codex_hook_adapter as a; root=a.effective_plan_root(Path.cwd());
if root is None: print("refused")
else:
try: (root / ".planning" / "sessions").lstat(); armed=True
@@ -253,13 +253,13 @@ if [ -f "$PLAN_FILE" ]; then
if [ -z "$PWF_PYTHON" ] || [ ! -f "${HOOK_DIR}/context_frame.py" ]; then exit 0; fi
if [ -n "$PLAN_DIR" ]; then ATTEST_FILE="${PLAN_DIR}/.attestation"; else ATTEST_FILE="${PLAN_PREFIX}.plan-attestation"; fi
if [ -n "$PLAN_DIR" ]; then MODE_FILE="${PLAN_DIR}/.mode"; else MODE_FILE="${PLAN_PREFIX}.mode"; fi
PLAN_CONTEXT=$("$PWF_PYTHON" "${HOOK_DIR}/context_frame.py" plan "$PLAN_FILE" --head 50 --attestation "$ATTEST_FILE" --mode "$MODE_FILE" 2>&1)
PLAN_CONTEXT=$("$PWF_PYTHON" -I -X utf8 "${HOOK_DIR}/context_frame.py" plan "$PLAN_FILE" --head 50 --attestation "$ATTEST_FILE" --mode "$MODE_FILE" 2>&1)
if [ $? -ne 0 ]; then printf '%s\n' "$PLAN_CONTEXT"; exit 0; fi
echo "[planning-with-files] ACTIVE PLAN — current state:"
printf '%s\n' "$PLAN_CONTEXT"
echo ""
if [ -f "$PROGRESS_FILE" ]; then
PROGRESS_CONTEXT=$("$PWF_PYTHON" "${HOOK_DIR}/context_frame.py" progress "$PROGRESS_FILE" --tail 20 2>&1)
PROGRESS_CONTEXT=$("$PWF_PYTHON" -I -X utf8 "${HOOK_DIR}/context_frame.py" progress "$PROGRESS_FILE" --tail 20 2>&1)
[ $? -eq 0 ] && printf '%s\n' "$PROGRESS_CONTEXT"
fi
echo ""
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
# Planning with Files
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+1 -1
View File
@@ -18,7 +18,7 @@ CURRENT_PHASE=$(grep -m1 "^## Current Phase" "$PLAN_FILE" 2>/dev/null || grep -m
if [ -n "$CURRENT_PHASE" ]; then
PYTHON=$(command -v python3 || command -v python)
ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "[planning-with-files] Current: $CURRENT_PHASE" 2>/dev/null || echo "\"\"")
ESCAPED=$($PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "[planning-with-files] Current: $CURRENT_PHASE" 2>/dev/null || echo "\"\"")
printf '%s\n' "{\"additionalContext\":$ESCAPED}"
else
echo '{}'
+1 -1
View File
@@ -21,7 +21,7 @@ fi
PYTHON=$(command -v python3 || command -v python)
if [ -n "$PYTHON" ]; then
ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$CONTEXT" 2>/dev/null)
ESCAPED=$($PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$CONTEXT" 2>/dev/null)
if [ -n "$ESCAPED" ] && [ "$ESCAPED" != "\"\"" ]; then
printf '%s\n' "{\"systemMessage\":$ESCAPED}"
exit 0
+1 -1
View File
@@ -18,7 +18,7 @@ if [ -f "$SCRIPT_DIR/check-complete.sh" ]; then
RESULT=$(sh "$SCRIPT_DIR/check-complete.sh" 2>/dev/null || true)
if [ -n "$RESULT" ]; then
PYTHON=$(command -v python3 || command -v python)
ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$RESULT" 2>/dev/null || echo "\"\"")
ESCAPED=$($PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$RESULT" 2>/dev/null || echo "\"\"")
printf '%s\n' "{\"systemMessage\":$ESCAPED}"
exit 0
fi
+2 -2
View File
@@ -19,11 +19,11 @@ fi
PYTHON=$(command -v python3 || command -v python)
CATCHUP=""
if [ -n "$PYTHON" ] && [ -f "$SCRIPT_DIR/session-catchup.py" ]; then
CATCHUP=$($PYTHON "$SCRIPT_DIR/session-catchup.py" --no-history "$(pwd)" 2>/dev/null || true)
CATCHUP=$($PYTHON -I -X utf8 "$SCRIPT_DIR/session-catchup.py" --no-history "$(pwd)" 2>/dev/null || true)
fi
if [ -n "$CATCHUP" ]; then
ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$CATCHUP" 2>/dev/null || echo "\"[planning-with-files] Session recovery data available. Read task_plan.md, progress.md, and findings.md.\"")
ESCAPED=$($PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$CATCHUP" 2>/dev/null || echo "\"[planning-with-files] Session recovery data available. Read task_plan.md, progress.md, and findings.md.\"")
printf '%s\n' "{\"hookSpecificOutput\":{\"additionalContext\":$ESCAPED}}"
else
echo '{"hookSpecificOutput":{"additionalContext":"[planning-with-files] Active plan detected. Read task_plan.md, progress.md, and findings.md before proceeding."}}'
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+2 -2
View File
@@ -21,7 +21,7 @@ for _p in /usr/bin/python3 /usr/local/bin/python3 /opt/homebrew/bin/python3; do
[ -x "$_p" ] && { PYTHON="$_p"; break; }
done
[ -z "$PYTHON" ] && PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
ERROR_MSG=$(printf '%s\n' "$INPUT" | $PYTHON -c "
ERROR_MSG=$(printf '%s\n' "$INPUT" | $PYTHON -I -X utf8 -c "
import sys, json
try:
data = json.load(sys.stdin)
@@ -33,7 +33,7 @@ except:
if [ -n "$ERROR_MSG" ]; then
CONTEXT="[planning-with-files] Error detected: ${ERROR_MSG}. Log this error in task_plan.md under Errors Encountered with the attempt number and resolution."
ESCAPED=$(printf '%s\n' "$CONTEXT" | $PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
ESCAPED=$(printf '%s\n' "$CONTEXT" | $PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"ErrorOccurred\",\"additionalContext\":$ESCAPED}}"
else
echo '{}'
+1 -1
View File
@@ -31,7 +31,7 @@ for _p in /usr/bin/python3 /usr/local/bin/python3 /opt/homebrew/bin/python3; do
[ -x "$_p" ] && { PYTHON="$_p"; break; }
done
[ -z "$PYTHON" ] && PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
ESCAPED=$(echo "$CONTEXT" | $PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
ESCAPED=$(echo "$CONTEXT" | $PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":$ESCAPED}}"
exit 0
+2 -2
View File
@@ -21,7 +21,7 @@ if [ -f "$PLAN_FILE" ]; then
# Plan exists: keep catchup zero-history, then read the plan header.
CATCHUP=""
if [ -n "$PYTHON" ] && [ -f "$SKILL_DIR/scripts/session-catchup.py" ]; then
CATCHUP=$($PYTHON "$SKILL_DIR/scripts/session-catchup.py" --no-history "$(pwd)" 2>/dev/null | head -100)
CATCHUP=$($PYTHON -I -X utf8 "$SKILL_DIR/scripts/session-catchup.py" --no-history "$(pwd)" 2>/dev/null | head -100)
fi
if [ -n "$CATCHUP" ]; then
@@ -43,7 +43,7 @@ if [ -z "$CONTEXT" ]; then
fi
# Escape context for JSON
ESCAPED=$(echo "$CONTEXT" | $PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
ESCAPED=$(echo "$CONTEXT" | $PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":$ESCAPED}}"
exit 0
+4 -2
View File
@@ -29,7 +29,9 @@ jobs:
# on ubuntu so GNU-only regressions fail there too.
os: [ubuntu-latest, windows-latest, macos-latest]
runs-on: ${{ matrix.os }}
timeout-minutes: 15
# Windows runs the full suite through Git Bash and native PowerShell.
# Successful runs already approach 15 minutes; allow runner variance.
timeout-minutes: ${{ matrix.os == 'windows-latest' && 30 || 15 }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
@@ -45,7 +47,7 @@ jobs:
# sh.exe on windows-latest).
run: python -c "import shutil, sys; sys.exit(0 if shutil.which('sh') else 1)"
- name: Run pytest
run: python -m pytest tests/ -q
run: python -m pytest tests/ -q --durations=20
vitest:
name: vitest (Pi extension)
+1 -1
View File
@@ -2,7 +2,7 @@
name: planning-with-files
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
metadata:
version: "3.18.0"
version: "3.18.2"
hermes:
tags: [planning, long-running-tasks, context-engineering, workflow]
---
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.mastracode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.config/opencode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.opencode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.18.0",
"version": "3.18.2",
"description": "Persistent project planning with selected context injection. Automatic recovery uses project files only; explicit catchup modes read same-project local session records for aggregate counts or bounded replay. The host-aware gate never runs Markdown-declared commands. No network upload path. Ships the skill plus a Pi Coding Agent extension.",
"keywords": [
"pi-package",
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+20
View File
@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
## [Unreleased]
## [3.18.2] - 2026-09-16
### Fixed
- IDE sync verification now fails when an enabled mapping has no canonical source, reports every affected entry, and continues checking the remaining mappings. Verification remains read-only (#244).
### Security
- Run Python in isolated mode in the Codex, Gemini, and GitHub Copilot shell adapters. Project-local modules and Python environment overrides can no longer shadow standard-library imports in these calls. Explicit UTF-8 mode preserves Unicode project paths and error messages on Windows (#245).
### Thanks
- @kuei51307-hub, for missing-source detection and CLI regression coverage in #244.
- @ShaunLinTW, for isolating adapter Python calls and adding import-shadowing regression coverage in #245.
## [3.18.1] - 2026-09-15
### Fixed
- Accept a leading UTF-8 BOM in `.planning/.active_plan` when showing the current plan or listing saved plans. This restores the active marker for pointers written by Windows editors and PowerShell UTF-8 workflows. The fix ships across all canonical shell helper copies (#243).
### Thanks
- @kuei51307-hub, for the BOM compatibility fix and regression coverage in #243.
## [3.18.0] - 2026-09-13
### Added
+2 -2
View File
@@ -7,8 +7,8 @@ authors:
- family-names: Adi
given-names: Ahmad Othman Ammar
alias: OthmanAdi
version: "3.18.0"
date-released: "2026-09-13"
version: "3.18.2"
date-released: "2026-09-16"
license: MIT
url: "https://github.com/OthmanAdi/planning-with-files"
repository-code: "https://github.com/OthmanAdi/planning-with-files"
+9 -1
View File
@@ -32,7 +32,15 @@ Before opening a pull request, run the test suite:
python -m pytest tests/ -q
```
Two pre-existing Windows exec-bit test failures may appear on Windows. If those are the only failures, note that in your pull request description.
Investigate test failures and include any unresolved findings in your pull request description.
## CI completion rule
Maintainer delivery is complete only after all five `Tests` jobs succeed on the final commit pushed to `master`: pytest on Linux, Windows and macOS, plus the Pi extension and OpenCode plugin suites.
After the final push, verify the remote `master` commit and wait for its workflow to finish. Queued, running, cancelled, timed-out, failed or missing checks mean verification is unfinished. Continue investigating, fixing and rerunning until every job is green. Preserve test coverage and security checks; change runtime limits only when measured runtime justifies a bounded adjustment.
A passing candidate branch or an identical Git tree does not replace checks on the final pushed commit. Recheck remote `master` and its check results immediately before reporting completion. If the user explicitly stops the work or an external blocker prevents progress, record the unfinished checks and the blocker.
## Project layout
+9 -2
View File
@@ -106,6 +106,13 @@ These amazing people have contributed code, documentation, or significant improv
### Other Contributors
- **[Shaun Lin](https://github.com/ShaunLinTW)**, [PR #245](https://github.com/OthmanAdi/planning-with-files/pull/245)
- Isolated Python calls in the Codex, Gemini, and GitHub Copilot shell adapters and added regression coverage for project-local import shadowing.
- **[@kuei51307-hub](https://github.com/kuei51307-hub)**, [PR #243](https://github.com/OthmanAdi/planning-with-files/pull/243), [PR #244](https://github.com/OthmanAdi/planning-with-files/pull/244)
- Fixed active-plan display and listing for UTF-8 BOM-prefixed pointers, with regression coverage across the synchronized shell helpers.
- Made IDE sync verification report missing canonical sources, with subprocess tests for read-only verification and unchanged sync behavior.
- **[@Dphoshoba](https://github.com/Dphoshoba)**, [PR #242](https://github.com/OthmanAdi/planning-with-files/pull/242)
- Proposed and implemented named-plan listing with phase counts and a shared active-pointer marker.
@@ -428,6 +435,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
---
**Total Contributors:** 60+ and growing!
**Total Contributors:** 62+ and growing!
*Last updated: 2026-09-13*
*Last updated: 2026-09-16*
+2
View File
@@ -356,6 +356,8 @@ One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from
| Version | Highlights |
|---------|------------|
| **v3.18.2** | Isolates Python in Codex, Gemini, and Copilot shell adapters and makes IDE sync verification fail on missing canonical sources (#244, #245). |
| **v3.18.1** | Fixes active-plan display and listing for UTF-8 BOM-prefixed pointers from Windows editors and PowerShell workflows across the canonical shell helpers (#243). |
| **v3.18.0** | Lists saved plans and phase counts with `--list` or PowerShell `-List` (#242). Supports the shipped translated templates, checks project containment, and delivers the canonical helpers across IDE bundles. |
| **v3.17.2** | Fixes #241: the native Codex manifest disables legacy command migration, removing 13 redundant `source-command-*` skills from plugin installs. The canonical planning skill, Codex hooks, and Claude commands remain available. |
| **v3.17.1** | Fixes #240: two named plans in the same project now require `PLAN_ID`, even without `.planning/sessions/`. A shared pointer or newest-plan guess cannot redirect a Codex session across compaction. Ambiguous hooks inject no plan and Stop does not gate against a guessed plan. |
+6
View File
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+10 -1
View File
@@ -433,7 +433,11 @@ def main(argv=None):
# Verify mode: just check for drift
src_hash = file_hash(src)
dst_hash = file_hash(dst)
if src_hash and dst_hash and src_hash != dst_hash:
if src_hash is None:
print(f" MISSING SOURCE: {src}")
stats["missing_src"] += 1
ide_changes += 1
elif src_hash and dst_hash and src_hash != dst_hash:
print(f" DRIFT: {dst}")
stats["drift"] += 1
ide_changes += 1
@@ -454,6 +458,11 @@ def main(argv=None):
# Summary
print(f"\n{'-' * 50}")
if verify:
if stats["missing_src"] > 0:
print(f"MISSING SOURCES: {stats['missing_src']} sync entry/entries "
"have no canonical source.")
print("Restore the missing canonical files, then rerun --verify.")
sys.exit(1)
total_drift = stats["drift"]
if total_drift > 0:
print(f"DRIFT DETECTED: {total_drift} file(s) out of sync.")
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-ar/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
# نظام تخطيط الملفات
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-de/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
# Dateiplanungssystem
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-es/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
# Sistema de Planificación con Archivos
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+1 -1
View File
@@ -37,7 +37,7 @@ hooks:
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-zh/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+1 -1
View File
@@ -37,7 +37,7 @@ hooks:
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-zht/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.0"
version: "3.18.2"
---
# Planning with Files
@@ -223,6 +223,12 @@ phase_status() {
current_active() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
+50
View File
@@ -0,0 +1,50 @@
"""BOM-prefixed shell pointers retain their bytes in display and listing modes."""
from __future__ import annotations
import codecs
import os
import shutil
import stat
import subprocess
from pathlib import Path
import pytest
SCRIPT = Path(__file__).resolve().parents[1] / "scripts" / "set-active-plan.sh"
SH = shutil.which("sh")
@pytest.mark.skipif(SH is None, reason="requires a POSIX sh")
@pytest.mark.parametrize("ending", [b"", b"\n", b"\r\n"], ids=["no-newline", "lf", "crlf"])
def test_bom_pointer_display_and_listing_preserve_readonly_bytes(tmp_path, ending):
plan = tmp_path / ".planning" / "alpha"
plan.mkdir(parents=True)
(plan / "task_plan.md").write_text("### Phase 1: Work [pending]\n", encoding="utf-8")
pointer = tmp_path / ".planning" / ".active_plan"
original_bytes = codecs.BOM_UTF8 + b"alpha" + ending
pointer.write_bytes(original_bytes)
original_mode = pointer.stat().st_mode
original_mtime = pointer.stat().st_mtime_ns
pointer.chmod(stat.S_IREAD)
env = os.environ.copy()
for name in ("PLAN_ID", "PWF_PLAN_ROOT", "PLANNING_DISABLED"):
env.pop(name, None)
try:
for args in ([], ["--list"]):
result = subprocess.run(
[SH, str(SCRIPT), *args], cwd=tmp_path, env=env,
capture_output=True, text=True, encoding="utf-8",
timeout=60, check=False,
)
assert result.returncode == 0, result.stdout + result.stderr
assert not result.stderr.strip(), result.stderr
if args:
assert any(line.startswith("- alpha [active]")
for line in result.stdout.splitlines()), result.stdout
else:
assert "Active plan: alpha" in result.stdout, result.stdout
assert pointer.read_bytes() == original_bytes
assert pointer.stat().st_mtime_ns == original_mtime
finally:
pointer.chmod(original_mode)
+225
View File
@@ -0,0 +1,225 @@
"""Regression coverage for shell-adapter Python import isolation."""
from __future__ import annotations
import json
import os
import shutil
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path
REPO = Path(__file__).resolve().parent.parent
SH = shutil.which("sh")
# Use the same Git for Windows installation, not a WSL bash launcher.
BASH = shutil.which("bash", path=str(Path(SH).parent)) if os.name == "nt" and SH else shutil.which("bash")
CODEX_HOOKS = REPO / ".codex" / "hooks"
GEMINI_HOOKS = REPO / ".gemini" / "hooks"
COPILOT_HOOKS = REPO / ".github" / "hooks" / "scripts"
PYTHON_SHELL_HOOKS = (
GEMINI_HOOKS / "before-model.sh",
GEMINI_HOOKS / "before-tool.sh",
GEMINI_HOOKS / "session-start.sh",
GEMINI_HOOKS / "session-end.sh",
COPILOT_HOOKS / "session-start.sh",
COPILOT_HOOKS / "pre-tool-use.sh",
COPILOT_HOOKS / "error-occurred.sh",
)
CODEX_PYTHON_SHELL_HOOKS = (
CODEX_HOOKS / "pre-tool-use.sh",
CODEX_HOOKS / "session-start.sh",
CODEX_HOOKS / "user-prompt-submit.sh",
)
def shell_python_is_usable() -> bool:
if not BASH:
return False
result = subprocess.run(
[
str(BASH),
"-c",
'PY=$(command -v python3 || command -v python); [ -n "$PY" ] && "$PY" -I -c "import json"',
],
capture_output=True,
text=True,
timeout=10,
)
return result.returncode == 0
@unittest.skipUnless(shell_python_is_usable(), "shell Python is not usable")
class AdapterPythonIsolationTests(unittest.TestCase):
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory()
self.cwd = Path(self._tmp.name)
(self.cwd / "task_plan.md").write_text(
"# Task Plan\n## Current Phase: hardening\n### Phase 1: Work\n"
"**Status:** in_progress\n",
encoding="utf-8",
)
(self.cwd / "json.py").write_text(
"open('PLANTED_json', 'w').close()\nraise RuntimeError('shadow loaded')\n",
encoding="utf-8",
)
def tearDown(self) -> None:
self._tmp.cleanup()
def run_hook(self, script: Path, input_data: str = "{}") -> dict:
result = subprocess.run(
# Gemini executes Bash-shebang scripts directly; Copilot declares
# these hooks in its "bash" field. POSIX sh can be dash on Linux.
[str(BASH), str(script)],
cwd=str(self.cwd),
env=dict(os.environ, PYTHONUTF8="1"),
input=input_data,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=60,
)
self.assertEqual(0, result.returncode, result.stderr)
return json.loads(result.stdout.lstrip("\ufeff"))
def test_gemini_json_encoding_ignores_project_json_module(self) -> None:
for name in ("before-model.sh", "before-tool.sh"):
with self.subTest(hook=name):
marker = self.cwd / "PLANTED_json"
marker.unlink(missing_ok=True)
payload = self.run_hook(GEMINI_HOOKS / name)
self.assertFalse(marker.exists(), f"{name} imported project json.py")
self.assertIn("hardening", json.dumps(payload))
def test_copilot_python_paths_ignore_project_json_module(self) -> None:
cases = (
("session-start.sh", "{}"),
("pre-tool-use.sh", "{}"),
("error-occurred.sh", '{"error":{"message":"fixture failure"}}'),
)
for name, input_data in cases:
with self.subTest(hook=name):
marker = self.cwd / "PLANTED_json"
marker.unlink(missing_ok=True)
payload = self.run_hook(COPILOT_HOOKS / name, input_data)
self.assertFalse(marker.exists(), f"{name} imported project json.py")
self.assertIn("additionalContext", payload.get("hookSpecificOutput", {}))
def test_copilot_unicode_error_survives_isolated_python(self) -> None:
message = "中文 العربية русский Grüße"
# Escaped JSON becomes real Unicode inside the Python parser. Isolated
# mode ignores PYTHONUTF8, so a Windows locale encoding loses this event.
payload = self.run_hook(
COPILOT_HOOKS / "error-occurred.sh",
json.dumps({"error": {"message": message}}, ensure_ascii=True),
)
context = payload.get("hookSpecificOutput", {}).get("additionalContext", "")
self.assertIn(message, context)
@unittest.skipUnless(SH, "sh is not available")
class CodexPythonIsolationTests(unittest.TestCase):
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory()
self.cwd = Path(self._tmp.name)
(self.cwd / "task_plan.md").write_text(
"# Task Plan\n### Phase 1: Work\n**Status:** in_progress\n",
encoding="utf-8",
)
(self.cwd / "progress.md").write_text("# Progress\n", encoding="utf-8")
(self.cwd / "hashlib.py").write_text(
"open('PLANTED_hashlib', 'w').close()\nraise RuntimeError('shadow loaded')\n",
encoding="utf-8",
)
def tearDown(self) -> None:
self._tmp.cleanup()
def run_hook(self, name: str, cwd: Path | None = None) -> subprocess.CompletedProcess[str]:
hook_cwd = self.cwd if cwd is None else cwd
env = dict(os.environ, PYTHONUTF8="1")
env["PYTHON_BIN"] = sys.executable
env["PWF_PLAN_ROOT"] = str(hook_cwd)
return subprocess.run(
[str(SH), str(CODEX_HOOKS / name)],
cwd=str(hook_cwd),
env=env,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=60,
)
def test_codex_shell_python_ignores_project_hashlib_module(self) -> None:
cases = (
("user-prompt-submit.sh", "ACTIVE PLAN", "stdout"),
("pre-tool-use.sh", "# Task Plan", "stderr"),
("session-start.sh", "ACTIVE PLAN", "stdout"),
)
for name, expected, stream in cases:
with self.subTest(hook=name):
marker = self.cwd / "PLANTED_hashlib"
marker.unlink(missing_ok=True)
result = self.run_hook(name)
self.assertEqual(0, result.returncode, result.stderr)
self.assertFalse(marker.exists(), f"{name} imported project hashlib.py")
self.assertIn(expected, getattr(result, stream))
def test_codex_unicode_plan_root_survives_isolated_python(self) -> None:
project = self.cwd / "中文"
project.mkdir()
shutil.copyfile(self.cwd / "task_plan.md", project / "task_plan.md")
for name in ("user-prompt-submit.sh", "session-start.sh"):
with self.subTest(hook=name):
result = self.run_hook(name, cwd=project)
self.assertEqual(0, result.returncode, result.stderr)
self.assertIn("ACTIVE PLAN", result.stdout)
self.assertIn("# Task Plan", result.stdout)
class AdapterPythonIsolationContractTests(unittest.TestCase):
def test_every_adapter_python_invocation_uses_isolated_mode(self) -> None:
for script in PYTHON_SHELL_HOOKS:
with self.subTest(hook=script.relative_to(REPO)):
text = script.read_text(encoding="utf-8")
invocations = [
line
for line in text.splitlines()
if "$($PYTHON" in line or "| $PYTHON" in line
]
self.assertTrue(invocations, f"no Python invocation found in {script}")
for line in invocations:
self.assertIn(
"$PYTHON -I -X utf8 ",
line,
f"non-isolated Python invocation in {script.relative_to(REPO)}: {line}",
)
def test_every_codex_shell_python_invocation_uses_isolated_mode(self) -> None:
variables = ('"$PYTHON_BIN"', '"$PWF_PYTHON"', '"$PIN_PYTHON"', '"$_tp_candidate"')
for script in CODEX_PYTHON_SHELL_HOOKS:
with self.subTest(hook=script.relative_to(REPO)):
text = script.read_text(encoding="utf-8")
invocations = [
line
for line in text.splitlines()
if any(variable in line for variable in variables)
and (" -c " in line or (".py\"" in line and " -f " not in line))
]
self.assertTrue(invocations, f"no Python invocation found in {script}")
for line in invocations:
self.assertIn(
" -I -X utf8 ",
line,
f"non-isolated Python invocation in {script.relative_to(REPO)}: {line}",
)
if __name__ == "__main__":
unittest.main()
+4 -2
View File
@@ -210,8 +210,10 @@ def test_empty_planning_directory_and_pointer_are_read_only(runtime, tmp_path):
@pytest.mark.parametrize("pointer_bytes,active", [
(b"alpha\r\n", True), (b"missing\n", False),
(b"../alpha\n", False), (b"", False),
(b"alpha" + bytes((13, 10)), True),
(bytes((239, 187, 191)) + b"alpha" + bytes((10,)), True),
(b"missing" + bytes((10,)), False),
(b"../alpha" + bytes((10,)), False), (b"", False),
])
def test_listing_preserves_read_only_pointer(runtime, tmp_path, pointer_bytes, active):
plan_file = plan(tmp_path, "alpha", "### Phase 1: Work [pending]\n")
+214
View File
@@ -0,0 +1,214 @@
"""CLI regressions for read-only IDE sync verification on temporary repositories."""
from __future__ import annotations
import os
import runpy
import shutil
import subprocess
import sys
from pathlib import Path
import pytest
SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "sync-ide-folders.py"
def seed_manifests(root: Path, manifests, ide_names) -> None:
canonical = root / "skills" / "planning-with-files"
canonical.mkdir(parents=True, exist_ok=True)
for ide in ide_names:
(root / ide).mkdir(parents=True, exist_ok=True)
for key, target in manifests[ide].items():
relative_source = key.split("__extra_")[0]
content = f"fixture: {relative_source}\n".encode("utf-8")
for path in (canonical / relative_source, root / target):
path.parent.mkdir(parents=True, exist_ok=True)
path.write_bytes(content)
@pytest.fixture
def sync_repo(tmp_path: Path):
# Exercise the real manifest and CLI, without importing or executing any hooks.
manifests = runpy.run_path(str(SCRIPT_PATH))["IDE_MANIFESTS"]
root = tmp_path / "repo with spaces 計畫"
seed_manifests(root, manifests, (".", ".cursor"))
skill = root / ".cursor" / "skills" / "planning-with-files" / "SKILL.md"
skill.write_bytes(b"IDE-specific skill; do not overwrite\n")
hook = root / ".cursor" / "hooks" / "custom.json"
hook.parent.mkdir()
hook.write_bytes(b'{"custom": true}\n')
return root, root / "skills" / "planning-with-files", manifests
def snapshot(root: Path) -> dict:
# Reads can update atime; compare paths, bytes, permissions and mtimes instead.
result = {}
for path in [root, *root.rglob("*")]:
stat = path.stat()
result[path.relative_to(root).as_posix()] = (
stat.st_mode,
stat.st_mtime_ns,
path.read_bytes() if path.is_file() else None,
)
return result
def run_sync(root: Path, *args: str) -> subprocess.CompletedProcess:
return subprocess.run(
[sys.executable, str(SCRIPT_PATH), *args],
cwd=root,
capture_output=True,
text=True,
encoding="utf-8",
env={**os.environ, "PYTHONIOENCODING": "utf-8"},
timeout=15,
check=False,
)
def run_read_only(root: Path, *args: str) -> subprocess.CompletedProcess:
before = snapshot(root)
result = run_sync(root, *args)
assert snapshot(root) == before, "Read-only command changed the fixture tree"
assert result.stderr == "", result.stderr
return result
@pytest.mark.parametrize("content", [b"canonical\n", b""], ids=["text", "empty-file"])
def test_verify_matching_files_succeeds_without_writes(sync_repo, content) -> None:
root, canonical, manifests = sync_repo
key = "templates/findings.md"
(canonical / key).write_bytes(content)
(root / manifests[".cursor"][key]).write_bytes(content)
result = run_read_only(root, "--verify")
assert result.returncode == 0, result.stdout
assert "All IDE folders are in sync." in result.stdout
@pytest.mark.parametrize("target_present", [True, False], ids=["target-present", "both-missing"])
def test_verify_missing_source_fails_without_writes(sync_repo, target_present) -> None:
root, canonical, manifests = sync_repo
key = "templates/findings.md"
(canonical / key).unlink()
if not target_present:
(root / manifests[".cursor"][key]).unlink()
result = run_read_only(root, "--verify")
assert result.returncode == 1, result.stdout
assert f"MISSING SOURCE: {Path('skills/planning-with-files') / key}" in result.stdout
assert "All IDE folders are in sync." not in result.stdout
cursor_section = result.stdout.split(" .cursor/\n", 1)[1].split("\n\n", 1)[0]
assert "(up to date)" not in cursor_section
assert "Restore the missing canonical files" in result.stdout
def test_verify_shared_missing_source_reports_each_affected_entry(sync_repo) -> None:
root, canonical, manifests = sync_repo
seed_manifests(root, manifests, (".gemini",))
(canonical / "templates/findings.md").unlink()
result = run_read_only(root, "--verify")
assert result.returncode == 1, result.stdout
assert result.stdout.count("MISSING SOURCE:") == 2
assert "2 sync entry/entries" in result.stdout
def test_verify_empty_canonical_tree_does_not_report_success(sync_repo) -> None:
root, canonical, _ = sync_repo
for path in canonical.rglob("*"):
if path.is_file():
path.unlink()
result = run_read_only(root, "--verify")
assert result.returncode == 1, result.stdout
assert "MISSING SOURCE:" in result.stdout
assert "(up to date)" not in result.stdout
assert "All IDE folders are in sync." not in result.stdout
@pytest.mark.parametrize("remove_parent", [False, True], ids=["file", "parent-directory"])
def test_verify_missing_destination_fails_without_recreating_it(sync_repo, remove_parent) -> None:
root, _, manifests = sync_repo
target = root / manifests[".cursor"]["templates/findings.md"]
if remove_parent:
shutil.rmtree(target.parent)
else:
target.unlink()
result = run_read_only(root, "--verify")
assert result.returncode == 1, result.stdout
assert f"MISSING: {target.relative_to(root)}" in result.stdout
assert "DRIFT DETECTED:" in result.stdout
def test_verify_content_drift_fails_without_repairing_it(sync_repo) -> None:
root, _, manifests = sync_repo
target = root / manifests[".cursor"]["templates/findings.md"]
target.write_bytes(b"stale mirror\n")
result = run_read_only(root, "--verify")
assert result.returncode == 1, result.stdout
assert f"DRIFT: {target.relative_to(root)}" in result.stdout
assert "DRIFT DETECTED: 1 file(s) out of sync." in result.stdout
def test_verify_still_skips_absent_ide_directories(sync_repo) -> None:
root, canonical, _ = sync_repo
shutil.rmtree(root / ".cursor")
# Only the absent IDE references this source in the remaining fixture.
(canonical / "templates/findings.md").unlink()
result = run_read_only(root, "--verify")
assert result.returncode == 0, result.stdout
assert "All IDE folders are in sync." in result.stdout
assert not (root / ".cursor").exists()
def test_verify_reports_other_problems_alongside_missing_sources(sync_repo) -> None:
root, canonical, manifests = sync_repo
(canonical / "templates/findings.md").unlink()
missing = Path(manifests[".cursor"]["templates/progress.md"])
drifted = Path(manifests[".cursor"]["templates/task_plan.md"])
(root / missing).unlink()
(root / drifted).write_bytes(b"stale plan template\n")
result = run_read_only(root, "--verify")
assert result.returncode == 1, result.stdout
assert "MISSING SOURCE:" in result.stdout
assert f"MISSING: {missing}" in result.stdout
assert f"DRIFT: {drifted}" in result.stdout
assert "Run 'python scripts/sync-ide-folders.py' to fix." not in result.stdout
def test_verify_with_dry_run_still_rejects_missing_sources(sync_repo) -> None:
root, canonical, _ = sync_repo
(canonical / "templates/findings.md").unlink()
result = run_read_only(root, "--verify", "--dry-run")
assert result.returncode == 1, result.stdout
assert "MISSING SOURCE:" in result.stdout
def test_verify_missing_canonical_directory_keeps_existing_error(sync_repo) -> None:
root, canonical, _ = sync_repo
shutil.rmtree(canonical)
result = run_read_only(root, "--verify")
assert result.returncode == 1, result.stdout
assert "Error: Canonical source not found" in result.stdout
@pytest.mark.parametrize("dry_run", [False, True], ids=["sync", "dry-run"])
def test_non_verify_modes_keep_existing_copy_behavior(sync_repo, dry_run) -> None:
root, canonical, manifests = sync_repo
missing_key, stale_key = "templates/findings.md", "templates/progress.md"
missing = root / manifests[".cursor"][missing_key]
stale = root / manifests[".cursor"][stale_key]
missing.unlink()
stale.write_bytes(b"stale\n")
if dry_run:
result = run_read_only(root, "--dry-run")
assert result.returncode == 0, result.stdout
assert "This was a dry run. No files were modified." in result.stdout
else:
result = run_sync(root)
assert result.returncode == 0, result.stdout + result.stderr
assert missing.read_bytes() == (canonical / missing_key).read_bytes()
assert stale.read_bytes() == (canonical / stale_key).read_bytes()
skill = root / ".cursor" / "skills" / "planning-with-files" / "SKILL.md"
hook = root / ".cursor" / "hooks" / "custom.json"
assert skill.read_bytes() == b"IDE-specific skill; do not overwrite\n"
assert hook.read_bytes() == b'{"custom": true}\n'
assert run_read_only(root, "--verify").returncode == 0