planning-with-files 3.19.0 → 3.20.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "planning-with-files",
-  "version": "3.19.0",
+  "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.",
   "keywords": [
     "pi-package",

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

@@ -80,6 +80,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 +156,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 +180,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 +234,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 +245,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 +266,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 +295,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 +316,32 @@ 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.
+    $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
+    }
+}
 
 Write-Host ""
 Write-Host "Planning files initialized!"
@@ -350,42 +378,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 }

package/scripts/phase-status.ps1

@@ -56,7 +56,7 @@ function Resolve-PlanFile {
 
     $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
             $planFile  = Join-Path $candidate "task_plan.md"

package/scripts/resolve-plan-dir.ps1

@@ -77,6 +77,17 @@ function Get-FinalDirectoryPath {
     return (Resolve-Path -LiteralPath $Path -ErrorAction Stop).Path
 }
 
+function Test-FullyQualifiedLocalPath {
+    param([string]$Path)
+    if (-not $Path -or $Path.StartsWith('\\') -or $Path.StartsWith('//')) {
+        return $false
+    }
+    if ($script:IsWindowsHost) {
+        return $Path -match '^[A-Za-z]:[\\/]'
+    }
+    return [System.IO.Path]::IsPathRooted($Path)
+}
+
 # PWF_PLAN_ROOT: absolute plan-root binding (issue #212), mirroring
 # resolve-plan-dir.sh. A thread whose cwd is a shared PARENT of the real
 # project resolves the parent's plan and never sees the nested one;
@@ -90,9 +101,8 @@ function Get-FinalDirectoryPath {
 # checked against the pinned root. Unset keeps legacy behavior unchanged.
 if ($env:PWF_PLAN_ROOT) {
     $pin = $env:PWF_PLAN_ROOT
-    $isUnc = $pin.StartsWith('\\') -or $pin.StartsWith('//')
-    $isAbsolute = [System.IO.Path]::IsPathFullyQualified($pin)
-    if ($isAbsolute -and -not $isUnc -and (Test-Path -LiteralPath $pin -PathType Container)) {
+    if ((Test-FullyQualifiedLocalPath $pin) -and
+        (Test-Path -LiteralPath $pin -PathType Container)) {
         $projectRoot = $pin
         $PlanRoot = Join-Path $pin ".planning"
     } else {
@@ -129,6 +139,24 @@ function Test-WithinRoot {
     return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
 }
 
+# A linked plan directory (symlink or junction) is never selectable: not by
+# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
+# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
+# twin: LinkType names symlinks and junctions only. The ReparsePoint
+# attribute alone would also match OneDrive Files On-Demand placeholders,
+# which every synced directory and file carries and which are not links to
+# sh. The same predicate guards the pointer file below (#275).
+function Test-LinkedDirectory {
+    param($PathOrItem)
+    if ($PathOrItem -is [string]) {
+        $item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
+    } else {
+        $item = $PathOrItem
+    }
+    if (-not $item) { return $false }
+    return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
+}
+
 $activeFile = Join-Path $PlanRoot ".active_plan"
 
 # A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -148,6 +176,9 @@ if (-not $env:PLAN_ID) {
     }
     if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
         foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
+            # A linked plan directory (symlink, junction) is not selectable and
+            # never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
+            if (Test-LinkedDirectory $entry) { continue }
             if ((Test-ValidSlug $entry.Name) -and
                 (Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
                 $planCount++
@@ -165,7 +196,7 @@ if ($planCount -gt 1) { exit 0 }
 if ($env:PLAN_ID) {
     if (Test-ValidSlug $env:PLAN_ID) {
         $candidate = Join-Path $PlanRoot $env:PLAN_ID
-        if ((Test-Path $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
+        if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
             Write-Output $candidate
             exit 0
         }
@@ -175,29 +206,37 @@ if ($env:PLAN_ID) {
 
 # Get-Item observes the link object even when its target is missing, unlike
 # Test-Path which follows the target. An active pointer that is a directory or
-# reparse point is an unsafe/ambiguous selector and must terminate resolution;
+# a symlink is an unsafe/ambiguous selector and must terminate resolution;
 # falling through would silently select and expose the newest unrelated plan.
+# LinkType, not the ReparsePoint attribute: OneDrive Files On-Demand marks
+# every synced file as a reparse point, and such a pointer is a plain file
+# to every other route (#275).
 $activeItem = Get-Item -LiteralPath $activeFile -Force -ErrorAction SilentlyContinue
 if ($activeItem) {
-    if ($activeItem.PSIsContainer -or
-        (($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0)) {
+    if ($activeItem.PSIsContainer -or (Test-LinkedDirectory $activeItem)) {
         exit 0
     }
-    $planId = (Get-Content -LiteralPath $activeFile -Raw).Trim()
+    # Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
+    # falls through like an invalid one instead of raising inside a caller.
+    $planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
     if ($planId -and (Test-ValidSlug $planId)) {
         $candidate = Join-Path $PlanRoot $planId
-        if ((Test-Path $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
+        if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
             Write-Output $candidate
             exit 0
         }
     }
 }
 
-if (Test-Path $PlanRoot -PathType Container) {
-    $latest = Get-ChildItem -Path $PlanRoot -Directory |
+# Literal paths throughout: a project path containing [ or ] is a wildcard to
+# Test-Path and Get-ChildItem -Path, and a pattern that matches nothing turned a
+# valid selection into an empty result.
+if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
+    $latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
         Where-Object { -not $_.Name.StartsWith('.') } |
+        Where-Object { -not (Test-LinkedDirectory $_) } |
         Where-Object { Test-ValidSlug $_.Name } |
-        Where-Object { Test-Path (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
+        Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
         Where-Object { Test-WithinRoot $_.FullName } |
         Sort-Object LastWriteTime -Descending |
         Select-Object -First 1

package/scripts/resolve-plan-dir.sh

@@ -246,10 +246,16 @@ mtime_of() {
     printf "0\n"
 }
 
+# A linked plan directory (symlink or junction; `-L` sees both under Git
+# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
+# newest-mtime scan, and it never counts below (#270). Containment alone let
+# a link that stays inside the root be selected while the counter skipped
+# it, so one real plan plus a newer linked one became an mtime guess again.
 resolve_from_env() {
     plan_id="${PLAN_ID:-}"
     slug_is_valid "${plan_id}" || return 1
     candidate="${PLAN_ROOT}/${plan_id}"
+    [ -L "${candidate}" ] && return 1
     if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
         printf "%s\n" "${candidate}"
         return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
     esac
     slug_is_valid "${plan_id}" || return 1
     candidate="${PLAN_ROOT}/${plan_id}"
+    [ -L "${candidate}" ] && return 1
     if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
         printf "%s\n" "${candidate}"
         return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
         case "${name}" in
             .*) continue ;;
         esac
+        [ -L "${clean}" ] && continue
         slug_is_valid "${name}" || continue
         [ -f "${clean}/task_plan.md" ] || continue
         is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
         PLAN_COUNT=1
     fi
     for plan_candidate in "${PLAN_ROOT}"/*/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

package/scripts/session-catchup.py

@@ -468,13 +468,16 @@ def _opencode_state_annotation(state: Any) -> str:
 
 def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dict[str, Any]]:
     """Print-ready summary for one OpenCode part row."""
+    if not isinstance(data, dict):
+        return None
     ptype = data.get('type')
     short = safe_session_label(session_id)
     if ptype == 'tool':
-        tool = (data.get('tool') or '').lower()
+        tool_value = data.get('tool')
+        tool = tool_value.lower() if isinstance(tool_value, str) else ''
         state = data.get('state') or {}
         input_ = state.get('input') if isinstance(state, dict) else None
-        input_ = input_ or {}
+        input_ = input_ if isinstance(input_, dict) else {}
         outcome = _opencode_state_annotation(state)
         if tool in ('write', 'edit'):
             fp = input_.get('filePath', '')
@@ -486,7 +489,8 @@ def _format_opencode_part(data: Dict[str, Any], session_id: str) -> Optional[Dic
             return {'session': short, 'summary': f"Tool bash: {cmd}{outcome}"}
         return {'session': short, 'summary': f"Tool {tool}{outcome}"}
     if ptype == 'text':
-        text = (data.get('text') or '')[:300]
+        text_value = data.get('text')
+        text = text_value[:300] if isinstance(text_value, str) else ''
         if text.strip():
             return {'session': short, 'summary': f"text: {text}"}
     return None
@@ -577,6 +581,7 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
             """
             SELECT time_created, data FROM part
             WHERE session_id = ?
+              AND json_valid(data)
               AND json_extract(data, '$.type') = 'tool'
               AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
               AND (

package/scripts/set-active-plan.ps1

@@ -121,9 +121,13 @@ function Test-SafeActiveFile {
     param([switch]$AllowLink)
     $item = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
     if (-not $item) { return $false }
-    # Reading may follow a verified in-project link; writing must not.
+    # Reading may follow a verified in-project link; writing must not. A link
+    # is a symlink or junction by LinkType, never the bare ReparsePoint
+    # attribute: OneDrive Files On-Demand marks every synced file as a
+    # reparse point, and the pointer must stay writable there (#275).
+    $linked = ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
     return -not $item.PSIsContainer -and
-        ($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
+        ($AllowLink -or -not $linked) -and
         (Test-WithinRoot $ActiveFile)
 }
 
@@ -204,6 +208,8 @@ function Show-PlanList {
     Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
     $found = $false
     foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
+        # A linked plan directory is never a plan (#270): no resolver selects it.
+        if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
         if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
         $planFile = Join-Path $plan.FullName "task_plan.md"
         if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +287,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
     Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
     exit 1
 }
+$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
+if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
+    Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
+    exit 1
+}
 if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
     Write-Error "Error: plan directory must remain within the project."
     exit 1

package/scripts/set-active-plan.sh

@@ -272,6 +272,9 @@ list_plans() {
     printf '%s\n' 'Available plans:'
     for _dir in "${PLAN_ROOT}"/*; do
         [ -d "${_dir}" ] || continue
+        # A linked plan directory is never a plan (#270): no resolver selects
+        # it, so listing it would advertise a PLAN_ID every route refuses.
+        [ -L "${_dir}" ] && continue
         _id="${_dir##*/}"
         slug_is_valid "${_id}" || continue
         is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
         exit 1
     fi
     plan_id="$(current_active)"
-    if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
+    if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
         printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
     elif [ -n "${plan_id}" ]; then
         printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
         "Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
     exit 1
 fi
+if [ -L "${PLAN_DIR}" ]; then
+    printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
+    exit 1
+fi
 if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
     printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
     exit 1

package/templates/analytics_task_plan.md

@@ -1,81 +1,87 @@
-# Task Plan: [Analytics Project Description]
-
-Use this file as the durable roadmap for a data analytics or exploration session. Keep phase status current as the analysis advances.
-
-## Goal
-
-State the analytical question or intended deliverable in one clear sentence.
-
-[One sentence describing the analytical objective]
-
-## Current Phase
-
-Name the phase currently being worked on.
-
-Phase 1
-
-## Phases
-
-Use only `pending`, `in_progress`, or `complete` for each status.
-
-### Phase 1: Data Discovery
-
-- [ ] Identify and connect to data sources
-- [ ] Document schemas and field descriptions in findings.md
-- [ ] Assess data quality (nulls, duplicates, outliers, date ranges)
-- [ ] Estimate dataset size and query performance
-- **Status:** in_progress
-
-### Phase 2: Exploratory Analysis
-
-- [ ] Compute summary statistics for key variables
-- [ ] Visualize distributions and relationships
-- [ ] Identify outliers and anomalies
-- [ ] Document initial patterns in findings.md
-- **Status:** pending
-
-### Phase 3: Hypothesis Testing
-
-- [ ] Formalize hypotheses from exploratory phase
-- [ ] Select appropriate statistical tests
-- [ ] Run tests and record results in findings.md
-- [ ] Validate findings against holdout data or alternative methods
-- **Status:** pending
-
-### Phase 4: Synthesis & Reporting
-
-- [ ] Summarize key findings with supporting evidence
-- [ ] Create final visualizations
-- [ ] Document conclusions and recommendations
-- [ ] Note limitations and areas for further investigation
-- **Status:** pending
-
-## Hypotheses
-
-Record the questions under investigation as testable hypotheses.
-
-1. [Hypothesis to test]
-2. [Hypothesis to test]
-
-## Decisions Made
-
-Record analytical choices, including tests, filters, exclusions, and their rationale.
-
-| Decision | Rationale |
-|----------|-----------|
-|          |           |
-
-## Errors Encountered
-
-Record each distinct error, the attempt number, and the resolution. Change the approach before retrying a failed action.
-
-| Error | Attempt | Resolution |
-|-------|---------|------------|
-|       | 1       |            |
-
-## Notes
-
-- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
-- Re-read the goal and current phase before major analytical decisions.
-- Log errors promptly so failed approaches are not repeated.
-- Record query results and visual evidence in findings.md.
+# Task Plan: [Analytics Project Description]
+
+Use this file as the durable roadmap for a data analytics or exploration session. Keep phase status current as the analysis advances.
+
+## Goal
+
+State the analytical question or intended deliverable in one clear sentence.
+
+[One sentence describing the analytical objective]
+
+## Next Step
+
+Record the single analytical action that should happen next. Update it whenever the active phase or immediate action changes.
+
+[The single next analytical action. Update whenever phase status changes.]
+
+## Current Phase
+
+Name the phase currently being worked on.
+
+Phase 1
+
+## Phases
+
+Use only `pending`, `in_progress`, or `complete` for each status.
+
+### Phase 1: Data Discovery
+
+- [ ] Identify and connect to data sources
+- [ ] Document schemas and field descriptions in findings.md
+- [ ] Assess data quality (nulls, duplicates, outliers, date ranges)
+- [ ] Estimate dataset size and query performance
+- **Status:** in_progress
+
+### Phase 2: Exploratory Analysis
+
+- [ ] Compute summary statistics for key variables
+- [ ] Visualize distributions and relationships
+- [ ] Identify outliers and anomalies
+- [ ] Document initial patterns in findings.md
+- **Status:** pending
+
+### Phase 3: Hypothesis Testing
+
+- [ ] Formalize hypotheses from exploratory phase
+- [ ] Select appropriate statistical tests
+- [ ] Run tests and record results in findings.md
+- [ ] Validate findings against holdout data or alternative methods
+- **Status:** pending
+
+### Phase 4: Synthesis & Reporting
+
+- [ ] Summarize key findings with supporting evidence
+- [ ] Create final visualizations
+- [ ] Document conclusions and recommendations
+- [ ] Note limitations and areas for further investigation
+- **Status:** pending
+
+## Hypotheses
+
+Record the questions under investigation as testable hypotheses.
+
+1. [Hypothesis to test]
+2. [Hypothesis to test]
+
+## Decisions Made
+
+Record analytical choices, including tests, filters, exclusions, and their rationale.
+
+| Decision | Rationale |
+|----------|-----------|
+|          |           |
+
+## Errors Encountered
+
+Record each distinct error, the attempt number, and the resolution. Change the approach before retrying a failed action.
+
+| Error | Attempt | Resolution |
+|-------|---------|------------|
+|       | 1       |            |
+
+## Notes
+
+- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
+- Re-read the goal, next step, and current phase before major analytical decisions.
+- Log errors promptly so failed approaches are not repeated.
+- Record query results and visual evidence in findings.md.