planning-with-files 3.20.5 → 3.20.7

package/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: pi-planning-with-files
+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."
 user-invocable: true
 allowed-tools: "Read Write Edit Bash Glob Grep"
@@ -7,26 +7,28 @@ hooks:
   UserPromptSubmit:
     - 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=userprompt; exit 0"
+          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=userprompt; exit 0"
   PreToolUse:
     - matcher: "Write|Edit|Bash|Read|Glob|Grep"
       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=pretool; exit 0"
+          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=pretool; exit 0"
   PostToolUse:
     - matcher: "Write|Edit"
       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=posttool; exit 0"
+          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=posttool; exit 0"
   Stop:
     - 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=stop; exit 0"
+          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=stop; exit 0"
   PreCompact:
     - matcher: "*"
       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"
+          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.20.7"
 ---
 
 # Planning with Files
@@ -221,7 +223,7 @@ Copy these templates to start:
 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/set-active-plan.sh` — Switch or inspect the active plan pointer (`.planning/.active_plan`). Run with `--list` to show named plans and phase counts, with a plan ID to switch, or 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`, 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.
@@ -284,11 +286,11 @@ Not every install path ships every surface in this section. Two distinct install
 | `/plugin marketplace add OthmanAdi/planning-with-files` then `/plugin install` | SKILL.md, scripts, templates, **plus `commands/` folder** | Yes, as `/plan-goal` and `/plan-loop` |
 | `npx skills add OthmanAdi/planning-with-files` (or ClawHub) | SKILL.md, scripts, templates only | No, follow the manual fallback below |
 
-The PreCompact hook is registered in the SKILL.md frontmatter and works for both routes. The `/plan-goal` and `/plan-loop` slash commands live in `commands/` at the repo root, which only the plugin route copies into `~/.claude/plugins/marketplaces/`. Skill-only installs land at `~/.claude/skills/planning-with-files/` and do not see `commands/`.
+Plugin installs register six lifecycle events from `hooks/hooks.json`, including quiet `SessionStart` recovery. Standalone skill installs register the five hooks in this SKILL.md frontmatter only after the skill is invoked for that session, so they have no startup recovery. The `/plan-goal` and `/plan-loop` slash commands live in `commands/` at the repository root and are available from the versioned plugin cache. Skill-only installs land at `~/.claude/skills/planning-with-files/` and do not include `commands/`.
 
 The standalone `scripts/skill-hook.sh` reads the host's JSON session identity. UserPromptSubmit emits plain context; PreToolUse and PostToolUse emit the event's `additionalContext` JSON. The progress reminder fires at most once per turn when a usable session identity and private cache are available, and repeats when those are unavailable. All five events follow the same plan selection and opt-out checks.
 
-Both slash commands also carry `disable-model-invocation: true`, which means the model will not auto-trigger them. You type them. Per known Claude Code behavior (anthropics/claude-code issues #26251, #41417), some sessions interpret `disable-model-invocation: true` as "I cannot use the Skill tool for this entry at all" and refuse to fire even when you type the slash. If that happens, the manual fallback below produces the same effect.
+Both slash commands carry `disable-model-invocation: true`, so invoke them explicitly. If a command is unavailable on a skill-only install, the manual fallback below produces the same planning-file result.
 
 ### PreCompact hook (auto)
 

package/package.json

@@ -1,10 +1,9 @@
 {
   "name": "planning-with-files",
-  "version": "3.20.5",
-  "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.",
+  "version": "3.20.7",
+  "description": "Official Planning with Files skill for AI coding agents. Keeps persistent project planning files and injects selected plan context. Automatic recovery reads project files only; explicit local session catchup has no network upload path. Includes scripts, templates, and a Pi Coding Agent extension.",
   "keywords": [
-    "pi-package",
-    "pi-skill",
+    "planning-with-files",
     "planning",
     "manus",
     "agent",
@@ -14,7 +13,8 @@
     "coding-agent",
     "context-engineering",
     "session-recovery",
-    "long-running-agents"
+    "long-running-agents",
+    "pi-coding-agent"
   ],
   "pi": {
     "skills": [

package/scripts/init-session.ps1

@@ -18,6 +18,27 @@ param(
     [switch]$Gated
 )
 
+# Windows PowerShell 5.1 can silently relocate a -File invocation when the
+# inherited cwd contains wildcard characters such as [ or ]. Recover the
+# physical cwd for a direct invocation before any project-relative paths are
+# resolved.
+if ($PSVersionTable.PSVersion.Major -eq 5 -and
+    [System.Management.Automation.WildcardPattern]::ContainsWildcardCharacters([Environment]::CurrentDirectory)) {
+    $processArgs = [Environment]::GetCommandLineArgs()
+    for ($index = 0; $index -lt ($processArgs.Length - 1); $index++) {
+        if ($processArgs[$index] -ieq '-File') {
+            $entryScript = $processArgs[$index + 1]
+            if (-not [IO.Path]::IsPathRooted($entryScript)) {
+                $entryScript = Join-Path ([Environment]::CurrentDirectory) $entryScript
+            }
+            if ([IO.Path]::GetFullPath($entryScript) -eq [IO.Path]::GetFullPath($PSCommandPath)) {
+                Set-Location -LiteralPath ([Environment]::CurrentDirectory)
+            }
+            break
+        }
+    }
+}
+
 $DATE = Get-Date -Format "yyyy-MM-dd"
 
 # Resolve v3 opt-in mode. -Gated implies autonomous and is the stronger marker.
@@ -331,13 +352,37 @@ if ($UsePlanDir) {
     # Activate the named plan only after all three planning files are ready.
     # This matches init-session.sh and prevents a failed initialization from
     # leaving .active_plan pointed at a partial plan directory.
-    $global:LASTEXITCODE = 0
-    try {
-        & $PlanSelector $PlanId *> $null
-    } catch {
-        $global:LASTEXITCODE = 1
+    $pointerSet = $false
+    for ($attempt = 1; $attempt -le 5; $attempt++) {
+        $global:LASTEXITCODE = 0
+        try {
+            $selectorResult = & $PlanSelector $PlanId 2>&1
+        } catch {
+            $selectorResult = $_
+            $global:LASTEXITCODE = 1
+        }
+        if ($LASTEXITCODE -eq 0) {
+            $pointerSet = $true
+            break
+        }
+        # Another writer can replace the pointer between the selector's
+        # Get-Item and final-path check. Retry only that transient result.
+        $transientPointerRace = $selectorResult -is [System.Management.Automation.ErrorRecord] -and
+            $selectorResult.Exception.Message -ceq
+                'Error: could not set the active plan pointer: the active plan pointer became unsafe during replacement'
+        if ($attempt -eq 5 -or -not $transientPointerRace) {
+            break
+        }
+        Start-Sleep -Milliseconds 50
+        $global:LASTEXITCODE = 0
+        try {
+            & $PlanSelector -VerifyRoot *> $null
+        } catch {
+            $global:LASTEXITCODE = 1
+        }
+        if ($LASTEXITCODE -ne 0) { break }
     }
-    if ($LASTEXITCODE -ne 0) {
+    if (-not $pointerSet) {
         Write-Error "Error: could not safely update the active plan pointer at $(Join-Path $PlanningRoot '.active_plan')."
         exit 1
     }

package/scripts/phase-status.ps1

@@ -7,9 +7,10 @@
     The ONLY sanctioned concurrent-safe writer of task_plan.md status lines. The
     orchestrator owns task_plan.md; workers NEVER edit it directly. The edit is
     a read-modify-write under the portable
-    <plan-dir>\.pwf-locks\phase-status.lock directory lock, with an atomic
-    temp-file + move swap so a torn write can never leave a half-rewritten plan
-    on disk (architecture C4).
+    <plan-dir>\.pwf-locks\phase-status.lock namespace. Ownership is granted by
+    atomically creating its .owner file, rather than trusting an external mkdir
+    exit status. The plan rewrite uses an atomic temp-file + move swap so a torn
+    write can never leave a half-rewritten plan on disk (architecture C4).
 
     Editing task_plan.md changes its SHA, so the orchestrator must re-attest at
     phase boundaries (see attest-plan.ps1).
@@ -102,18 +103,44 @@ function Enter-PwfDirectoryLock {
 
     $wait = [Diagnostics.Stopwatch]::StartNew()
     while ($wait.Elapsed.TotalSeconds -lt 5) {
-        $createdByUs = $false
         try {
-            New-Item -Path $LockDir -ItemType Directory -ErrorAction Stop | Out-Null
-            $createdByUs = $true
-            [System.IO.File]::WriteAllText($ownerFile, $token + "`n", $utf8NoBom)
+            [void][System.IO.Directory]::CreateDirectory($LockDir)
+        } catch {
+            Start-Sleep -Milliseconds 100
+            continue
+        }
+
+        $stream = $null
+        $createdOwner = $false
+        $claimed = $false
+        try {
+            # FileMode.CreateNew is the cross-runtime ownership decision. It
+            # fails atomically when either the shell or PowerShell writer has
+            # already claimed .owner, even if both observed mkdir success.
+            $stream = [System.IO.File]::Open(
+                $ownerFile,
+                [System.IO.FileMode]::CreateNew,
+                [System.IO.FileAccess]::Write,
+                [System.IO.FileShare]::None
+            )
+            $createdOwner = $true
+            $bytes = $utf8NoBom.GetBytes($token + "`n")
+            $stream.Write($bytes, 0, $bytes.Length)
+            $stream.Flush()
+            $claimed = $true
             return [PSCustomObject]@{
                 Directory = $LockDir
                 OwnerFile = $ownerFile
                 Token = $token
             }
         } catch {
-            if ($createdByUs) {
+            # Existing ownership is the normal contention path. Other failures
+            # remain fail-closed and are retried only within the bounded wait.
+        } finally {
+            if ($stream) {
+                $stream.Dispose()
+            }
+            if ($createdOwner -and -not $claimed) {
                 try {
                     if ([System.IO.File]::Exists($ownerFile)) {
                         $ownerValue = [System.IO.File]::ReadAllText($ownerFile).Trim()
@@ -121,13 +148,12 @@ function Enter-PwfDirectoryLock {
                             [System.IO.File]::Delete($ownerFile)
                         }
                     }
-                    [System.IO.Directory]::Delete($LockDir, $false)
                 } catch {
-                    # Leave any directory we cannot prove is still ours intact.
+                    # Leave any owner file we cannot prove is still ours intact.
                 }
             }
-            Start-Sleep -Milliseconds 100
         }
+        Start-Sleep -Milliseconds 100
     }
 
     return $null
@@ -174,7 +200,7 @@ $planDir  = Split-Path -Parent $planFile
 $lockRoot = Join-Path $planDir ".pwf-locks"
 $lockDir  = Join-Path $lockRoot "phase-status.lock"
 
-# Atomic directory creation is the common lock primitive used by both the sh
+# Exclusive .owner creation is the common lock primitive used by both the sh
 # and PowerShell implementations. Failure to acquire within about five seconds
 # is fail-closed: no plan read/rewrite is attempted.
 $lock = Enter-PwfDirectoryLock -LockRoot $lockRoot -LockDir $lockDir

package/scripts/phase-status.sh

@@ -4,9 +4,12 @@
 # This is the ONLY sanctioned concurrent-safe writer of task_plan.md status
 # lines. The orchestrator owns task_plan.md; workers NEVER edit it directly.
 # All status edits go through this read-modify-write under the portable
-# <plan-dir>/.pwf-locks/phase-status.lock directory lock, with an atomic
-# temp-file + mv swap so a torn write can never leave a half-rewritten plan on
-# disk (architecture C4).
+# <plan-dir>/.pwf-locks/phase-status.lock namespace. Lock ownership is the
+# atomic no-clobber creation of its .owner file; the directory's mkdir exit
+# status is only provisional because some Windows-native implementations can
+# report success to two simultaneous creators. The plan rewrite still uses an
+# atomic temp-file + mv swap so a torn write can never leave a half-rewritten
+# plan on disk (architecture C4).
 #
 # Note: editing task_plan.md changes its SHA, so the orchestrator must
 # re-attest at phase boundaries (see attest-plan.sh).
@@ -106,6 +109,22 @@ release_lock() {
     LOCK_ACQUIRED=0
 }
 
+claim_lock_owner() {
+    owner_file="${LOCK_DIR}/.owner"
+    # POSIX noclobber makes this redirection an exclusive create. This is the
+    # actual ownership decision: a Windows-native mkdir may report success
+    # after another process won the directory-creation race (issue #281).
+    if (
+        umask 077
+        set -C
+        printf '%s\n' "${LOCK_TOKEN}" > "${owner_file}"
+    ) 2>/dev/null; then
+        LOCK_ACQUIRED=1
+        return 0
+    fi
+    return 1
+}
+
 acquire_lock() {
     mkdir -p "${LOCK_ROOT}" 2>/dev/null || {
         printf "[phase-status] Cannot create lock root %s.\n" "${LOCK_ROOT}" >&2
@@ -114,7 +133,13 @@ acquire_lock() {
     LOCK_TOKEN="phase-status-$$-$(date +%s 2>/dev/null || printf 0)"
     started_at="$(date +%s 2>/dev/null || printf 0)"
     attempts=0
-    while ! mkdir "${LOCK_DIR}" 2>/dev/null; do
+    while :; do
+        # Directory creation is intentionally idempotent. The exclusive owner
+        # file below, not this external utility's exit status, grants the lock.
+        mkdir "${LOCK_DIR}" 2>/dev/null || true
+        if [ -d "${LOCK_DIR}" ] && claim_lock_owner; then
+            return 0
+        fi
         attempts=$((attempts + 1))
         now="$(date +%s 2>/dev/null || printf 0)"
         if { [ "${started_at}" -gt 0 ] 2>/dev/null \
@@ -125,13 +150,6 @@ acquire_lock() {
         fi
         sleep 0.1
     done
-    if ! printf '%s\n' "${LOCK_TOKEN}" > "${LOCK_DIR}/.owner" 2>/dev/null; then
-        rmdir "${LOCK_DIR}" 2>/dev/null || true
-        printf "[phase-status] Cannot record lock ownership in %s.\n" "${LOCK_DIR}" >&2
-        return 1
-    fi
-    LOCK_ACQUIRED=1
-    return 0
 }
 
 trap 'release_lock' EXIT

package/scripts/set-active-plan.ps1

@@ -128,6 +128,7 @@ function Test-SafeActiveFile {
     $linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
     return -not $item.PSIsContainer -and
         ($AllowLink -or -not $linked) -and
+        ($AllowLink -or -not $item.IsReadOnly) -and
         (Test-WithinRoot $ActiveFile)
 }
 
@@ -316,10 +317,23 @@ try {
         $stream.Write($bytes, 0, $bytes.Length)
         $stream.Flush()
     } finally { $stream.Dispose() }
-    if ($activeItem) {
-        [IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
-    } else {
-        [IO.File]::Move($tempFile, $ActiveFile)
+    $maxAttempts = 20
+    for ($attempt = 1; $attempt -le $maxAttempts; $attempt++) {
+        try {
+            $currentActive = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
+            if ($currentActive) {
+                if (-not (Test-SafeActiveFile)) {
+                    throw [InvalidOperationException]::new("the active plan pointer became unsafe during replacement")
+                }
+                [IO.File]::Replace($tempFile, $ActiveFile, [NullString]::Value)
+            } else {
+                [IO.File]::Move($tempFile, $ActiveFile)
+            }
+            break
+        } catch [IO.IOException] {
+            if ($attempt -eq $maxAttempts) { throw }
+            Start-Sleep -Milliseconds 25
+        }
     }
 } catch {
     Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"