Compare commits

...
36 Commits
Author SHA1 Message Date
OthmanAdi 3b7690eafd release: v3.20.7 2026-09-23 22:13:44 +02:00
OthmanAdi f473fa8930 fix: disclose Pi package planning capabilities 2026-09-23 22:09:00 +02:00
OthmanAdi 3827d3c018 release: v3.20.6 2026-09-23 21:58:59 +02:00
OthmanAdi b7edae42dc fix: retry transient PowerShell pointer inspection 2026-09-23 21:51:09 +02:00
OthmanAdi 10c64d464e fix: compare canonical active plan pointer roots 2026-09-23 21:16:28 +02:00
TayfurYldz a82c5a4588 fix: keep DSH core in sync 2026-09-23 21:16:28 +02:00
TayfurYldz 16b6a452bc fix: replace OpenCode active pointer safely 2026-09-23 21:16:28 +02:00
TayfurYldz abd39f7e9b fix: retry concurrent PowerShell pointer replacement 2026-09-23 20:55:49 +02:00
TayfurYldz 388b591f77 fix: recover PowerShell bracketed project cwd 2026-09-23 20:55:43 +02:00
TayfurYldz 87b2553fa1 test: scope read-only pointer case to Windows 2026-09-23 20:55:38 +02:00
TayfurYldz a3bd42954b fix: reject read-only active plan pointers 2026-09-23 20:55:38 +02:00
TayfurYldz 5165ffe847 fix: replace Hermes active pointer safely 2026-09-23 20:55:22 +02:00
kuei51307-hub f7b9be9d58 fix(locking): claim phase status lock atomically 2026-09-23 20:54:59 +02:00
OthmanAdi 0827eeaecf docs: add official skills.sh install badge 2026-09-22 22:07:58 +02:00
OthmanAdi 09d2254d76 docs: restore ClawHub chart below star history 2026-09-22 21:58:33 +02:00
OthmanAdi 78e5bf7b5b docs: simplify star history to the graph 2026-09-22 21:57:34 +02:00
OthmanAdi 27ab93c15d docs: show full star history below reference dropdown 2026-09-22 21:49:40 +02:00
OthmanAdi 4a40450390 docs: remove workflow caption 2026-09-22 19:51:19 +02:00
OthmanAdi 0bd06d344b docs: refresh README layout and visual story 2026-09-22 17:38:29 +02:00
OthmanAdi 5ac39bcb41 docs: align v3.20.5 citation date and replay description 2026-09-21 21:00:22 +02:00
OthmanAdi b81c488d46 release: v3.20.5 2026-09-21 20:59:55 +02:00
Shaun Lin f869dfb4d0 fix: fail PowerShell init on denied writes 2026-09-21 20:57:40 +02:00
kuei51307-hub 428b96c982 fix(init): report attestation failures 2026-09-21 20:57:36 +02:00
kuei51307-hub cd0bc3d202 fix(templates): add analytics next step 2026-09-21 20:56:57 +02:00
TayfurYldz 5ad5452276 fix: tolerate malformed OpenCode replay parts 2026-09-21 20:56:53 +02:00
OthmanAdi 726da18dc7 release: v3.20.4
PowerShell route on OneDrive (#275: pointer checks and the attester refuse only symlinks, junctions and name-surrogate reparse points) and the session-catchup copy guard checks tracked copies only (#274). Parity set bumped with scripts/bump-version.py; CHANGELOG, README releases row.
2026-09-19 20:39:00 +02:00
OthmanAdi 3a4f2077be fix(powershell): attest-plan.ps1 refuses only name-surrogate reparse points
ValidateRegular in the attester's native helper threw "Refusing a
reparse-point file" for any file with the ReparsePoint attribute, so in a
project under OneDrive (Files On-Demand marks every synced file, tag
0x9000601A) attestation, --show and --clear all failed, and init-session.ps1
still printed "attested" because it swallows the attester's failure. The
check now refuses only name-surrogate tags (bit 29 set: symlinks, junctions
and any unknown surrogate), which is exactly the set Windows path parsing
follows, so the security property is unchanged and placeholder files read
as the regular files they are. Every mirror synced (#275).
2026-09-19 20:35:25 +02:00
OthmanAdi 864577857d test: keep the exact session-catchup.py basename on the git pathspec 2026-09-19 20:35:25 +02:00
OthmanAdi a33fc3eb1a fix(powershell): the .active_plan pointer check is LinkType, not the ReparsePoint attribute
resolve-plan-dir.ps1, the Cursor hook resolve-plan-context.ps1 and the
set-active-plan.ps1 writer refused an .active_plan pointer that carried the
ReparsePoint attribute. OneDrive Files On-Demand marks every synced file as
a reparse point, so in a project under OneDrive the Cursor hooks stopped
with the unsafe-pointer notice, the resolver printed nothing for
attest-plan.ps1 and check-complete.ps1, and set-active-plan.ps1 refused to
write, while every other route read the pointer normally. The three checks
now refuse a container or a LinkType of SymbolicLink or Junction, the same
predicate v3.20.3 gave the directory checks and the `[ -L ]` of the shell
scripts. Every mirror synced. Tests cover the plain pointer and the
symlinked pointer (skipped where file symlinks need a privilege). Fixes #275.
2026-09-19 20:18:27 +02:00
OthmanAdi 85dfd5dcdd test: check only tracked session-catchup.py copies
The exact-basename guard walked the whole checkout, so any untracked copy
of session-catchup.py, such as a stale clone kept under the gitignored
.planning/ directory on a maintainer machine, was loaded as a shipped copy
and failed the two tests with 120 subtests while CI stayed green. Shipped
means tracked: the copies now come from git ls-files, with the filtered
walk kept only for a checkout without git, where .planning and .git are
excluded as well. Fixes #274.
2026-09-19 20:18:27 +02:00
OthmanAdi 57fe376da9 release: v3.20.3
A symlinked or junctioned directory under .planning/ is never a plan on
any route (#270, PR #271 by @ShaunLinTW plus three maintainer commits).

Parity set bumped to 3.20.3 with scripts/bump-version.py. CHANGELOG,
CONTRIBUTORS.md (PR #271 for Shaun Lin), README releases row.
2026-09-19 11:24:08 +02:00
OthmanAdi 663908180e docs(hermes): name the routes that share the linked-directory rule 2026-09-19 11:23:53 +02:00
OthmanAdi f54f8144c2 fix(scripts): match symlinks and junctions only, and keep linked directories out of set-active-plan
Review of the previous two commits found the PowerShell resolver testing the
ReparsePoint attribute, which every OneDrive Files On-Demand directory
carries: a project under OneDrive would have lost every plan on the Cursor
route. The resolver now tests LinkType for SymbolicLink or Junction, the
exact `[ -L ]` of the shell scripts and is_link of the Python twin, and the
Codex counter uses the same symlink-or-junction tag rule instead of the
adapter's any-reparse helper.

set-active-plan.sh and set-active-plan.ps1 refuse to point the shared
default at a linked directory and leave it out of --list, since no route
selects it; the sh/py/ps1 suites cover PLAN_ID naming a link (refused with
the existing notice) and the pointer naming one (falls through to the real
plan like a stale pointer). Hermes docstring names the routes precisely (#270).
2026-09-19 11:13:08 +02:00
OthmanAdi 95cf6f499b fix(adapters): skip linked plan directories in the Codex, OpenCode and DSH plan counters
The Codex adapter's session_plan_requires_binding and the shared
countSelectablePlans of the OpenCode and DeepSeek Harness plugins counted a
symlinked or junctioned plan directory although their selection paths (and
the shell family since the previous commit) refuse it. A linked directory
never counts now, so the several-plans notice fires on the same trees on
every route. The two TypeScript cores stay byte-identical (#270).
2026-09-19 10:44:07 +02:00
OthmanAdi 0308a2f819 fix(scripts): a linked plan directory is never selectable, on every shell-family route
PR #271 made the several-plans counters in inject-plan.sh and
resolve-plan-dir.sh skip symlinked and junctioned plan directories, matching
the Hermes plugin. Skipping the link in the counter alone left the selection
paths following it through containment: one real plan plus a newer linked
one counted as one plan and the newest-mtime scan then selected the linked
directory, the mtime guess the #240 rule exists to prevent. The PowerShell
twin reproduced that after the counter port.

The rule now holds end to end in the shell family: resolve-plan-dir.sh,
inject-plan.sh, resolve-plan-dir.ps1 and the Python twin inject-plan.py
refuse a linked plan directory in the PLAN_ID, .active_plan and
newest-mtime branches and never count it. Every shipped copy is synced.

Tests: the sh/py parity suite gains the linked-directory fixture (the twin
contract), and test_unarmed_plan_ambiguity drives both resolvers and both
injectors over a real plan plus a junction or symlink (#270).
2026-09-19 10:43:59 +02:00
Shaun Lin 0bbc43cff3 fix: skip linked plan dirs in ambiguity counts 2026-09-19 10:36:51 +02:00
231 changed files with 6918 additions and 1304 deletions
+1 -1
View File
@@ -28,7 +28,7 @@ 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"
metadata:
version: "3.20.2"
version: "3.20.7"
---
# Planning with Files
@@ -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.");
@@ -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!"
@@ -355,8 +428,11 @@ if ($Mode -ne "") {
# 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
@@ -370,21 +446,54 @@ if ($Mode -ne "") {
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
@@ -399,5 +508,9 @@ if ($Mode -ne "") {
}
}
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)"
}
}
@@ -186,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"
@@ -210,13 +214,54 @@ apply_v3_mode() {
# ./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}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
if [ "$SLUG_MODE" -eq 1 ]; then
PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" >/dev/null 2>&1 || true
_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
PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" >/dev/null 2>&1 || true
_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
}
@@ -431,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}"
@@ -442,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
@@ -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"):
@@ -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)
@@ -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
@@ -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
@@ -139,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
@@ -158,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++
@@ -175,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 -LiteralPath $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
}
@@ -185,12 +206,14 @@ 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
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $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
}
@@ -211,6 +234,7 @@ if ($activeItem) {
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 -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -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
@@ -468,10 +468,13 @@ 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_ if isinstance(input_, dict) else {}
@@ -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
@@ -121,9 +121,14 @@ 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
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,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 +288,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
@@ -305,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)"
@@ -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
@@ -8,6 +8,12 @@ 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.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- 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.
+1 -1
View File
@@ -10,7 +10,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Installs across 60+ agents.",
"version": "3.20.2"
"version": "3.20.7"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.20.2",
"version": "3.20.7",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Works across 60+ agents and includes Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese.",
"author": {
"name": "OthmanAdi",
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"${CODEBUDDY_PLUGIN_ROOT}/scripts/skill-hook.sh\" \"$HOME/.codebuddy/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.2"
version: "3.20.7"
---
@@ -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.");
@@ -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!"
@@ -355,8 +428,11 @@ if ($Mode -ne "") {
# 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
@@ -370,21 +446,54 @@ if ($Mode -ne "") {
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
@@ -399,5 +508,9 @@ if ($Mode -ne "") {
}
}
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)"
}
}
@@ -186,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"
@@ -210,13 +214,54 @@ apply_v3_mode() {
# ./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}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
if [ "$SLUG_MODE" -eq 1 ]; then
PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" >/dev/null 2>&1 || true
_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
PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" >/dev/null 2>&1 || true
_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
}
@@ -431,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}"
@@ -442,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
@@ -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"):
@@ -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)
@@ -139,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
@@ -158,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++
@@ -175,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 -LiteralPath $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
}
@@ -185,12 +206,14 @@ 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
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $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
}
@@ -211,6 +234,7 @@ if ($activeItem) {
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 -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -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
@@ -468,10 +468,13 @@ 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_ if isinstance(input_, dict) else {}
@@ -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
@@ -121,9 +121,14 @@ 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
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,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 +288,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
@@ -305,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)"
@@ -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
@@ -8,6 +8,12 @@ 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.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- 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.
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.20.2",
"version": "3.20.7",
"description": "Persistent project planning for Codex. Opt-in lifecycle hooks inject selected plan context; automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs Markdown-declared commands. No network upload path.",
"author": {
"name": "OthmanAdi",
+25
View File
@@ -90,6 +90,27 @@ def _is_reparse_or_link(path: Path) -> bool:
return bool(attrs & reparse)
_LINK_REPARSE_TAGS = (0xA000000C, 0xA0000003) # IO_REPARSE_TAG_SYMLINK, _MOUNT_POINT
def _is_linked_directory(path: Path) -> bool:
"""`[ -L ]` of the shell scripts: a symlink, or a junction on Windows.
Narrower than _is_reparse_or_link on purpose: OneDrive Files On-Demand
marks every synced directory as a reparse point, and those are plans.
"""
try:
info = path.lstat()
except OSError:
return False
if stat.S_ISLNK(info.st_mode):
return True
reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
if getattr(info, "st_file_attributes", 0) & reparse:
return getattr(info, "st_reparse_tag", 0) in _LINK_REPARSE_TAGS
return False
def _is_trusted_darwin_system_alias(path: Path) -> bool:
"""Admit only macOS's fixed root aliases after verifying their targets."""
if sys.platform != "darwin":
@@ -243,6 +264,10 @@ def session_plan_requires_binding(root: Path) -> bool:
for child in planning_dir.iterdir():
if not _PLAN_SLUG.fullmatch(child.name) or not child.is_dir():
continue
# A linked plan directory is not selectable and never counts,
# matching `[ -L ]` in the shell counters (#270).
if _is_linked_directory(child):
continue
if (child / "task_plan.md").is_file():
candidates += 1
if candidates > 1:
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.2"
version: "3.20.7"
---
@@ -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.");
@@ -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!"
@@ -355,8 +428,11 @@ if ($Mode -ne "") {
# 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
@@ -370,21 +446,54 @@ if ($Mode -ne "") {
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
@@ -399,5 +508,9 @@ if ($Mode -ne "") {
}
}
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)"
}
}
@@ -186,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"
@@ -210,13 +214,54 @@ apply_v3_mode() {
# ./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}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
if [ "$SLUG_MODE" -eq 1 ]; then
PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" >/dev/null 2>&1 || true
_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
PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" >/dev/null 2>&1 || true
_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
}
@@ -431,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}"
@@ -442,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
@@ -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"):
@@ -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)
@@ -139,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
@@ -158,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++
@@ -175,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 -LiteralPath $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
}
@@ -185,12 +206,14 @@ 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
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $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
}
@@ -211,6 +234,7 @@ if ($activeItem) {
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 -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -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
@@ -468,10 +468,13 @@ 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_ if isinstance(input_, dict) else {}
@@ -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
@@ -121,9 +121,14 @@ 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
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,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 +288,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
@@ -305,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)"
@@ -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
@@ -8,6 +8,12 @@ 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.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- 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.
@@ -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.");
@@ -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!"
@@ -355,8 +428,11 @@ if ($Mode -ne "") {
# 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
@@ -370,21 +446,54 @@ if ($Mode -ne "") {
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
@@ -399,5 +508,9 @@ if ($Mode -ne "") {
}
}
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)"
}
}
@@ -186,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"
@@ -210,13 +214,54 @@ apply_v3_mode() {
# ./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}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
if [ "$SLUG_MODE" -eq 1 ]; then
PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" >/dev/null 2>&1 || true
_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
PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" >/dev/null 2>&1 || true
_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
}
@@ -431,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}"
@@ -442,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
@@ -139,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
@@ -158,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++
@@ -175,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 -LiteralPath $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
}
@@ -185,12 +206,14 @@ 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
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $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
}
@@ -211,6 +234,7 @@ if ($activeItem) {
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 -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -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
@@ -468,10 +468,13 @@ 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_ if isinstance(input_, dict) else {}
@@ -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
@@ -121,9 +121,14 @@ 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
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,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 +288,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
@@ -305,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)"
@@ -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
+5 -1
View File
@@ -88,9 +88,13 @@ function Resolve-CursorPlanContext {
# inject-plan.sh is. A stale pointer text, a dot-named directory or an
# invalid slug is ignored the way inject-plan.sh ignores it, so the legacy
# root applies, as on every other route.
# A pointer that is a directory or a symlink is unsafe. 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; the attribute test made this hook go silent on OneDrive (#275).
$activeItem = Get-Item -LiteralPath (Join-Path $planRoot '.active_plan') -Force -ErrorAction SilentlyContinue
if ($activeItem -and ($activeItem.PSIsContainer -or
(($activeItem.Attributes -band [IO.FileAttributes]::ReparsePoint) -ne 0))) {
(([string]$activeItem.LinkType) -in @('SymbolicLink', 'Junction')))) {
return (New-CursorPlanContext $null 'invalid' 'unsafe-pointer')
}
if ($planRootExists) {
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.2"
version: "3.20.7"
---
@@ -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.");
@@ -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!"
@@ -355,8 +428,11 @@ if ($Mode -ne "") {
# 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
@@ -370,21 +446,54 @@ if ($Mode -ne "") {
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
@@ -399,5 +508,9 @@ if ($Mode -ne "") {
}
}
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)"
}
}
@@ -186,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"
@@ -210,13 +214,54 @@ apply_v3_mode() {
# ./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}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
if [ "$SLUG_MODE" -eq 1 ]; then
PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" >/dev/null 2>&1 || true
_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
PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" >/dev/null 2>&1 || true
_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
}
@@ -431,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}"
@@ -442,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
@@ -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"):
@@ -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)
@@ -139,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
@@ -158,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++
@@ -175,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 -LiteralPath $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
}
@@ -185,12 +206,14 @@ 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
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $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
}
@@ -211,6 +234,7 @@ if ($activeItem) {
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 -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -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
@@ -468,10 +468,13 @@ 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_ if isinstance(input_, dict) else {}
@@ -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
@@ -121,9 +121,14 @@ 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
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,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 +288,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
@@ -305,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)"
@@ -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
@@ -8,6 +8,12 @@ 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.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- 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.
@@ -188,8 +188,14 @@ describe("resolver", () => {
fs.writeFileSync(path.join(planning, ".active_plan"), "2026-09-02-evil\n")
expect(resolvePlan(root, {}, env).planDir).toBeNull()
expect(resolvePlan(root, {}, { ...env, PLAN_ID: "2026-09-02-evil" }).planDir).toBeNull()
// a linked plan directory never counts toward the several-plans rule (#270)
expect(countSelectablePlans(root)).toBe(0)
const real = path.join(planning, "2026-09-02-real")
fs.mkdirSync(real)
fs.writeFileSync(path.join(real, "task_plan.md"), "# REAL\n")
expect(countSelectablePlans(root)).toBe(1)
expect(resolvePlan(root, {}, env).planDir).toBe(real)
fs.rmSync(path.join(real, "task_plan.md"))
try {
fs.symlinkSync(path.join(outside, "task_plan.md"), path.join(real, "task_plan.md"), "file")
} catch {
@@ -366,6 +372,41 @@ describe("init and status", () => {
expect(buildContext(root, dir)).toContain("[planning-with-files] plan: ")
})
it("updates a regular active plan pointer through a directory junction project root", () => {
const linkedRoot = `${root}-junction`
fs.symlinkSync(root, linkedRoot, "junction")
try {
const first = initPlan(linkedRoot, { name: "First" }, env)
expect(first.ok).toBe(true)
const second = initPlan(linkedRoot, { name: "Second" }, env)
expect(second.ok).toBe(true)
const pointer = path.join(root, ".planning", ".active_plan")
expect(fs.lstatSync(pointer).isFile()).toBe(true)
expect(fs.readFileSync(pointer, "utf8")).toBe(`${second.plan_id}\n`)
} finally {
fs.rmSync(linkedRoot, { recursive: true, force: true })
}
})
it("refuses a linked planning directory without changing its external pointer", () => {
const outside = `${root}-outside`
const planning = path.join(root, ".planning")
fs.mkdirSync(outside)
const pointer = path.join(outside, ".active_plan")
fs.writeFileSync(pointer, "external-plan\n")
fs.symlinkSync(outside, planning, "junction")
try {
const result = initPlan(root, { name: "Blocked" }, env)
expect(result.ok).toBe(false)
expect(result.error).toContain("unsafe active plan pointer")
expect(fs.readFileSync(pointer, "utf8")).toBe("external-plan\n")
expect(fs.readdirSync(outside)).toEqual([".active_plan"])
} finally {
fs.rmSync(planning, { recursive: true, force: true })
fs.rmSync(outside, { recursive: true, force: true })
}
})
it("uses a real skill template when one is discoverable, and rejects unknown modes", () => {
const skill = path.join(root, ".agents", "skills", "planning-with-files", "templates")
fs.mkdirSync(skill, { recursive: true })
@@ -86,6 +86,40 @@ function writeText(target: string, text: string): void {
fs.writeFileSync(target, text, { encoding: "utf8" })
}
function activePlanPointerError(planningRoot: string): string | null {
const pointer = path.join(planningRoot, ".active_plan")
const realRoot = realpathOrNull(planningRoot)
if (!isRealDir(planningRoot) || !realRoot) return `refusing to replace unsafe active plan pointer: ${pointer}`
if (!fs.existsSync(pointer)) return null
const st = lstatSafe(pointer)
const real = realpathOrNull(pointer)
return !st || !st.isFile() || st.isSymbolicLink() || st.nlink > 1 || !real || !isInside(real, realRoot)
? `refusing to replace unsafe active plan pointer: ${pointer}`
: null
}
function writeActivePlan(planningRoot: string, planId: string): string | null {
const pointer = path.join(planningRoot, ".active_plan")
const unsafe = activePlanPointerError(planningRoot)
if (unsafe) return unsafe
const tmp = path.join(planningRoot, `.active_plan.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`)
let fd: number | null = null
try {
fd = fs.openSync(tmp, "wx")
fs.writeFileSync(fd, `${planId}\n`, { encoding: "utf8" })
fs.closeSync(fd)
fd = null
fs.renameSync(tmp, pointer)
return null
} catch (err) {
return `could not safely update active plan pointer: ${err instanceof Error ? err.message : String(err)}`
} finally {
if (fd !== null) fs.closeSync(fd)
try { fs.unlinkSync(tmp) } catch { /* already renamed or absent */ }
}
}
function realpathOrNull(target: string): string | null {
try {
return fs.realpathSync(target)
@@ -205,6 +239,9 @@ export function countSelectablePlans(root: string): number {
}
for (const entry of entries) {
if (!slugIsValid(entry)) continue
// A linked plan directory is not selectable and never counts (#270),
// matching the shell counters, the Hermes plugin and resolvePlan below.
if (!isRealDir(path.join(planningRoot, entry))) continue
if (!isRegularFile(path.join(planningRoot, entry, "task_plan.md"))) continue
count += 1
if (count > 1) break
@@ -733,8 +770,11 @@ export function initPlan(
fs.mkdirSync(planningRoot, { recursive: true })
planId = `${new Date().toISOString().slice(0, 10)}-${slug}`
planDir = path.join(planningRoot, planId)
const pointerError = activePlanPointerError(planningRoot)
if (pointerError) return { ok: false, error: pointerError, project_dir: root }
fs.mkdirSync(planDir, { recursive: true })
writeText(path.join(planningRoot, ".active_plan"), `${planId}\n`)
const writeError = writeActivePlan(planningRoot, planId)
if (writeError) return { ok: false, error: writeError, project_dir: root }
}
const created = copyTemplates(planDir, templatesDir, template)
const result: InitResult = {
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.2"
version: "3.20.7"
---
# Planning with Files
@@ -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.");
@@ -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!"
@@ -355,8 +428,11 @@ if ($Mode -ne "") {
# 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
@@ -370,21 +446,54 @@ if ($Mode -ne "") {
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
@@ -399,5 +508,9 @@ if ($Mode -ne "") {
}
}
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)"
}
}
@@ -186,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"
@@ -210,13 +214,54 @@ apply_v3_mode() {
# ./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}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
if [ "$SLUG_MODE" -eq 1 ]; then
PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" >/dev/null 2>&1 || true
_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
PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" >/dev/null 2>&1 || true
_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
}
@@ -431,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}"
@@ -442,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
@@ -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"):
@@ -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)
@@ -139,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
@@ -158,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++
@@ -175,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 -LiteralPath $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
}
@@ -185,12 +206,14 @@ 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
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $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
}
@@ -211,6 +234,7 @@ if ($activeItem) {
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 -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -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
@@ -468,10 +468,13 @@ 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_ if isinstance(input_, dict) else {}
@@ -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
@@ -121,9 +121,14 @@ 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
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,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 +288,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
@@ -305,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)"
@@ -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
@@ -8,6 +8,12 @@ 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.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- 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.
@@ -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.");
@@ -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!"
@@ -355,8 +428,11 @@ if ($Mode -ne "") {
# 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
@@ -370,21 +446,54 @@ if ($Mode -ne "") {
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
@@ -399,5 +508,9 @@ if ($Mode -ne "") {
}
}
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)"
}
}
@@ -186,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"
@@ -210,13 +214,54 @@ apply_v3_mode() {
# ./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}/attest-plan.sh"
if [ -f "${_attest}" ] && [ -f "${_mode_plan}" ]; then
if [ "$SLUG_MODE" -eq 1 ]; then
PWF_PLAN_ROOT="$PWD" PLAN_ID="${PLAN_ID}" sh "${_attest}" >/dev/null 2>&1 || true
_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
PWF_PLAN_ROOT="" PLAN_ID="" sh "${_attest}" >/dev/null 2>&1 || true
_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
}
@@ -431,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}"
@@ -442,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
@@ -139,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
@@ -158,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++
@@ -175,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 -LiteralPath $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
}
@@ -185,12 +206,14 @@ 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
}
# Get-Content -Raw returns $null for a zero-byte pointer; an empty pointer
@@ -198,7 +221,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $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
}
@@ -211,6 +234,7 @@ if ($activeItem) {
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 -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -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
@@ -468,10 +468,13 @@ 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_ if isinstance(input_, dict) else {}
@@ -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
@@ -121,9 +121,14 @@ 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
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,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 +288,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
@@ -305,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)"
@@ -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
@@ -8,6 +8,12 @@ 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.
@@ -76,6 +82,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- 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.
+4 -1
View File
@@ -290,7 +290,10 @@ def resolve_plan(
continues through .planning/.active_plan, the newest
.planning/<slug>/task_plan.md by modification time, then the legacy root
task_plan.md. Slugs are validated and the chosen directory must stay
inside .planning (no symlink or junction escape).
inside .planning (no symlink or junction escape). A linked plan directory
never counts and never resolves here; since v3.20.3 the shell family, the
Python twin, the Codex adapter and the OpenCode and DSH cores apply the
same rule (#270).
A cwd guess (pointer, newest, or legacy root) is refused when a direct
child of the root carries its own live plan (issue #212): the result is
@@ -115,6 +115,46 @@ def apply_v3_mode(project_dir: Path, plan_dir: Path, mode: str) -> dict[str, Any
return {"marker": marker.strip(), "attestation": digest}
def _active_plan_pointer_error(planning_root: Path) -> str | None:
pointer = planning_root / ".active_plan"
if not pointer.exists() and not pointer.is_symlink():
return None
try:
stat = pointer.lstat()
resolved = pointer.resolve(strict=True)
resolved.relative_to(planning_root.resolve(strict=True))
except (OSError, ValueError):
return f"refusing to replace unsafe active plan pointer: {pointer}"
if pointer.is_symlink() or not pointer.is_file() or stat.st_nlink > 1:
return f"refusing to replace unsafe active plan pointer: {pointer}"
return None
def _write_active_plan(planning_root: Path, plan_id: str) -> str | None:
pointer = planning_root / ".active_plan"
unsafe = _active_plan_pointer_error(planning_root)
if unsafe:
return unsafe
temp = planning_root / f".active_plan.{os.getpid()}.{secrets.token_hex(4)}.tmp"
fd: int | None = None
try:
fd = os.open(temp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "w", encoding="utf-8") as handle:
fd = None
handle.write(plan_id + "\n")
os.replace(temp, pointer)
return None
except OSError as exc:
return f"could not safely update active plan pointer: {exc}"
finally:
if fd is not None:
os.close(fd)
try:
temp.unlink()
except FileNotFoundError:
pass
def init_plan(
project_dir: Path,
*,
@@ -147,8 +187,13 @@ def init_plan(
planning_root.mkdir(parents=True, exist_ok=True)
plan_id = f"{_dt.date.today().isoformat()}-{slug}"
plan_dir = planning_root / plan_id
pointer_error = _active_plan_pointer_error(planning_root)
if pointer_error:
return {"ok": False, "error": pointer_error, "project_dir": str(project_dir)}
plan_dir.mkdir(exist_ok=True)
(planning_root / ".active_plan").write_text(plan_id + "\n", encoding="utf-8")
write_error = _write_active_plan(planning_root, plan_id)
if write_error:
return {"ok": False, "error": write_error, "project_dir": str(project_dir)}
else:
plan_dir = project_dir
plan_id = "root"
+1 -1
View File
@@ -2,7 +2,7 @@
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."
metadata:
version: "3.20.2"
version: "3.20.7"
hermes:
tags: [planning, long-running-tasks, context-engineering, workflow]
---
@@ -7,6 +7,8 @@ param(
[string]$Template = "default"
)
$ErrorActionPreference = "Stop"
$DATE = Get-Date -Format "yyyy-MM-dd"
# Resolve template directory (skill root is one level up from scripts/)
@@ -121,9 +121,14 @@ 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
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,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 +288,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
@@ -305,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)"
@@ -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
@@ -8,6 +8,12 @@ State what the analysis should determine or produce 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.
@@ -84,6 +90,6 @@ Record each distinct error, the attempt number, and the resolution. Change the a
## Notes
- Update phase status as work progresses: `pending` to `in_progress` to `complete`.
- Re-read the goal and current phase before major analytical decisions.
- 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 findings in findings.md while the evidence is available.
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.mastracode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.2"
version: "3.20.7"
---
@@ -5,6 +5,8 @@ param(
[string]$ProjectName = "project"
)
$ErrorActionPreference = "Stop"
$DATE = Get-Date -Format "yyyy-MM-dd"
Write-Host "Initializing planning files for: $ProjectName"
@@ -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"):
@@ -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)
@@ -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
@@ -121,9 +121,14 @@ 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
($AllowLink -or -not $item.IsReadOnly) -and
(Test-WithinRoot $ActiveFile)
}
@@ -204,6 +209,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 +288,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
@@ -305,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)"
@@ -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

Some files were not shown because too many files have changed in this diff Show More