planning-with-files 3.19.0 → 3.20.6

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.6"
 ---
 
 # 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.19.0",
-  "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.6",
+  "description": "Official Planning with Files skill for AI coding agents. Ships the canonical skill, 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/attest-plan.ps1

@@ -116,7 +116,13 @@ public static class PwfAttestationNative {
             handle, FileAttributeTagInfo, out tag,
             (uint)Marshal.SizeOf(typeof(FILE_ATTRIBUTE_TAG_INFO))))
             throw new Win32Exception(Marshal.GetLastWin32Error());
-        if ((tag.FileAttributes & FILE_ATTRIBUTE_REPARSE_POINT) != 0)
+        // Refuse only name-surrogate reparse points (symlinks, junctions, and any
+        // unknown tag with bit 29 set): those are what path parsing follows. A
+        // OneDrive Files On-Demand placeholder (tag 0x9000601A) is a regular file
+        // that every other route reads; refusing it broke attestation, --show
+        // and --clear in every project under OneDrive (#275).
+        if ((tag.FileAttributes & FILE_ATTRIBUTE_REPARSE_POINT) != 0 &&
+            (tag.ReparseTag & 0x20000000) != 0)
             throw new IOException("Refusing a reparse-point file.");
         if ((tag.FileAttributes & (uint)FileAttributes.Directory) != 0)
             throw new IOException("Refusing a directory where a regular file is required.");
@@ -218,8 +224,10 @@ if ($script:IsWindowsHost) {
     $securityRootPath = (Get-Location).Path
     if ($env:PWF_PLAN_ROOT) {
         $pin = $env:PWF_PLAN_ROOT
+        # Windows PowerShell 5.1 has no IsPathFullyQualified; a drive-qualified
+        # local path is the only accepted shape, as in resolve-plan-dir.ps1.
         $isUnc = $pin.StartsWith('\\') -or $pin.StartsWith('//')
-        if (-not [IO.Path]::IsPathFullyQualified($pin) -or $isUnc) {
+        if ($isUnc -or ($pin -notmatch '^[A-Za-z]:[\\/]')) {
             throw "[plan-attest] PWF_PLAN_ROOT must be an absolute local path."
         }
         $securityRootPath = $pin

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.
@@ -80,6 +101,26 @@ function Get-InheritedMode([string]$CurrentMode) {
     return $CurrentMode
 }
 
+function Format-AttestationFailureReason {
+    param([object[]]$Output, [string]$Fallback)
+
+    $Reason = @(
+        $Output |
+            ForEach-Object {
+                if ($null -ne $_) { ($_.ToString()).Trim() }
+            } |
+            Where-Object { $_ }
+    ) -join " "
+    $Reason = ($Reason -replace '\s+', ' ').Trim()
+    if ([string]::IsNullOrWhiteSpace($Reason)) {
+        return $Fallback
+    }
+    if ($Reason.Length -gt 300) {
+        return ($Reason.Substring(0, 297) + "...")
+    }
+    return $Reason
+}
+
 # Validate template
 if ($Template -ne "default" -and $Template -ne "analytics") {
     Write-Host "Unknown template: $Template (available: default, analytics). Using default."
@@ -136,20 +177,7 @@ if ($UsePlanDir) {
         $Counter++
     }
     $TargetDir = Join-Path $PlanningRoot $PlanId
-    New-Item -ItemType Directory -Path $TargetDir -Force | Out-Null
-    # Reuse the selector's contained, atomic pointer replacement. Set-Content
-    # would follow a reparse point and truncate a hardlinked pointer in place,
-    # overwriting whichever file shares that inode.
-    $global:LASTEXITCODE = 0
-    try {
-        & $PlanSelector $PlanId *> $null
-    } catch {
-        $global:LASTEXITCODE = 1
-    }
-    if ($LASTEXITCODE -ne 0) {
-        Write-Error "Error: could not safely update the active plan pointer at $(Join-Path $PlanningRoot '.active_plan')."
-        exit 1
-    }
+    New-Item -ItemType Directory -Path $TargetDir -Force -ErrorAction Stop | Out-Null
     $Mode = Get-InheritedMode $Mode
 } else {
     $TargetDir = (Get-Location).Path
@@ -173,11 +201,12 @@ if ($UsePlanDir) {
     Write-Host "PLAN_ID=$PlanId"
 }
 
+try {
 # Create task_plan.md if it doesn't exist
 if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
     $AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
     if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
-        Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
+        Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath -ErrorAction Stop
     } else {
         @"
 # Task Plan: [Brief Description]
@@ -226,7 +255,7 @@ Phase 1
 ## Errors Encountered
 | Error | Resolution |
 |-------|------------|
-"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
+"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8 -ErrorAction Stop
     }
     Write-Host "Created $TaskPlanDisplay"
 } else {
@@ -237,7 +266,7 @@ Phase 1
 if (-not (Test-Path -LiteralPath $FindingsPath)) {
     $AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
     if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
-        Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
+        Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath -ErrorAction Stop
     } else {
         @"
 # Findings & Decisions
@@ -258,7 +287,7 @@ if (-not (Test-Path -LiteralPath $FindingsPath)) {
 
 ## Resources
 -
-"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
+"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8 -ErrorAction Stop
     }
     Write-Host "Created $FindingsDisplay"
 } else {
@@ -287,7 +316,7 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
 ### Errors
 | Error | Resolution |
 |-------|------------|
-"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
+"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
     } else {
         @"
 # Progress Log
@@ -308,12 +337,56 @@ if (-not (Test-Path -LiteralPath $ProgressPath)) {
 ### Errors
 | Error | Resolution |
 |-------|------------|
-"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
+"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8 -ErrorAction Stop
     }
     Write-Host "Created $ProgressDisplay"
 } else {
     Write-Host "$ProgressDisplay already exists, skipping"
 }
+} catch {
+    Write-Error "Error: could not initialize planning files in '$TargetDir': $($_.Exception.Message)"
+    exit 1
+}
+
+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.
+    $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 (-not $pointerSet) {
+        Write-Error "Error: could not safely update the active plan pointer at $(Join-Path $PlanningRoot '.active_plan')."
+        exit 1
+    }
+}
 
 Write-Host ""
 Write-Host "Planning files initialized!"
@@ -350,42 +423,94 @@ if ($Mode -ne "") {
     # (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
     # attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
     # no-follow implementation uses Win32 handles. On Unix, use the POSIX
-    # attester instead. Bind slug mode to the plan we just created so an
-    # inherited PLAN_ID cannot redirect attestation to another plan.
+    # attester instead. Slug mode binds PWF_PLAN_ROOT and PLAN_ID to the plan
+    # we just created so an inherited pin or slug cannot redirect attestation
+    # to another project or plan (#261, #237). Root mode clears both instead:
+    # the attester only falls back to the legacy ./task_plan.md when no
+    # selector is set, and a bound pin would make it refuse the root plan.
+    $AttestationSucceeded = $false
+    $AttestationCommand = "attest-plan"
+    $AttestationReason = "task_plan.md was not available for attestation"
     $PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
-    if (Test-Path -LiteralPath $PlanFilePwf) {
+    if (Test-Path -LiteralPath $PlanFilePwf -PathType Leaf) {
         $HadPlanId = Test-Path Env:PLAN_ID
         $PreviousPlanId = $env:PLAN_ID
+        $HadPlanRoot = Test-Path Env:PWF_PLAN_ROOT
+        $PreviousPlanRoot = $env:PWF_PLAN_ROOT
         try {
             if ($UsePlanDir) {
+                $env:PWF_PLAN_ROOT = (Get-Location).Path
                 $env:PLAN_ID = $PlanId
             } else {
+                Remove-Item Env:PWF_PLAN_ROOT -ErrorAction SilentlyContinue
                 Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
             }
 
+            # A called script can return without changing $LASTEXITCODE, so
+            # clear the inherited value before every attempt. Both a non-zero
+            # status and a terminating exception mean the plan is not attested.
+            $global:LASTEXITCODE = 0
+            $AttestOutput = @()
             $IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
             if ($IsWindowsHost) {
-                $AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
-                if (Test-Path -LiteralPath $AttestPs1) {
-                    & $AttestPs1 *> $null
+                $AttestationCommand = "attest-plan.ps1"
+                $AttestPs1 = Join-Path $ScriptDir $AttestationCommand
+                if (Test-Path -LiteralPath $AttestPs1 -PathType Leaf) {
+                    $AttestOutput = @(& $AttestPs1 2>&1)
+                    $AttestExitCode = $LASTEXITCODE
+                    if ($AttestExitCode -eq 0) {
+                        $AttestationSucceeded = $true
+                        $AttestationReason = ""
+                    } else {
+                        $AttestationReason = Format-AttestationFailureReason `
+                            -Output $AttestOutput `
+                            -Fallback "$AttestationCommand exited with code $AttestExitCode"
+                    }
+                } else {
+                    $AttestationReason = "$AttestationCommand was not found beside init-session.ps1"
                 }
             } else {
-                $AttestSh = Join-Path $ScriptDir "attest-plan.sh"
+                $AttestationCommand = "attest-plan.sh"
+                $AttestSh = Join-Path $ScriptDir $AttestationCommand
                 $Sh = Get-Command sh -ErrorAction SilentlyContinue
-                if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
-                    & $Sh.Path $AttestSh *> $null
+                if ($Sh -and (Test-Path -LiteralPath $AttestSh -PathType Leaf)) {
+                    $AttestOutput = @(& $Sh.Path $AttestSh 2>&1)
+                    $AttestExitCode = $LASTEXITCODE
+                    if ($AttestExitCode -eq 0) {
+                        $AttestationSucceeded = $true
+                        $AttestationReason = ""
+                    } else {
+                        $AttestationReason = Format-AttestationFailureReason `
+                            -Output $AttestOutput `
+                            -Fallback "$AttestationCommand exited with code $AttestExitCode"
+                    }
+                } elseif (-not $Sh) {
+                    $AttestationReason = "sh was not found; $AttestationCommand could not run"
+                } else {
+                    $AttestationReason = "$AttestationCommand was not found beside init-session.ps1"
                 }
             }
         } catch {
-            # attestation failure must not abort init; the mode marker still stands.
+            $AttestationReason = Format-AttestationFailureReason `
+                -Output @($_) `
+                -Fallback "$AttestationCommand failed"
         } finally {
             if ($HadPlanId) {
                 $env:PLAN_ID = $PreviousPlanId
             } else {
                 Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
             }
+            if ($HadPlanRoot) {
+                $env:PWF_PLAN_ROOT = $PreviousPlanRoot
+            } else {
+                Remove-Item Env:PWF_PLAN_ROOT -ErrorAction SilentlyContinue
+            }
         }
     }
 
-    Write-Host "Mode: $MarkerText (attested, gate counter reset)"
+    if ($AttestationSucceeded) {
+        Write-Host "Mode: $MarkerText (attested, gate counter reset)"
+    } else {
+        Write-Host "Mode: $MarkerText (NOT attested: $AttestationReason; run $AttestationCommand before the first hook fire)"
+    }
 }

package/scripts/init-session.sh

@@ -103,6 +103,7 @@ slugify() {
     # Lowercase, non-alphanumerics → '-', collapse repeats, trim leading/trailing '-'
     printf '%s' "$1" \
         | tr '[:upper:]' '[:lower:]' \
+        | tr '\r\n' '--' \
         | sed -e 's/[^a-z0-9]/-/g' -e 's/-\{2,\}/-/g' -e 's/^-//' -e 's/-$//' \
         | cut -c1-40
 }
@@ -185,6 +186,10 @@ apply_v3_mode() {
     _mode_plan="$2"
     [ -z "$MODE" ] && return 0
 
+    ATTESTATION_OK=0
+    ATTESTATION_COMMAND="attest-plan.sh"
+    ATTESTATION_REASON="task_plan.md was not available for attestation"
+
     # (a) reset the gate block counter and drop any stale gate ledger so a prior
     #     run's high block count cannot let the next run stop instantly.
     printf '0\n' > "${_mode_dir}/.stop_blocks"
@@ -202,12 +207,61 @@ apply_v3_mode() {
 
     # (c) auto-attest the plan (attestation default-on in v3 modes, security
     #     strand rec 1). attest-plan.sh resolves the same way init-session just
-    #     pinned things: in slug mode PLAN_ID points at this plan dir; in legacy
-    #     mode it is empty and the script falls back to ./task_plan.md at root.
-    #     Run from the project root (CWD here) so both resolutions land.
-    _attest="${SCRIPT_DIR}/attest-plan.sh"
-    if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
-        PLAN_ID="${PLAN_ID:-}" sh "${_attest}" >/dev/null 2>&1 || true
+    #     pinned things. Slug mode binds both selectors to the plan that was
+    #     just created, so an inherited PWF_PLAN_ROOT or PLAN_ID cannot
+    #     redirect attestation to another project or plan (#261, #237). Root
+    #     mode clears both instead: the attester only falls back to the legacy
+    #     ./task_plan.md when no selector is set, and a bound pin would make it
+    #     refuse the root plan. Run from the project root (CWD here) so both
+    #     resolutions land.
+    _attest="${SCRIPT_DIR}/${ATTESTATION_COMMAND}"
+    if [ ! -f "${_attest}" ]; then
+        ATTESTATION_REASON="${ATTESTATION_COMMAND} was not found beside init-session.sh"
+        return 0
+    fi
+    if [ ! -f "${_mode_plan}" ]; then
+        return 0
+    fi
+
+    if [ "$SLUG_MODE" -eq 1 ]; then
+        if _attest_output="$(PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" 2>&1)"; then
+            ATTESTATION_OK=1
+            ATTESTATION_REASON=""
+            return 0
+        else
+            _attest_rc=$?
+        fi
+    else
+        if _attest_output="$(PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" 2>&1)"; then
+            ATTESTATION_OK=1
+            ATTESTATION_REASON=""
+            return 0
+        else
+            _attest_rc=$?
+        fi
+    fi
+
+    _attest_reason="$(
+        printf '%s\n' "${_attest_output}" |
+            sed -n '/[^[:space:]]/ { s/[[:space:]][[:space:]]*/ /g; s/^ //; s/ $//; p; q; }' |
+            cut -c1-300
+    )"
+    if [ -n "${_attest_reason}" ]; then
+        ATTESTATION_REASON="${_attest_reason}"
+    else
+        ATTESTATION_REASON="${ATTESTATION_COMMAND} exited with code ${_attest_rc}"
+    fi
+    return 0
+}
+
+print_v3_mode_status() {
+    _status_dir="$1"
+    _marker="$(cat "${_status_dir}/.mode")"
+    if [ "${ATTESTATION_OK:-0}" -eq 1 ]; then
+        printf 'Mode: %s (attested, gate counter reset)\n' "${_marker}"
+    else
+        printf 'Mode: %s (NOT attested: %s; run %s before the first hook fire)\n' \
+            "${_marker}" "${ATTESTATION_REASON:-attestation failed}" "${ATTESTATION_COMMAND:-attest-plan.sh}"
     fi
 }
 
@@ -422,7 +476,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
     echo "Pin this terminal to the plan for parallel sessions:"
     echo "  export PLAN_ID=$PLAN_ID"
     if [ -n "$MODE" ]; then
-        echo "Mode: $(cat "${PLAN_DIR}/.mode") (attested, gate counter reset)"
+        print_v3_mode_status "${PLAN_DIR}"
     fi
 else
     PROJECT_NAME="${PROJECT_NAME:-project}"
@@ -433,6 +487,6 @@ else
     echo "Planning files initialized!"
     echo "Files: task_plan.md, findings.md, progress.md"
     if [ -n "$MODE" ]; then
-        echo "Mode: $(cat "$(pwd)/.mode") (attested, gate counter reset)"
+        print_v3_mode_status "$(pwd)"
     fi
 fi

package/scripts/inject-plan.py

@@ -845,7 +845,10 @@ class Injector(object):
                 )
             raise Bail()
         if plan_id:
-            if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
+            # A linked plan directory is never selectable (#270): the same
+            # `[ ! -L ]` the reference applies on every branch below.
+            if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
+                    and not is_link(plan_prefix + ".planning/" + plan_id)):
                 resolved = plan_prefix + ".planning/" + plan_id
                 scope = "scoped"
                 explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
                 active = b""
             if active and slug_is_valid(active):
                 slug = active.decode("ascii")
-                if is_dir(plan_prefix + ".planning/" + slug):
+                if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
                     resolved = plan_prefix + ".planning/" + slug
                     scope = "scoped"
         if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
                 candidate = plan_prefix + ".planning/" + name
                 if not is_dir(candidate):
                     continue
+                if is_link(candidate):
+                    continue
                 if not slug_is_valid(name):
                     continue
                 if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
     except OSError:
         names = []
     for name in names:
-        if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
+        candidate_dir = plan_root + "/" + name
+        # A linked plan directory is not selectable, so it never counts (#270):
+        # the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
+        if is_link(candidate_dir):
+            continue
+        if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
             count += 1
             if count > 1:
                 return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
     if plan_id:
         if slug_is_valid(plan_id):
             candidate = fs_root + "/" + plan_id
-            if is_dir(candidate) and within(candidate):
+            if is_dir(candidate) and not is_link(candidate) and within(candidate):
                 return found(plan_id)
         return ("", "")
 
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
         if slug_is_valid(active):
             slug = active.decode("ascii")
             candidate = fs_root + "/" + slug
-            if is_dir(candidate) and within(candidate):
+            if is_dir(candidate) and not is_link(candidate) and within(candidate):
                 return found(slug)
 
     if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
                 continue
             if name.startswith("."):
                 continue
+            if is_link(candidate):
+                continue
             if not slug_is_valid(name):
                 continue
             if not is_file(candidate + "/task_plan.md"):

package/scripts/inject-plan.sh

@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
         PLAN_COUNT=1
     fi
     for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
-        [ -f "$plan_candidate" ] || continue
         plan_candidate_dir="${plan_candidate%/task_plan.md}"
+        [ -L "$plan_candidate_dir" ] && continue
+        [ -f "$plan_candidate" ] || continue
         slug_is_valid "${plan_candidate_dir##*/}" || continue
         PLAN_COUNT=$((PLAN_COUNT + 1))
         if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
     # printing on those would spam the transcript with the same line. The
     # userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
     # still sees and reports the state.
-    if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
+    # A linked plan directory is never selectable (#270): same `-L` rule as
+    # the counter above and as resolve-plan-dir.sh, on every branch below.
+    if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
         RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
     else
         if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
     fi
 elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
     AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
-    if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
+    if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
         RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
     fi
 fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
     for d in "${PLAN_PREFIX}".planning/*/; do
         d="${d%/}"; n="${d##*/}"
         case "$n" in .*) continue;; esac
+        [ -L "$d" ] && continue
         slug_is_valid "$n" || continue
         [ -f "$d/task_plan.md" ] || continue
         m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)

package/scripts/ledger-append.ps1

@@ -67,7 +67,7 @@ function Resolve-PlanDir {
 
     $activePointer = Join-Path $planRoot ".active_plan"
     if (Test-Path -LiteralPath $activePointer) {
-        $planId = (Get-Content -LiteralPath $activePointer -Raw).Trim()
+        $planId = "$(Get-Content -LiteralPath $activePointer -Raw -ErrorAction SilentlyContinue)".Trim()
         if ($planId) {
             $candidate = Join-Path $planRoot $planId
             if (Test-Path -LiteralPath $candidate -PathType Container) { return $candidate }

package/scripts/ledger-summary.ps1

@@ -44,7 +44,7 @@ function Resolve-PlanDir {
 
     $activePointer = Join-Path $planRoot ".active_plan"
     if (Test-Path -LiteralPath $activePointer) {
-        $planId = (Get-Content -LiteralPath $activePointer -Raw).Trim()
+        $planId = "$(Get-Content -LiteralPath $activePointer -Raw -ErrorAction SilentlyContinue)".Trim()
         if ($planId) {
             $candidate = Join-Path $planRoot $planId
             if (Test-Path -LiteralPath $candidate -PathType Container) { return $candidate }