Compare commits

...
5 Commits
Author SHA1 Message Date
OthmanAdi 09740f7293 release: v3.10.2
Version bump across the 19 parity targets, CHANGELOG, CONTRIBUTORS and the
README releases table. Ships PR #223, #222 and #224 by @Whxuan0701 plus the
three defects the merge audit turned up.
2026-08-19 19:27:21 +02:00
OthmanAdi ee6021bcfb fix: honor the planning opt-out on the Cursor route and keep the disabled Copilot hook neutral
The #195 opt-out lives in scripts/inject-plan.sh, and the Cursor hooks read
task_plan.md directly instead of dispatching to it, so PLANNING_DISABLED=1
never reached any of the eight. Each guard reproduces its own hook's
no-plan-file output, so the Cursor protocol shape is unchanged: PreToolUse
still answers {"decision": "allow"} because that is what it emits
unconditionally today, and the other three stay silent.

Three defects found while auditing #222, #223 and #224:

- The Copilot PreToolUse guard answered permissionDecision "allow" on the
  disabled path, so setting the variable to make planning inert also handed
  every tool call a blanket approval. Both copies now emit {}, matching
  their own no-plan-file path, which returns the decision to Copilot.
- .cursor/hooks/stop.ps1 was the last copy the #191 zero-phase guard never
  reached. It answered "0/0 phases done" and auto-continued on a plan that
  was never phase-structured.
- .github/hooks/scripts/error-occurred.ps1 read stdin into $input, which is
  PowerShell's automatic pipeline variable. Under -File the assignment does
  not stick, so the JSON parse always saw an empty string and the hook has
  never logged an error on Windows. Reproduced under pwsh 7 and Windows
  PowerShell 5.1 before the rename.

The opt-out tests now run every hook twice, unset and set, and fail if the
unset run is already inert. The merged versions asserted only the disabled
run, which a fleet gutted to unconditional {} also passed. That baseline is
what caught the $input bug.
2026-08-19 19:27:00 +02:00
WeiHaoxuan 5898865548 fix: honor planning opt-out in Copilot hooks 2026-08-19 18:46:27 +02:00
WeiHaoxuan c3615529e4 fix: ignore unstructured Copilot PowerShell plans 2026-08-19 18:46:21 +02:00
WeiHaoxuan 79ab59b325 test: use active Python for Hermes probe 2026-08-19 18:45:57 +02:00
42 changed files with 413 additions and 26 deletions
+1 -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.10.1"
version: "3.10.2"
---
# Planning with Files
+1 -1
View File
@@ -10,7 +10,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.10.1"
"version": "3.10.2"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.10.1",
"version": "3.10.2",
"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",
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"${CODEBUDDY_PLUGIN_ROOT}/scripts/inject-plan.sh\" \"$HOME/.codebuddy/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.10.1"
version: "3.10.2"
---
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.10.1"
version: "3.10.2"
---
+4
View File
@@ -1,6 +1,10 @@
# planning-with-files: Post-tool-use hook for Cursor (PowerShell)
# Reminds the agent to update task_plan.md after file modifications.
# Issue #195 opt-out. The disabled branch reproduces this hook's own
# no-plan-file behaviour, so the Cursor protocol shape never changes.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
if (Test-Path "task_plan.md") {
Write-Output "[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."
}
+4
View File
@@ -2,6 +2,10 @@
# planning-with-files: Post-tool-use hook for Cursor
# Reminds the agent to update task_plan.md after file modifications.
# Issue #195 opt-out. The disabled branch reproduces this hook's own
# no-plan-file behaviour, so the Cursor protocol shape never changes.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
if [ -f task_plan.md ]; then
echo "[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."
fi
+7
View File
@@ -2,6 +2,13 @@
# Reads the first 30 lines of task_plan.md to keep goals in context.
# Returns {"decision": "allow"} — this hook never blocks tools.
# Issue #195 opt-out. The disabled branch reproduces this hook's own
# no-plan-file behaviour, so the Cursor protocol shape never changes.
if ($env:PLANNING_DISABLED -eq '1') {
Write-Output '{"decision": "allow"}'
exit 0
}
$PlanFile = "task_plan.md"
if (Test-Path $PlanFile) {
+4
View File
@@ -3,6 +3,10 @@
# Reads the first 30 lines of task_plan.md to keep goals in context.
# Returns {"decision": "allow"} — this hook never blocks tools.
# Issue #195 opt-out. The disabled branch reproduces this hook's own
# no-plan-file behaviour, so the Cursor protocol shape never changes.
[ "${PLANNING_DISABLED:-}" = "1" ] && { echo '{"decision": "allow"}'; exit 0; }
PLAN_FILE="task_plan.md"
if [ -f "$PLAN_FILE" ]; then
+11
View File
@@ -3,6 +3,10 @@
# Returns followup_message to auto-continue if phases are incomplete.
# Always exits 0 — uses JSON stdout for control.
# Issue #195 opt-out. The disabled branch reproduces this hook's own
# no-plan-file behaviour, so the Cursor protocol shape never changes.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
$PlanFile = "task_plan.md"
if (-not (Test-Path $PlanFile)) {
@@ -25,6 +29,13 @@ if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
# issue #191: no "### Phase" headings -> not phase-structured. Avoid the false
# "0/0 phases done ... continue working" auto-continue message. The sh twin has
# carried this since v3.2.0; this file was the one copy the fix never reached.
if ($TOTAL -eq 0) {
exit 0
}
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
Write-Host "{`"followup_message`": `"[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting.`"}"
exit 0
+4
View File
@@ -4,6 +4,10 @@
# Returns followup_message to auto-continue if phases are incomplete.
# Always exits 0 — uses JSON stdout for control.
# Issue #195 opt-out. The disabled branch reproduces this hook's own
# no-plan-file behaviour, so the Cursor protocol shape never changes.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
PLAN_FILE="task_plan.md"
if [ ! -f "$PLAN_FILE" ]; then
+4
View File
@@ -2,6 +2,10 @@
# Injects plan context on every user message.
# Critical for session recovery after /clear — dumps actual content, not just advice.
# Issue #195 opt-out. The disabled branch reproduces this hook's own
# no-plan-file behaviour, so the Cursor protocol shape never changes.
if ($env:PLANNING_DISABLED -eq '1') { exit 0 }
# --- PWF_PLAN_ROOT: absolute plan-root binding (issue #212). ---
# A thread whose cwd is a shared PARENT of the real project can be pinned to
# the nested project root; every planning-state read below goes through the
+4
View File
@@ -3,6 +3,10 @@
# Injects plan context on every user message.
# Critical for session recovery after /clear — dumps actual content, not just advice.
# Issue #195 opt-out. The disabled branch reproduces this hook's own
# no-plan-file behaviour, so the Cursor protocol shape never changes.
[ "${PLANNING_DISABLED:-}" = "1" ] && exit 0
# --- PWF_PLAN_ROOT: absolute plan-root binding (issue #212). ---
# A thread whose cwd is a shared PARENT of the real project can be pinned to
# the nested project root; every planning-state read below goes through the
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.10.1"
version: "3.10.2"
---
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.10.1"
version: "3.10.2"
---
# Planning with Files
+10
View File
@@ -8,6 +8,11 @@ $OutputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$InputData = [Console]::In.ReadToEnd()
if ($env:PLANNING_DISABLED -eq '1') {
Write-Output '{}'
exit 0
}
$PlanFile = "task_plan.md"
if (-not (Test-Path $PlanFile)) {
@@ -32,6 +37,11 @@ if ($COMPLETE -eq 0 -and $IN_PROGRESS -eq 0 -and $PENDING -eq 0) {
$PENDING = ([regex]::Matches($content, "\[pending\]")).Count
}
if ($TOTAL -eq 0) {
Write-Output '{}'
exit 0
}
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
$msg = "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
$output = @{
+2
View File
@@ -7,6 +7,8 @@
# Read stdin (required — Copilot pipes JSON to stdin)
INPUT=$(cat)
[ "${PLANNING_DISABLED:-}" = "1" ] && { echo '{}'; exit 0; }
PLAN_FILE="task_plan.md"
if [ ! -f "$PLAN_FILE" ]; then
+10 -3
View File
@@ -1,6 +1,11 @@
# planning-with-files: Error hook for GitHub Copilot (Windows PowerShell)
# Logs errors to task_plan.md when the agent encounters an error.
if ($env:PLANNING_DISABLED -eq '1') {
Write-Output '{}'
exit 0
}
$planFile = "task_plan.md"
if (-not (Test-Path $planFile)) {
@@ -8,11 +13,13 @@ if (-not (Test-Path $planFile)) {
exit 0
}
# Read stdin
$input = [Console]::In.ReadToEnd()
# Read stdin. Do not name this $input: that is PowerShell's automatic pipeline
# variable, and under `-File` the assignment does not stick, so the hook read an
# empty string and never logged an error on Windows.
$InputData = [Console]::In.ReadToEnd()
try {
$data = $input | ConvertFrom-Json
$data = $InputData | ConvertFrom-Json
$errorMsg = ""
if ($data.error -is [PSCustomObject]) {
$errorMsg = $data.error.message
+2
View File
@@ -6,6 +6,8 @@
# Read stdin (required — Copilot pipes JSON to stdin)
INPUT=$(cat)
[ "${PLANNING_DISABLED:-}" = "1" ] && { echo '{}'; exit 0; }
PLAN_FILE="task_plan.md"
if [ ! -f "$PLAN_FILE" ]; then
+5
View File
@@ -7,6 +7,11 @@ $OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
$InputData = [Console]::In.ReadToEnd()
if ($env:PLANNING_DISABLED -eq '1') {
Write-Output '{}'
exit 0
}
$output = @{
hookSpecificOutput = @{
hookEventName = "PostToolUse"
+2
View File
@@ -6,5 +6,7 @@
# Read stdin (required — Copilot pipes JSON to stdin)
INPUT=$(cat)
[ "${PLANNING_DISABLED:-}" = "1" ] && { echo '{}'; exit 0; }
echo '{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."}}'
exit 0
+7
View File
@@ -8,6 +8,13 @@ $OutputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$InputData = [Console]::In.ReadToEnd()
# Disabled means no opinion, not blanket approval: emit the same empty object the
# no-plan-file path emits so Copilot's own permission flow decides.
if ($env:PLANNING_DISABLED -eq '1') {
Write-Output '{}'
exit 0
}
$PlanFile = "task_plan.md"
if (-not (Test-Path $PlanFile)) {
+4
View File
@@ -7,6 +7,10 @@
# Read stdin (required — Copilot pipes JSON to stdin)
INPUT=$(cat)
# Disabled means no opinion, not blanket approval: emit the same empty object the
# no-plan-file path emits so Copilot's own permission flow decides.
[ "${PLANNING_DISABLED:-}" = "1" ] && { echo '{}'; exit 0; }
PLAN_FILE="task_plan.md"
if [ ! -f "$PLAN_FILE" ]; then
+5
View File
@@ -8,6 +8,11 @@ $OutputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$InputData = [Console]::In.ReadToEnd()
if ($env:PLANNING_DISABLED -eq '1') {
Write-Output '{}'
exit 0
}
$PlanFile = "task_plan.md"
$SkillDir = ".github/skills/planning-with-files"
+2
View File
@@ -7,6 +7,8 @@
# Read stdin (required — Copilot pipes JSON to stdin)
INPUT=$(cat)
[ "${PLANNING_DISABLED:-}" = "1" ] && { echo '{}'; exit 0; }
PLAN_FILE="task_plan.md"
SKILL_DIR=".github/skills/planning-with-files"
PYTHON=""
+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.10.1"
version: "3.10.2"
---
> Hermes note: lifecycle automation for this skill is provided by the Hermes adapter plugin in `.hermes/plugins/planning-with-files/`.
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.mastracode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.10.1"
version: "3.10.2"
---
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.config/opencode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.opencode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.10.1"
version: "3.10.2"
---
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.10.1",
"version": "3.10.2",
"description": "Persistent file-based planning for AI coding agents: keeps task_plan.md, findings.md and progress.md on disk so the plan survives /clear, context loss and compaction. Manus-style. Ships the skill plus a Pi Coding Agent extension.",
"keywords": [
"pi-package",
+24
View File
@@ -2,6 +2,30 @@
All notable changes to this project will be documented in this file.
## [3.10.2] - 2026-08-19
### Fixed
- **`PLANNING_DISABLED=1` did nothing on the GitHub Copilot route (PR #223, by @Whxuan0701).** The per-invocation opt-out from #195 reached the canonical, `.agents` and Codex routes in v3.9.0, but all ten Copilot entry points under `.github/hooks/scripts/` still read `task_plan.md` and emitted planning context whatever the variable said. That is the failure #195 was filed about: a one-shot task that merely shares a working directory with an unrelated plan gets that plan attached on every session start, matched tool call, error and stop, with no way to turn it off. All five shell and five PowerShell hooks now exit before touching the plan file.
- **The same opt-out was inoperative on all eight Cursor hooks.** The Cursor route reads `task_plan.md` directly rather than dispatching to `scripts/inject-plan.sh`, which is where the #195 guard lives, so `PLANNING_DISABLED=1` never reached `pre-tool-use`, `post-tool-use`, `stop` or `user-prompt-submit` in either shell or PowerShell. Each guard reproduces its own hook's no-plan-file output, so the Cursor protocol shape is unchanged: `PreToolUse` still answers `{"decision": "allow"}` because that is what it emits unconditionally today, and the other three stay silent. `.gemini` is deliberately behind and is not covered.
- **Disabling the skill made Copilot's `PreToolUse` more permissive than leaving it on.** The merged guard answered `permissionDecision: allow` on the disabled path, so a user who set the variable to make planning inert also handed every tool call a blanket approval it would not otherwise have had. Both the shell and PowerShell hooks now emit `{}`, matching their own no-plan-file path, which returns the decision to Copilot.
- **The Copilot PowerShell stop hook reported "Task incomplete (0/0 phases done)" for a plan with no phase headings (PR #222, by @Whxuan0701).** The #191 guard shipped to `agent-stop.sh` and to the canonical scripts and never reached `agent-stop.ps1`, so Windows Copilot users kept getting the false nag the fix was written to remove.
- **`.cursor/hooks/stop.ps1` was the last copy the #191 fix never reached.** It answered `0/0 phases done` and auto-continued on a plan that was never phase-structured. A repository-wide sweep of every script that emits a `(N/M phases done)` message now finds no unguarded copy left.
- **The Copilot PowerShell error hook had never logged an error on Windows.** `error-occurred.ps1` read stdin into `$input`, which is PowerShell's automatic pipeline variable: under `-File` the assignment does not stick, so the JSON parse always saw an empty string and the hook emitted `{}` every time. Reproduced under both pwsh 7 and Windows PowerShell 5.1 before the rename.
- **The Hermes determinism probe could not run on a host without a `python` alias (PR #224, by @Whxuan0701).** `tests/test_injection_determinism.py` spawned a hardcoded `python`, which does not exist on a default macOS setup or on any host that ships only `python3`, so the probe raised `FileNotFoundError` instead of testing anything. It now reuses `sys.executable`.
### Changed
- The opt-out tests run every hook twice, once with the variable unset and once with it set, and fail if the unset run is already inert. The merged versions asserted only the disabled run, which a fleet of hooks that emit `{}` unconditionally would also have passed: gutting all ten Copilot hooks left the suite green. That is the silent-death class behind the v3.6.0 realpath failure and the v3.8.0 Stop hook, and it is now the one thing these tests cannot miss. The `error-occurred.ps1` `$input` bug is what the new baseline caught first.
### Verification
- Full Python suite: 430 passed, 11 skipped, 492 subtests passed. Baseline before the three merges was 424 passed, 11 skipped, 474 subtests.
- Each fix was mutation-tested rather than assumed: stripping all ten Copilot guards fails 9 assertions, gutting the hook fleet to unconditional `{}` fails 6, restoring `$input` in the error hook fails the anti-vacuity baseline by name, and stripping the eight Cursor guards plus the `stop.ps1` phase guard fails 9.
- `#222` and `#223` both edit `agent-stop.ps1`. The combined tree was tested after both landed, not only in isolation.
- All four `.ps1` files that carry non-ASCII keep their UTF-8 BOM, every touched script is pure LF, and `sh -n` parses all nine shell hooks.
- `scripts/sync-ide-folders.py --verify` clean; `scripts/bump-version.py 3.10.2` reports 19 changed, 0 errors.
### Thanks
- Haoxuan sent three single-commit PRs rather than one bundle: the Copilot opt-out gap (#223), the missing zero-phase guard on the Copilot PowerShell stop hook (#222), and the hardcoded interpreter in the Hermes probe (#224). Each arrived with a test that executes the real script. Auditing them is what surfaced the Cursor route, the `PreToolUse` permission widening and the `$input` bug.
## [3.10.1] - 2026-08-14
### Fixed
+1 -1
View File
@@ -7,7 +7,7 @@ authors:
- family-names: Adi
given-names: Ahmad Othman Ammar
alias: OthmanAdi
version: "3.10.1"
version: "3.10.2"
date-released: "2026-08-14"
license: MIT
url: "https://github.com/OthmanAdi/planning-with-files"
+4 -2
View File
@@ -372,6 +372,8 @@ Thank you to everyone who reported issues, provided feedback, and helped test fi
- [@marcmuon](https://github.com/marcmuon) (Marc Kelechava) - Issue #195 (one-shot `codex exec` sessions sharing a cwd with an incomplete plan got hijacked and mutated orchestrator-owned plan files; the report's reproductions, root-cause file list, and acceptance criteria shipped directly as the `PLANNING_DISABLED=1` opt-out in v3.4.0)
- [@mfehlhaber](https://github.com/mfehlhaber): Issue #220 (identified that the Codex POSIX `SessionStart` and `UserPromptSubmit` routes bypassed the JSON adapter, causing planning context beginning with `[` to be rejected as invalid event JSON; fixed in v3.10.1)
- [@Whxuan0701](https://github.com/Whxuan0701) (WeiHaoxuan) - [PR #223](https://github.com/OthmanAdi/planning-with-files/pull/223), [PR #222](https://github.com/OthmanAdi/planning-with-files/pull/222), [PR #224](https://github.com/OthmanAdi/planning-with-files/pull/224) (found that the `PLANNING_DISABLED=1` opt-out from #195 had never reached any of the ten GitHub Copilot hook entry points, that the #191 zero-phase guard was missing from the Copilot PowerShell stop hook, and that the Hermes determinism probe hardcoded `python` so it could not run where only `python3` exists; three single-commit PRs, each with a test that executes the real script. Auditing them surfaced three further defects fixed in the same release: the Cursor route had the same opt-out gap across all eight of its hooks, the disabled `PreToolUse` branch was widening Copilot's permissions rather than staying neutral, and `error-occurred.ps1` had never logged an error on Windows because it read stdin into PowerShell's automatic `$input` variable)
And many others who have starred, forked, and shared this project!
- **[@voidborne-d](https://github.com/voidborne-d)** - [PR #149](https://github.com/OthmanAdi/planning-with-files/pull/149)
@@ -398,6 +400,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
---
**Total Contributors:** 51+ and growing!
**Total Contributors:** 52+ and growing!
*Last updated: August 14, 2026*
*Last updated: August 19, 2026*
+2 -1
View File
@@ -402,7 +402,7 @@ The v3 line adds features aimed at long-running agentic runs. Each one is listed
- **SHA-256 plan attestation** (`/plan-attest`): locks `task_plan.md`; a tampered plan body is refused at injection.
- **Run ledger**: an append-only JSONL record of phase transitions that replaces the raw `progress.md` tail in v3 modes with a fixed-shape summary.
- **Host capability tiers**: hard block on Claude Code, Codex, and Continue; follow-up injection on Cursor, Pi, and Kiro; notify-only elsewhere.
- **Per-invocation opt-out** (`PLANNING_DISABLED=1`, v3.4.0): a one-shot session that merely shares a cwd with an incomplete plan skips all plan reading at every hook entry point.
- **Per-invocation opt-out** (`PLANNING_DISABLED=1`, v3.4.0): a one-shot session that merely shares a cwd with an incomplete plan skips all plan reading at every hook entry point. Covers the Copilot and Cursor routes since v3.10.2; `.gemini` is deliberately behind and does not honour it.
- **Absolute plan-root pin** (`PWF_PLAN_ROOT`, v3.9.0): binds a thread to a project root by absolute path, for agent threads whose cwd is a shared parent of the project they are actually working in. Ambiguous cwds refuse to inject rather than guessing.
### Environment variables
@@ -514,6 +514,7 @@ One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from
| Version | Highlights |
|---------|------------|
| **v3.10.2** | **`PLANNING_DISABLED=1` had never reached the GitHub Copilot or Cursor hooks** (PRs #223, #222 and #224, by @Whxuan0701). Both routes read `task_plan.md` directly instead of dispatching to the script that carries the #195 guard, so eighteen hook entry points ignored the opt-out entirely: a one-shot task sharing a working directory with an unrelated plan had no way to detach from it. Auditing the merge found three more: the disabled `PreToolUse` branch answered `permissionDecision: allow`, so turning the skill off widened Copilot's permissions instead of staying neutral; `.cursor/hooks/stop.ps1` was the last copy the #191 zero-phase guard never reached, still auto-continuing on `0/0 phases done`; and `error-occurred.ps1` had never logged an error on Windows because it read stdin into `$input`, PowerShell's automatic pipeline variable, which does not hold the assignment under `-File`. The opt-out tests now run every hook with the variable unset as well as set, because the disabled-only versions stayed green against a fleet gutted to emit `{}`. Suite 424 to 430. |
| **v3.10.1** | **Codex context hooks now emit valid event JSON on Linux and macOS** (fixes #220, reported by @mfehlhaber). `SessionStart`, `UserPromptSubmit`, and `PreCompact` use the same adapter as Windows, so planning output beginning with `[` is no longer misread as malformed JSON. This release also aligns the tracked npm payload with the published 20-script package, corrects the release reference, and makes the version bumper safe to run without the gitignored ClawHub stage in a fresh clone. |
| **v3.10.0** | **Two sessions sharing one plan directory could silently destroy each other's work** (closes #217, reported by @dubes394). Both read `task_plan.md`, both write it back, and the later write discards the earlier one's phases while injection, `plan-doctor` and the Stop gate all read the result as an ordinary edit. Attestation could not cover it: it compares against a baseline a human approved once, not against what the hooks last observed, and it is a read side gate that cannot stop the stale write. The guard compares progress rather than hashes, because a hash comparison flags a single agent's own edit on its very next fire; checked items and completed phases only go up during normal work, so a decrease means work is gone. Verifying #130 alongside it exposed that every non-English install was a subset install, missing attestation, the Stop gate, the ledger, phase status and plan-doctor entirely, plus a Windows UTF-8 crash fix that never left the canonical skill. Closed additively, 60 files created and 0 overwritten, with the translator-owned scripts pinned so no future sync can English them. Also fixes a README top that showed five labels and no numbers on a phone. Suite 411 to 417. |
| **v3.9.0** | **A Codex thread whose cwd was a shared parent injected an unrelated project's plan on every hook fire** (closes #212, reported by @webwww123). Resolution was cwd relative with no notion of a thread, so the shared parent's pointer was the only one the hook could see. Adds `PWF_PLAN_ROOT` for an absolute plan root binding, which a cwd relative `PLAN_ID` slug structurally could not express, and refuses to inject when the cwd is ambiguous rather than guessing. Verifying the report exposed that `PLANNING_DISABLED=1` was inoperative on eleven of thirteen install routes, that the Stop hook could never find its script on six hosts, and that eight shipped PowerShell scripts could not be parsed by Windows PowerShell 5.1 at all, leaving Cursor injection and both Chinese variants' `init-session` dead on Windows. Also closes #211 (a provider error queued another request into the same failing provider, and the Pi status bar stopped tracking the plan after approval) and #210 (injection determinism now asserted, five routes normalized). Suite 311 to 411. |
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-ar/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.10.1"
version: "3.10.2"
---
# نظام تخطيط الملفات
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-de/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.10.1"
version: "3.10.2"
---
# Dateiplanungssystem
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-es/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.10.1"
version: "3.10.2"
---
# Sistema de Planificación con Archivos
+1 -1
View File
@@ -37,7 +37,7 @@ hooks:
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-zh/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.10.1"
version: "3.10.2"
---
+1 -1
View File
@@ -37,7 +37,7 @@ hooks:
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files-zht/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.10.1"
version: "3.10.2"
---
+1 -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.10.1"
version: "3.10.2"
---
# Planning with Files
+55
View File
@@ -0,0 +1,55 @@
"""Behavior tests for the GitHub Copilot AgentStop hooks."""
from __future__ import annotations
import json
import shutil
import subprocess
import tempfile
import unittest
from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parents[1]
AGENT_STOP_PS1 = REPO_ROOT / ".github" / "hooks" / "scripts" / "agent-stop.ps1"
POWERSHELL = (
shutil.which("pwsh")
or shutil.which("powershell.exe")
or shutil.which("powershell")
)
@unittest.skipUnless(POWERSHELL, "PowerShell is not available")
class CopilotAgentStopPowerShellTests(unittest.TestCase):
def test_unstructured_plan_emits_empty_json(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
cwd = Path(tmp)
(cwd / "task_plan.md").write_text(
"# Notes\n\nThis file has no phase structure.\n",
encoding="utf-8",
)
result = subprocess.run(
[
str(POWERSHELL),
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
str(AGENT_STOP_PS1),
],
cwd=cwd,
input="{}",
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=30,
)
self.assertEqual(0, result.returncode, result.stderr)
self.assertEqual({}, json.loads(result.stdout.lstrip("\ufeff")))
if __name__ == "__main__":
unittest.main()
+2 -1
View File
@@ -33,6 +33,7 @@ from __future__ import annotations
import os
import shutil
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path
@@ -373,7 +374,7 @@ class NoRawWallClockTests(unittest.TestCase):
# so it never received the v2.40 sed pass. Same contract, same fixture.
# Its package directory name contains a dash, so it cannot be imported
# by name; load it under a synthetic package instead.
result = self._run(["python", "-c", _HERMES_PROBE])
result = self._run([sys.executable, "-c", _HERMES_PROBE])
self.assertEqual(0, result.returncode, result.stderr)
self.assertIn("ACTIVE PLAN", result.stdout)
self._assert_normalized(result.stdout, ".hermes/plugins/planning-with-files")
+217 -1
View File
@@ -8,7 +8,9 @@ attachment path the issue reports) with and without the env var.
"""
from __future__ import annotations
import json
import os
import shutil
import subprocess
import sys
import tempfile
@@ -17,12 +19,21 @@ from pathlib import Path
REPO = Path(__file__).resolve().parent.parent
CODEX_HOOKS = REPO / ".codex" / "hooks"
COPILOT_HOOKS = REPO / ".github" / "hooks" / "scripts"
CURSOR_HOOKS = REPO / ".cursor" / "hooks"
SCRIPTS = REPO / "scripts"
POWERSHELL = (
shutil.which("pwsh")
or shutil.which("powershell.exe")
or shutil.which("powershell")
)
PLAN = "# Test Plan\n### Phase 1: something\n**Status:** in_progress\n"
def run_sh(script: Path, cwd: Path, disabled: bool) -> subprocess.CompletedProcess:
def run_sh(
script: Path, cwd: Path, disabled: bool, input_data: str = ""
) -> subprocess.CompletedProcess:
env = dict(os.environ)
env.pop("PLANNING_DISABLED", None)
if disabled:
@@ -31,6 +42,34 @@ def run_sh(script: Path, cwd: Path, disabled: bool) -> subprocess.CompletedProce
["sh", str(script)],
cwd=str(cwd),
env=env,
input=input_data,
capture_output=True,
text=True,
encoding="utf-8",
errors="replace",
timeout=60,
)
def run_powershell(
script: Path, cwd: Path, disabled: bool
) -> subprocess.CompletedProcess:
env = dict(os.environ)
env.pop("PLANNING_DISABLED", None)
if disabled:
env["PLANNING_DISABLED"] = "1"
return subprocess.run(
[
str(POWERSHELL),
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
str(script),
],
cwd=str(cwd),
env=env,
input='{"error":{"message":"fixture failure"}}',
capture_output=True,
text=True,
encoding="utf-8",
@@ -137,6 +176,55 @@ class PlanningDisabledOptOutTests(unittest.TestCase):
(self.cwd / "progress.md").read_text(encoding="utf-8"), "progress line\n"
)
def test_copilot_shell_hooks_skip_context_when_disabled(self) -> None:
# Each hook is run twice against the same fixture. Asserting only the
# disabled run would pass against a fleet of hooks that emit {} no
# matter what, which is the silent-death class this repo has shipped
# twice, so the enabled run is the anti-vacuity baseline: it has to
# produce the context that the disabled run must not.
live = 0
for name in (
"session-start.sh",
"pre-tool-use.sh",
"post-tool-use.sh",
"agent-stop.sh",
"error-occurred.sh",
):
with self.subTest(hook=name):
enabled = run_sh(
COPILOT_HOOKS / name,
self.cwd,
disabled=False,
input_data='{"error":{"message":"fixture failure"}}',
)
self.assertEqual(0, enabled.returncode, enabled.stderr)
enabled_output = json.loads(
enabled.stdout.lstrip("\ufeff")
).get("hookSpecificOutput", {})
if "additionalContext" in enabled_output:
live += 1
result = run_sh(
COPILOT_HOOKS / name,
self.cwd,
disabled=True,
input_data='{"error":{"message":"fixture failure"}}',
)
self.assertEqual(0, result.returncode, result.stderr)
payload = json.loads(result.stdout.lstrip("\ufeff"))
# Disabled means no opinion: no context, and for PreToolUse no
# permission decision either, so Copilot's own flow decides.
self.assertEqual({}, payload)
# error-occurred.sh JSON-escapes through python3 and goes quiet where
# that probe finds nothing, so four is the floor, not five.
self.assertGreaterEqual(
live,
4,
"no Copilot shell hook produced context with the opt-out unset; "
"the disabled-run assertions above cannot mean anything",
)
# --- Every distributed copy carries the guard ---
def test_all_check_complete_copies_carry_the_guard(self) -> None:
@@ -155,5 +243,133 @@ class PlanningDisabledOptOutTests(unittest.TestCase):
)
@unittest.skipUnless(POWERSHELL, "PowerShell is not available")
class CopilotPowerShellPlanningDisabledTests(unittest.TestCase):
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory()
self.cwd = Path(self._tmp.name)
(self.cwd / "task_plan.md").write_text(PLAN, encoding="utf-8")
(self.cwd / "progress.md").write_text("progress line\n", encoding="utf-8")
def tearDown(self) -> None:
self._tmp.cleanup()
def test_copilot_powershell_hooks_skip_context_when_disabled(self) -> None:
# None of the five PowerShell hooks shells out to escape JSON, so every
# one of them must produce context with the opt-out unset. A hook that
# goes quiet in both runs is dead, not disabled.
for name in (
"session-start.ps1",
"pre-tool-use.ps1",
"post-tool-use.ps1",
"agent-stop.ps1",
"error-occurred.ps1",
):
with self.subTest(hook=name):
enabled = run_powershell(
COPILOT_HOOKS / name, self.cwd, disabled=False
)
self.assertEqual(0, enabled.returncode, enabled.stderr)
enabled_output = json.loads(
enabled.stdout.lstrip("\ufeff")
).get("hookSpecificOutput", {})
self.assertIn(
"additionalContext",
enabled_output,
f"{name} emitted no context with the opt-out unset, so the "
"disabled-run assertion below proves nothing",
)
result = run_powershell(
COPILOT_HOOKS / name, self.cwd, disabled=True
)
self.assertEqual(0, result.returncode, result.stderr)
payload = json.loads(result.stdout.lstrip("\ufeff"))
# Disabled means no opinion: no context, and for PreToolUse no
# permission decision either, so Copilot's own flow decides.
self.assertEqual({}, payload)
CURSOR_HOOK_NAMES = (
"pre-tool-use",
"post-tool-use",
"stop",
"user-prompt-submit",
)
class CursorPlanningDisabledTests(unittest.TestCase):
"""The Cursor hooks read task_plan.md directly instead of dispatching to
scripts/inject-plan.sh, so the #195 opt-out never reached them. Each guard
reproduces its own hook's no-plan-file output: PreToolUse still answers
{"decision": "allow"} because that is what it emits unconditionally today,
and the other three stay silent.
"""
def setUp(self) -> None:
self._tmp = tempfile.TemporaryDirectory()
self.cwd = Path(self._tmp.name)
(self.cwd / "task_plan.md").write_text(PLAN, encoding="utf-8")
(self.cwd / "progress.md").write_text("progress line\n", encoding="utf-8")
def tearDown(self) -> None:
self._tmp.cleanup()
def _expected_disabled(self, name: str) -> str:
return '{"decision": "allow"}' if name == "pre-tool-use" else ""
def test_cursor_shell_hooks_go_inert_when_disabled(self) -> None:
for name in CURSOR_HOOK_NAMES:
with self.subTest(hook=f"{name}.sh"):
script = CURSOR_HOOKS / f"{name}.sh"
enabled = run_sh(script, self.cwd, disabled=False)
disabled = run_sh(script, self.cwd, disabled=True)
self.assertEqual(0, enabled.returncode, enabled.stderr)
self.assertEqual(0, disabled.returncode, disabled.stderr)
inert = self._expected_disabled(name)
self.assertNotEqual(
inert,
(enabled.stdout + enabled.stderr).strip(),
f"{name}.sh produced its inert output with the opt-out "
"unset, so the disabled assertion below proves nothing",
)
self.assertEqual(
inert, (disabled.stdout + disabled.stderr).strip()
)
@unittest.skipUnless(POWERSHELL, "PowerShell is not available")
def test_cursor_powershell_hooks_go_inert_when_disabled(self) -> None:
for name in CURSOR_HOOK_NAMES:
with self.subTest(hook=f"{name}.ps1"):
script = CURSOR_HOOKS / f"{name}.ps1"
enabled = run_powershell(script, self.cwd, disabled=False)
disabled = run_powershell(script, self.cwd, disabled=True)
self.assertEqual(0, enabled.returncode, enabled.stderr)
self.assertEqual(0, disabled.returncode, disabled.stderr)
inert = self._expected_disabled(name)
self.assertNotEqual(
inert,
(enabled.stdout + enabled.stderr).strip().lstrip(""),
f"{name}.ps1 produced its inert output with the opt-out "
"unset, so the disabled assertion below proves nothing",
)
self.assertEqual(
inert,
(disabled.stdout + disabled.stderr).strip().lstrip(""),
)
@unittest.skipUnless(POWERSHELL, "PowerShell is not available")
def test_cursor_stop_ps1_is_silent_on_an_unstructured_plan(self) -> None:
# issue #191, the copy the fix never reached. stop.sh has carried the
# zero-phase guard since v3.2.0; stop.ps1 answered "0/0 phases done"
# and auto-continued on a plan that was never phase-structured.
(self.cwd / "task_plan.md").write_text(
"# Notes\n\nThis file has no phase structure.\n", encoding="utf-8"
)
result = run_powershell(CURSOR_HOOKS / "stop.ps1", self.cwd, disabled=False)
self.assertEqual(0, result.returncode, result.stderr)
self.assertEqual("", (result.stdout + result.stderr).strip().lstrip(""))
if __name__ == "__main__":
unittest.main()