planning-with-files 3.16.1 → 3.18.3

package/README.md

@@ -1,13 +1,25 @@
-# planning-with-files
+<div align="center">
+  <img src="https://raw.githubusercontent.com/OthmanAdi/planning-with-files/master/media/v3-banner-1400.jpg" alt="planning-with-files: task_plan.md, findings.md, and progress.md as three stone tablets" width="100%">
+</div>
 
-> **Your agent's context window dies. The plan does not.**
+<h1 align="center">Planning with Files</h1>
 
-Persistent file-based planning for AI coding agents. The skill keeps `task_plan.md`, `findings.md` and `progress.md` on disk. After `/plan-execute`, Pi lifecycle hooks inject selected project planning context so the plan survives context loss, `/clear`, crashes and compaction. Automatic recovery reads project files only. Reading same-project local session records for aggregate counts or bounded replay requires an explicit catchup mode.
+<p align="center">
+  <strong>The planning skill your agent cannot ignore.</strong><br>
+  Your agent's context window dies. The plan does not.
+</p>
 
-This is the npm distribution of [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files), which installs across 60+ agents via the Agent Skills standard. The package ships:
+Persistent file-based planning for AI coding agents. Keep the plan, research and progress in your project so work can continue after context loss, `/clear`, crashes or compaction.
 
-- the planning skill itself: `SKILL.md`, `scripts/` and `templates/`
-- a [Pi Coding Agent](https://pi.dev) extension providing Claude-style lifecycle automation
+| File | Purpose |
+| --- | --- |
+| `task_plan.md` | Goals, phases and decisions |
+| `findings.md` | Research and discoveries |
+| `progress.md` | Work completed, checks and next steps |
+
+This is the npm distribution of [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files), available across 60+ agents via the Agent Skills standard. It includes the planning skill, scripts and templates. Supported agent integrations add lifecycle hooks that bring selected planning context back into the session.
+
+Automatic recovery reads project files only. Reading same-project local session records for aggregate counts or bounded replay requires an explicit catchup mode.
 
 ## Installation
 
@@ -19,19 +31,40 @@ npm install planning-with-files
 
 Places the skill, scripts and templates under `node_modules/planning-with-files/`. Use this to pin an exact version into a project, or to copy `SKILL.md` and `scripts/` into your agent's skills directory yourself. It does not register hooks on its own.
 
-### Pi Install
+### Agent integrations
 
-```bash
-pi install npm:planning-with-files
+Claude Code gets the full surface (skill, hooks, slash commands) through the plugin route, and 60+ other agents install in one line. See the [main README](https://github.com/OthmanAdi/planning-with-files#quick-install).
+
+## Usage
+
+Once the skill is installed for your agent, start with:
+
+```text
+Use the planning-with-files skill to help me with this task.
+```
+
+The workflow centers on three files in your project:
+
+```text
+your-project/
+├── task_plan.md
+├── findings.md
+└── progress.md
 ```
 
-Wires up the skill, the extension and the status bar automatically.
+## Pi Coding Agent integration
 
-### Other agents
+The package also bundles a [Pi Coding Agent](https://pi.dev) extension for lifecycle automation and a planning status bar.
 
-Claude Code gets the full surface (skill, hooks, slash commands) through the plugin route, and 60+ other agents install in one line. See the [main README](https://github.com/OthmanAdi/planning-with-files#quick-install).
+### Install in Pi
+
+```bash
+pi install npm:planning-with-files
+```
 
-### Manual Install
+Pi discovers the skill and extension from the installed package.
+
+For a local repository checkout:
 
 ```bash
 # From the planning-with-files repo root
@@ -45,31 +78,17 @@ Or add to `.pi/settings.json`:
 }
 ```
 
----
-
-## Usage
-
-Pi discovers the skill and extension from the installed package.
-
-Start with:
-
-```text
-Use the planning-with-files skill to help me with this task.
-```
-
-Or:
+You can also invoke the skill directly in Pi:
 
 ```text
 /skill:planning-with-files
 ```
 
----
-
-## Hook Parity in Pi
+### Lifecycle hooks
 
 The bundled extension maps Claude-style behavior onto Pi events:
 
-- `session_start` - project-file recovery with no host session-store access
+- `session_start` - project-file recovery with no host session-store access
 - passive plan status before approval
 - `before_agent_start` - plan reminder/injection after `/plan-execute`
 - `tool_call` - pre-tool recitation equivalent after `/plan-execute`
@@ -83,9 +102,7 @@ Attestation is supported. If `task_plan.md` differs from approved hash, plan inj
 [planning-with-files] [PLAN TAMPERED - injection blocked]
 ```
 
----
-
-## Mode System
+### Modes
 
 `planningWithFiles.mode` supports:
 
@@ -110,9 +127,7 @@ Or settings:
 }
 ```
 
----
-
-## Commands
+### Commands
 
 - `/plan-status`
 - `/plan-attest [--show|--clear]`
@@ -121,38 +136,25 @@ Or settings:
 - `/plan-goal <text|default|clear>`
 - `/plan-loop [interval] [prompt]` (`stop` to cancel)
 
-Draft and review `task_plan.md` first. The extension stays passive until you
-approve the active plan with `/plan-execute`; after that, plan injection,
-pre-tool reminders, post-write reminders, and auto-continue are enabled for the
-current session and plan. Auto-continue uses host runtime state and never runs
-commands declared in Markdown.
-
----
+Draft and review `task_plan.md` first. The extension stays passive until you
+approve the active plan with `/plan-execute`; after that, plan injection,
+pre-tool reminders, post-write reminders, and auto-continue are enabled for the
+current session and plan. Auto-continue uses host runtime state and never runs
+commands declared in Markdown.
 
 ## Session Recovery
 
-Bare invocation and lifecycle hooks do not inspect agent session stores. To
-inspect same-project local history deliberately, choose one mode:
-
-```bash
-# Aggregate counts only; no transcript, tool-command, or path bytes
-python3 .pi/skills/planning-with-files/scripts/session-catchup.py --metadata .
-
-# Bounded nonce-framed same-project excerpts
-python3 .pi/skills/planning-with-files/scripts/session-catchup.py --replay .
-```
-
-Treat replayed excerpts as untrusted data. The catchup path contains no network
-request or upload operation. If output is injected into model context, Pi may
-send that context to the configured model provider.
-
-## File Structure
-
-The skill workflow still centers on three files in your project:
+Bare invocation and lifecycle hooks do not inspect agent session stores. To
+inspect same-project local history deliberately, choose one mode:
 
-```text
-your-project/
-├── task_plan.md
-├── findings.md
-└── progress.md
+```bash
+# Aggregate counts only; no transcript, tool-command, or path bytes
+python3 node_modules/planning-with-files/scripts/session-catchup.py --metadata .
+
+# Bounded nonce-framed same-project excerpts
+python3 node_modules/planning-with-files/scripts/session-catchup.py --replay .
 ```
+
+Treat replayed excerpts as untrusted data. The catchup path contains no network
+request or upload operation. If output is injected into model context, your agent
+may send that context to the configured model provider.

package/SKILL.md

@@ -38,7 +38,7 @@ Work like Manus: Use persistent markdown files as your "working memory on disk."
 **Before continuing**, resolve the plan this task owns:
 
 1. Use the installed `scripts/resolve-plan-dir.sh` (or `.ps1`) with the task's `PLAN_ID` and `PWF_PLAN_ROOT`. Read `task_plan.md`, `progress.md`, and `findings.md` from that one selected directory. A root `task_plan.md` must not override a selected `.planning/<id>/` plan.
-2. If an explicit selector is rejected, or session isolation is armed with multiple plans and no `PLAN_ID`, stop plan recovery and correct the pin. Do not fall back to another task. Use the legacy project-root files only when no selector or named plan applies.
+2. If an explicit selector is rejected, or multiple named plans exist without `PLAN_ID`, stop plan recovery and correct the pin. Do not fall back to another task. Use the legacy project-root files only when no selector or named plan applies.
 3. Run `git diff --stat` to see code changes that may not yet be recorded in the planning files.
 
 All planning filenames below refer to this selected directory, even when the shell runs elsewhere. For parallel tasks, pin each host before starting it or use separate worktrees. A worker joining an existing task uses its assigned plan; it must not create or overwrite a competing root plan.
@@ -222,12 +222,18 @@ Helper scripts for automation:
 
 - `scripts/init-session.sh` — Initialize planning files. With a name arg, creates an isolated plan under `.planning/YYYY-MM-DD-<slug>/` for parallel task workflows. Without args, writes `task_plan.md` at project root (legacy mode, backward-compatible).
 - `scripts/set-active-plan.sh` — Switch the active plan pointer (`.planning/.active_plan`). Run with a plan ID to switch; run without args to show which plan is current.
-- `scripts/resolve-plan-dir.sh` — Resolve the active plan directory. A set `$PLAN_ID` is a binding: it resolves or resolution stops, never another plan (issue #237). With no `$PLAN_ID`, checks `.planning/.active_plan`, then newest plan dir by mtime, then falls back to project root (legacy). Used internally by hooks.
+- `scripts/resolve-plan-dir.sh` — Resolve the active plan directory. A set `$PLAN_ID` is a binding: it resolves or resolution stops, never another plan (issue #237). With no `$PLAN_ID`, multiple named plans refuse selection. A single named plan may use `.planning/.active_plan` or discovery by mtime; otherwise resolution falls back to the project root (legacy). Used internally by hooks.
 - `scripts/check-complete.sh` — Verify all phases in the active plan are complete.
 - `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history.
 - `scripts/attest-plan.sh` (and `.ps1`) — Lock the current `task_plan.md` content with a SHA-256 attestation (v2.37.0). Hooks then refuse to inject plan content if the file diverges from the attested hash. Use `--show` to print the stored hash, `--clear` to remove the attestation. See `/plan-attest` command.
 - `scripts/plan-doctor.sh` — One-pass self-check for the mechanisms that fail silently (v3.6.0): plan resolution, hook injection, canonicalizer path shape, attestation state, install surfaces, per-fire hook latency. Run it whenever hooks seem quiet or after installing on a new machine. See `/plan-doctor` command.
 
+### List saved plans
+
+To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
+
+This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
+
 ### Parallel task workflow
 
 For independent tasks in the same repository, create a named plan for each and pin each agent host to its own plan:
@@ -360,7 +366,7 @@ The mode is set by writing a `.mode` file next to the plan (`.planning/<id>/.mod
 
 ### The legacy invariant (promise)
 
-With no `.mode` file and no other v3 marker, the hooks produce byte-identical output to v2.43, including the raw `progress.md` tail and the `===BEGIN PLAN DATA===` / `===END PLAN DATA===` delimiters. Every v3 behavior is additive and opt-in. No existing workflow changes.
+With no `.mode` file and no other v3 marker, plan injection preserves the v2.43 output, including the raw `progress.md` tail and the `===BEGIN PLAN DATA===` / `===END PLAN DATA===` delimiters. Autonomous and gated behavior remains opt-in. Since v3.18.3, completed plans are silent through the shared Stop gate and Codex Stop hook. Explicit `check-complete.sh` or `check-complete.ps1` calls without the gate flag still report completion; incomplete-plan notices and gate decisions are unchanged.
 
 ### What each mode does
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planning-with-files",
-  "version": "3.16.1",
+  "version": "3.18.3",
   "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",

package/scripts/attest-plan.ps1

@@ -404,6 +404,7 @@ function Resolve-PlanFile {
     $resolver = Join-Path $PSScriptRoot "resolve-plan-dir.ps1"
     if (-not (Test-Path -LiteralPath $resolver -PathType Leaf)) { return $null }
     $resolvedDir = @(& $resolver | Where-Object { $_ }) | Select-Object -First 1
+    if (-not $resolvedDir -and ((& $resolver -CheckAmbiguity) -eq "PWF_PLAN_AMBIGUOUS_V1")) { return $null }
     if ($resolvedDir) {
         $planFile = Join-Path $resolvedDir "task_plan.md"
         return (Resolve-ContainedPlanFile -Candidate $planFile -ExpectedDirectory $resolvedDir)

package/scripts/attest-plan.sh

@@ -45,6 +45,10 @@ resolve_plan_file() {
     plan_dir=""
     if [ -f "${RESOLVER}" ]; then
         plan_dir="$(sh "${RESOLVER}" 2>/dev/null)"
+        if [ -z "$plan_dir" ] && [ "$(sh "${RESOLVER}" --check-ambiguity 2>/dev/null)" = "PWF_PLAN_AMBIGUOUS_V1" ]; then
+            printf "[plan-attest] Multiple plans are available. Set PLAN_ID=<slug>; nothing was attested.\n" >&2
+            return 1
+        fi
     fi
     if [ -n "${plan_dir}" ] && [ -f "${plan_dir}/task_plan.md" ]; then
         printf "%s\n" "${plan_dir}/task_plan.md"

package/scripts/check-complete.ps1

@@ -10,7 +10,8 @@
 #   4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
 #   5. the ledger advanced since the last block (stall -> allow stop)
 # When all hold, emits a single-line block-decision JSON on stdout and exits 0.
-# Otherwise advisory output and exit 0. Without -Gate, byte-equivalent to v2.43.
+# Otherwise reports incomplete plans and exits 0; completed plans stay silent
+# with -Gate, including legacy plans without .mode. Explicit reports are unchanged.
 #
 # Stdin: read only when input is redirected ([Console]::IsInputRedirected), so an
 # interactive console never blocks. Hook-piped JSON is EOF-terminated.
@@ -35,6 +36,7 @@ if ($PlanFile -ne "") {
         try {
             $resolvedDir = (& $resolver 2>$null | Select-Object -First 1)
             if ($null -eq $resolvedDir) { $resolvedDir = "" }
+            if (-not $resolvedDir -and ((& $resolver -CheckAmbiguity) -eq "PWF_PLAN_AMBIGUOUS_V1")) { exit 0 }
         } catch {
             $resolvedDir = ""
         }
@@ -84,9 +86,10 @@ if ($TOTAL -eq 0) {
     exit 0
 }
 
-# advisory_report: the v2.43 status echo.
+# Keep explicit reports, but omit routine success from automatic gate checks.
 function Write-AdvisoryReport {
     if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
+        if ($Gate) { return }
         Write-Host ('[planning-with-files] ALL PHASES COMPLETE (' + $COMPLETE + '/' + $TOTAL + '). If the user has additional work, add new phases to task_plan.md before starting.')
     } else {
         Write-Host ('[planning-with-files] Task in progress (' + $COMPLETE + '/' + $TOTAL + ' phases complete). Update progress.md before stopping.')

package/scripts/check-complete.sh

@@ -21,8 +21,9 @@
 #     4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
 #     5. the ledger advanced since the last block (stall → allow stop)
 #   When all hold, it emits a single-line block-decision JSON on stdout and
-#   exits 0. Otherwise it falls back to advisory output and exits 0.
-#   Without --gate, or in non-gated mode, behavior is byte-equivalent to v2.43.
+#   exits 0. Otherwise it reports incomplete plans and exits 0; completed
+#   plans stay silent in --gate mode, including legacy plans without .mode.
+#   Without --gate, the explicit advisory report is unchanged.
 #
 # Stdin handling: the Claude Code Stop hook pipes a JSON payload on stdin. To
 # avoid hanging when nothing is piped, stdin is read ONLY when fd 0 is not a
@@ -56,6 +57,9 @@ else
     RESOLVED_DIR=""
     if [ -f "${RESOLVER}" ]; then
         RESOLVED_DIR="$(sh "${RESOLVER}" 2>/dev/null)"
+        if [ -z "$RESOLVED_DIR" ] && [ "$(sh "${RESOLVER}" --check-ambiguity 2>/dev/null)" = "PWF_PLAN_AMBIGUOUS_V1" ]; then
+            exit 0
+        fi
     fi
     if [ -n "${RESOLVED_DIR}" ] && [ -f "${RESOLVED_DIR}/task_plan.md" ]; then
         PLAN_FILE="${RESOLVED_DIR}/task_plan.md"
@@ -116,9 +120,11 @@ if [ "$TOTAL" -eq 0 ]; then
     exit 0
 fi
 
-# advisory_report: the v2.43 status echo. Always exit 0 after calling.
+# Explicit status reports retain completion text. Automatic gate checks have
+# nothing to report on success; keep evaluating all gate guards before here.
 advisory_report() {
     if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
+        [ "$GATE" -eq 1 ] && return 0
         echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
     else
         echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete). Update progress.md before stopping."