Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
3b7690eafd | ||
|
|
f473fa8930 | ||
|
|
3827d3c018 | ||
|
|
b7edae42dc | ||
|
|
10c64d464e | ||
|
|
a82c5a4588 | ||
|
|
16b6a452bc | ||
|
|
abd39f7e9b | ||
|
|
388b591f77 | ||
|
|
87b2553fa1 | ||
|
|
a3bd42954b | ||
|
|
5165ffe847 | ||
|
|
f7b9be9d58 | ||
|
|
0827eeaecf | ||
|
|
09d2254d76 | ||
|
|
78e5bf7b5b | ||
|
|
27ab93c15d | ||
|
|
4a40450390 | ||
|
|
0bd06d344b | ||
|
|
5ac39bcb41 | ||
|
|
b81c488d46 | ||
|
|
f869dfb4d0 | ||
|
|
428b96c982 | ||
|
|
cd0bc3d202 | ||
|
|
5ad5452276 | ||
|
|
726da18dc7 | ||
|
|
3a4f2077be | ||
|
|
864577857d | ||
|
|
a33fc3eb1a | ||
|
|
85dfd5dcdd |
@@ -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.3"
|
||||
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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -144,7 +144,8 @@ function Test-WithinRoot {
|
||||
# (#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 carries and which are not links to sh.
|
||||
# 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]) {
|
||||
@@ -205,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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -312,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)"
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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.3"
|
||||
"version": "3.20.7"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "planning-with-files",
|
||||
"version": "3.20.3",
|
||||
"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.3"
|
||||
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
|
||||
|
||||
@@ -144,7 +144,8 @@ function Test-WithinRoot {
|
||||
# (#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 carries and which are not links to sh.
|
||||
# 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]) {
|
||||
@@ -205,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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -312,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)"
|
||||
|
||||
@@ -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,6 +1,6 @@
|
||||
{
|
||||
"name": "planning-with-files",
|
||||
"version": "3.20.3",
|
||||
"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",
|
||||
|
||||
@@ -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.3"
|
||||
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
|
||||
|
||||
@@ -144,7 +144,8 @@ function Test-WithinRoot {
|
||||
# (#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 carries and which are not links to sh.
|
||||
# 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]) {
|
||||
@@ -205,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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -312,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)"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -144,7 +144,8 @@ function Test-WithinRoot {
|
||||
# (#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 carries and which are not links to sh.
|
||||
# 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]) {
|
||||
@@ -205,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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -312,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)"
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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.3"
|
||||
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
|
||||
|
||||
@@ -144,7 +144,8 @@ function Test-WithinRoot {
|
||||
# (#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 carries and which are not links to sh.
|
||||
# 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]) {
|
||||
@@ -205,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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -312,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)"
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -372,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)
|
||||
@@ -736,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 = {
|
||||
|
||||
@@ -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.3"
|
||||
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
|
||||
|
||||
@@ -144,7 +144,8 @@ function Test-WithinRoot {
|
||||
# (#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 carries and which are not links to sh.
|
||||
# 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]) {
|
||||
@@ -205,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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -312,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)"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -144,7 +144,8 @@ function Test-WithinRoot {
|
||||
# (#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 carries and which are not links to sh.
|
||||
# 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]) {
|
||||
@@ -205,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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -312,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)"
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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.3"
|
||||
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)
|
||||
}
|
||||
|
||||
@@ -312,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)"
|
||||
|
||||
@@ -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.3"
|
||||
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"
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -312,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)"
|
||||
|
||||
@@ -372,6 +372,56 @@ 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("refuses a hard-linked active plan pointer without modifying its sibling", () => {
|
||||
const planning = path.join(root, ".planning")
|
||||
fs.mkdirSync(planning, { recursive: true })
|
||||
const sibling = path.join(root, "pointer-sibling.txt")
|
||||
fs.writeFileSync(sibling, "existing-plan\n")
|
||||
fs.linkSync(sibling, path.join(planning, ".active_plan"))
|
||||
|
||||
const result = initPlan(root, { name: "Night Run" }, env)
|
||||
|
||||
expect(result.ok).toBe(false)
|
||||
expect(result.error).toContain("unsafe active plan pointer")
|
||||
expect(fs.readFileSync(sibling, "utf8")).toBe("existing-plan\n")
|
||||
expect(fs.readdirSync(planning)).toEqual([".active_plan"])
|
||||
})
|
||||
|
||||
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)
|
||||
@@ -736,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 = {
|
||||
|
||||
@@ -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/.config/opencode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.opencode/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.3"
|
||||
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"
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -312,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)"
|
||||
|
||||
@@ -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.
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -1,5 +1,5 @@
|
||||
---
|
||||
name: pi-planning-with-files
|
||||
name: planning-with-files
|
||||
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
|
||||
user-invocable: true
|
||||
allowed-tools: "Read Write Edit Bash Glob Grep"
|
||||
@@ -7,26 +7,28 @@ hooks:
|
||||
UserPromptSubmit:
|
||||
- hooks:
|
||||
- type: command
|
||||
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=userprompt; exit 0"
|
||||
command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=userprompt; exit 0"
|
||||
PreToolUse:
|
||||
- matcher: "Write|Edit|Bash|Read|Glob|Grep"
|
||||
hooks:
|
||||
- type: command
|
||||
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=pretool; exit 0"
|
||||
command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=pretool; exit 0"
|
||||
PostToolUse:
|
||||
- matcher: "Write|Edit"
|
||||
hooks:
|
||||
- type: command
|
||||
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=posttool; exit 0"
|
||||
command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=posttool; exit 0"
|
||||
Stop:
|
||||
- hooks:
|
||||
- type: command
|
||||
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=stop; exit 0"
|
||||
command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=stop; exit 0"
|
||||
PreCompact:
|
||||
- matcher: "*"
|
||||
hooks:
|
||||
- type: command
|
||||
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
command: "[ -n \"${CLAUDE_PLUGIN_ROOT:-}\" ] && exit 0; SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
|
||||
metadata:
|
||||
version: "3.20.7"
|
||||
---
|
||||
|
||||
# Planning with Files
|
||||
@@ -221,7 +223,7 @@ Copy these templates to start:
|
||||
Helper scripts for automation:
|
||||
|
||||
- `scripts/init-session.sh` — Initialize planning files. With a name arg, creates an isolated plan under `.planning/YYYY-MM-DD-<slug>/` for parallel task workflows. Without args, writes `task_plan.md` at project root (legacy mode, backward-compatible).
|
||||
- `scripts/set-active-plan.sh` — Switch the active plan pointer (`.planning/.active_plan`). Run with a plan ID to switch; run without args to show which plan is current.
|
||||
- `scripts/set-active-plan.sh` — Switch or inspect the active plan pointer (`.planning/.active_plan`). Run with `--list` to show named plans and phase counts, with a plan ID to switch, or without args to show which plan is current.
|
||||
- `scripts/resolve-plan-dir.sh` — Resolve the active plan directory. A set `$PLAN_ID` is a binding: it resolves or resolution stops, never another plan (issue #237). With no `$PLAN_ID`, multiple named plans refuse selection. A single named plan may use `.planning/.active_plan` or discovery by mtime; otherwise resolution falls back to the project root (legacy). Used internally by hooks.
|
||||
- `scripts/check-complete.sh` — Verify all phases in the active plan are complete.
|
||||
- `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history.
|
||||
@@ -284,11 +286,11 @@ Not every install path ships every surface in this section. Two distinct install
|
||||
| `/plugin marketplace add OthmanAdi/planning-with-files` then `/plugin install` | SKILL.md, scripts, templates, **plus `commands/` folder** | Yes, as `/plan-goal` and `/plan-loop` |
|
||||
| `npx skills add OthmanAdi/planning-with-files` (or ClawHub) | SKILL.md, scripts, templates only | No, follow the manual fallback below |
|
||||
|
||||
The PreCompact hook is registered in the SKILL.md frontmatter and works for both routes. The `/plan-goal` and `/plan-loop` slash commands live in `commands/` at the repo root, which only the plugin route copies into `~/.claude/plugins/marketplaces/`. Skill-only installs land at `~/.claude/skills/planning-with-files/` and do not see `commands/`.
|
||||
Plugin installs register six lifecycle events from `hooks/hooks.json`, including quiet `SessionStart` recovery. Standalone skill installs register the five hooks in this SKILL.md frontmatter only after the skill is invoked for that session, so they have no startup recovery. The `/plan-goal` and `/plan-loop` slash commands live in `commands/` at the repository root and are available from the versioned plugin cache. Skill-only installs land at `~/.claude/skills/planning-with-files/` and do not include `commands/`.
|
||||
|
||||
The standalone `scripts/skill-hook.sh` reads the host's JSON session identity. UserPromptSubmit emits plain context; PreToolUse and PostToolUse emit the event's `additionalContext` JSON. The progress reminder fires at most once per turn when a usable session identity and private cache are available, and repeats when those are unavailable. All five events follow the same plan selection and opt-out checks.
|
||||
|
||||
Both slash commands also carry `disable-model-invocation: true`, which means the model will not auto-trigger them. You type them. Per known Claude Code behavior (anthropics/claude-code issues #26251, #41417), some sessions interpret `disable-model-invocation: true` as "I cannot use the Skill tool for this entry at all" and refuse to fire even when you type the slash. If that happens, the manual fallback below produces the same effect.
|
||||
Both slash commands carry `disable-model-invocation: true`, so invoke them explicitly. If a command is unavailable on a skill-only install, the manual fallback below produces the same planning-file result.
|
||||
|
||||
### PreCompact hook (auto)
|
||||
|
||||
|
||||
@@ -1,10 +1,9 @@
|
||||
{
|
||||
"name": "planning-with-files",
|
||||
"version": "3.20.3",
|
||||
"description": "Persistent project planning with selected context injection. Automatic recovery uses project files only; explicit catchup modes read same-project local session records for aggregate counts or bounded replay. The host-aware gate never runs Markdown-declared commands. No network upload path. Ships the skill plus a Pi Coding Agent extension.",
|
||||
"version": "3.20.7",
|
||||
"description": "Official Planning with Files skill for AI coding agents. Keeps persistent project planning files and injects selected plan context. Automatic recovery reads project files only; explicit local session catchup has no network upload path. Includes scripts, templates, and a Pi Coding Agent extension.",
|
||||
"keywords": [
|
||||
"pi-package",
|
||||
"pi-skill",
|
||||
"planning-with-files",
|
||||
"planning",
|
||||
"manus",
|
||||
"agent",
|
||||
@@ -14,7 +13,8 @@
|
||||
"coding-agent",
|
||||
"context-engineering",
|
||||
"session-recovery",
|
||||
"long-running-agents"
|
||||
"long-running-agents",
|
||||
"pi-coding-agent"
|
||||
],
|
||||
"pi": {
|
||||
"skills": [
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -144,7 +144,8 @@ function Test-WithinRoot {
|
||||
# (#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 carries and which are not links to sh.
|
||||
# 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]) {
|
||||
@@ -205,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
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
|
||||
@@ -312,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)"
|
||||
|
||||
@@ -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,6 +4,53 @@ All notable changes to this project will be documented in this file.
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [3.20.7] - 2026-09-23
|
||||
|
||||
### Fixed
|
||||
- The npm package description now discloses selected project planning context and the absence of a network upload path. This restores the public-capability metadata check that failed in v3.20.6 CI.
|
||||
- The contributor portrait grid uses the current profile for @Fat-Jan and stable identicons linked to archived credits for two unavailable accounts.
|
||||
- The full npm README points to the v3.20.7 repository files and includes the corrected contributor portraits.
|
||||
|
||||
## [3.20.6] - 2026-09-23
|
||||
|
||||
### Added
|
||||
- The README ends with a linked portrait grid of credited contributors, excluding the maintainer.
|
||||
|
||||
### Fixed
|
||||
- Phase-status locking now grants ownership through exclusive `.owner` creation instead of relying on `mkdir` exit status. This prevents a lost update when a Windows-native `mkdir` reports success to two writers (#281, PR #282).
|
||||
- Hermes rejects linked active-plan pointers and replaces the pointer through an exclusive temporary file, preserving hard-linked sibling content (#259, PR #284).
|
||||
- OpenCode and the DSH core reject linked active-plan pointers and replace the pointer without truncating a hard-linked sibling. A linked `.planning` directory is rejected while a project root reached through a junction remains usable (#260, PR #283).
|
||||
- PowerShell named-plan initialization rejects a read-only active pointer before creating the new plan directory (#253, PR #285).
|
||||
- PowerShell initialization recovers a project working directory containing `[` or `]` under Windows PowerShell 5.1 (#256, PR #286).
|
||||
- PowerShell active-pointer replacement retries transient concurrent I/O and pointer-inspection races while rechecking root and pointer safety. Cleanup of a `ReplaceFile` artifact after final failure remains open in #254 (PR #287).
|
||||
|
||||
### Changed
|
||||
- The `planning-with-files` npm package ships the canonical skill and displays the full official repository README. Repository-relative images and document links resolve to the v3.20.6 release while the Pi integration remains bundled.
|
||||
|
||||
### Thanks
|
||||
- @kuei51307-hub, for the exclusive phase-status lock claim and regression in #282.
|
||||
- @TayfurYldz, for the OpenCode, DSH, Hermes and PowerShell pointer fixes in #283, #284, #285, #286 and #287.
|
||||
|
||||
## [3.20.5] - 2026-09-21
|
||||
|
||||
### Fixed
|
||||
- OpenCode session replay tolerates null or array part rows, non-string tool names, and non-string text instead of aborting the session. Healthy rows remain available, and the defensive checks are synchronized across the copies that carry this formatter (#269, PR #273).
|
||||
- Shell and PowerShell initialization now report failed attestation as `NOT attested`, with a reason and recovery command, instead of claiming success. Attestation failure remains non-aborting, and inherited plan selectors are restored after the attempt (#276, PR #277).
|
||||
- The analytics task-plan template includes a non-empty `## Next Step` section across its shipped copies. Structural and initializer regressions keep generated analytics plans compatible with lifecycles that require that section (#278, PR #279).
|
||||
- PowerShell planning-file writes fail with a non-zero exit status and an error when access is denied. Named plans become active only after all three planning files are ready, so a failed initialization preserves the previous active pointer. The separately maintained host and translated initializers also stop on write errors (#255, PR #280).
|
||||
|
||||
### Thanks
|
||||
- @TayfurYldz, for the malformed OpenCode replay guards and regression coverage in #273.
|
||||
- @kuei51307-hub, for attestation failure reporting in #277 and the analytics Next Step fix in #279.
|
||||
- @ShaunLinTW, for denied-write handling, safe activation ordering, and Windows regression coverage in #280.
|
||||
- @mfehlhaber, for reporting the missing analytics Next Step section in #278.
|
||||
|
||||
## [3.20.4] - 2026-09-19
|
||||
|
||||
### Fixed
|
||||
- PowerShell route on OneDrive: `resolve-plan-dir.ps1`, the Cursor hook `resolve-plan-context.ps1` and `set-active-plan.ps1` refused an `.active_plan` pointer that carried the `ReparsePoint` file attribute. OneDrive Files On-Demand sets that attribute on every synced file, so in a project under OneDrive the Cursor hooks stopped with the unsafe-pointer notice instead of injecting the pointed plan, 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 predicate v3.20.3 gave the directory checks and the `[ -L ]` of the shell scripts. `attest-plan.ps1` had the same class of check in its native helper and refused to hash, show or clear any reparse-point file, so attestation failed in every project under OneDrive while `init-session.ps1` still reported the plan as attested; it now refuses only name-surrogate reparse points (symlinks, junctions and unknown surrogate tags), which is the set Windows path parsing follows (#275).
|
||||
- `tests/test_session_catchup_copies_exact_basename.py` walked the whole checkout and loaded any untracked `session-catchup.py`, so a stale clone kept under the gitignored `.planning/` on a maintainer machine failed the two tests with 120 subtests while CI stayed green. The copies now come from `git ls-files`; the filtered walk is kept only for a checkout without git (#274).
|
||||
|
||||
## [3.20.3] - 2026-09-19
|
||||
|
||||
### Fixed
|
||||
|
||||
+2
-2
@@ -7,8 +7,8 @@ authors:
|
||||
- family-names: Adi
|
||||
given-names: Ahmad Othman Ammar
|
||||
alias: OthmanAdi
|
||||
version: "3.20.3"
|
||||
date-released: "2026-09-19"
|
||||
version: "3.20.7"
|
||||
date-released: "2026-09-23"
|
||||
license: MIT
|
||||
url: "https://github.com/OthmanAdi/planning-with-files"
|
||||
repository-code: "https://github.com/OthmanAdi/planning-with-files"
|
||||
|
||||
+12
-7
@@ -109,23 +109,28 @@ These amazing people have contributed code, documentation, or significant improv
|
||||
- **[@ericshunhinglee-cloud](https://github.com/ericshunhinglee-cloud)**, [Issue #272](https://github.com/OthmanAdi/planning-with-files/issues/272)
|
||||
- Reported and traced the Hermes 0.21.3 first-turn `TERMINAL_CWD` rewrite that made the Hermes plugin resolve the home directory as the project root, with a setter stack trace, on-the-wire token evidence and the upstream cross-references.
|
||||
|
||||
- **[Shaun Lin](https://github.com/ShaunLinTW)**, [PR #245](https://github.com/OthmanAdi/planning-with-files/pull/245), [PR #247](https://github.com/OthmanAdi/planning-with-files/pull/247), [PR #263](https://github.com/OthmanAdi/planning-with-files/pull/263), [PR #271](https://github.com/OthmanAdi/planning-with-files/pull/271)
|
||||
- **[Shaun Lin](https://github.com/ShaunLinTW)**, [PR #245](https://github.com/OthmanAdi/planning-with-files/pull/245), [PR #247](https://github.com/OthmanAdi/planning-with-files/pull/247), [PR #263](https://github.com/OthmanAdi/planning-with-files/pull/263), [PR #271](https://github.com/OthmanAdi/planning-with-files/pull/271), [PR #280](https://github.com/OthmanAdi/planning-with-files/pull/280)
|
||||
- Isolated Python calls in the Codex, Gemini, and GitHub Copilot shell adapters and added regression coverage for project-local import shadowing.
|
||||
- Added named-plan slug mode to the PowerShell initializer with root-mode policy inheritance, host-aware attestation, and Windows PowerShell regression coverage.
|
||||
- Made the OpenCode session catchup adapter skip malformed part rows instead of raising, with regression coverage for the string-state and invalid-JSON shapes.
|
||||
- Made the shell several-plans counters skip symlinked and junctioned plan directories so they match the Hermes plugin, with a differential regression including the ambiguity probe.
|
||||
- Made denied PowerShell planning-file writes fail explicitly and deferred named-plan activation until all three files are ready, with real Windows ACL regression coverage.
|
||||
|
||||
- **[@TayfurYldz](https://github.com/TayfurYldz)**, [PR #265](https://github.com/OthmanAdi/planning-with-files/pull/265), [PR #266](https://github.com/OthmanAdi/planning-with-files/pull/266)
|
||||
- **[@TayfurYldz](https://github.com/TayfurYldz)**, [PR #265](https://github.com/OthmanAdi/planning-with-files/pull/265), [PR #266](https://github.com/OthmanAdi/planning-with-files/pull/266), [PR #273](https://github.com/OthmanAdi/planning-with-files/pull/273), [PR #283](https://github.com/OthmanAdi/planning-with-files/pull/283), [PR #284](https://github.com/OthmanAdi/planning-with-files/pull/284), [PR #285](https://github.com/OthmanAdi/planning-with-files/pull/285), [PR #286](https://github.com/OthmanAdi/planning-with-files/pull/286), [PR #287](https://github.com/OthmanAdi/planning-with-files/pull/287)
|
||||
- Bound `PWF_PLAN_ROOT` to the current project around the attestation call in both initializers so an inherited pin cannot redirect attestation, with shell and PowerShell regressions.
|
||||
- Made the shell slugifier single-line so a plan name with an embedded newline no longer creates an unusable plan directory.
|
||||
- Guarded OpenCode replay against null and array rows, non-string tool names, and object-valued text while retaining healthy session rows.
|
||||
- Replaced OpenCode, DSH and Hermes active pointers without following hard links, rejected read-only PowerShell pointers before plan creation, recovered bracketed Windows PowerShell working directories, and bounded concurrent pointer replacement retries. The `ReplaceFile` artifact case remains open in #254.
|
||||
|
||||
- **[@kuei51307-hub](https://github.com/kuei51307-hub)**, [PR #243](https://github.com/OthmanAdi/planning-with-files/pull/243), [PR #244](https://github.com/OthmanAdi/planning-with-files/pull/244), [PR #248](https://github.com/OthmanAdi/planning-with-files/pull/248), [PR #249](https://github.com/OthmanAdi/planning-with-files/pull/249), [PR #251](https://github.com/OthmanAdi/planning-with-files/pull/251), [PR #267](https://github.com/OthmanAdi/planning-with-files/pull/267)
|
||||
- **[@kuei51307-hub](https://github.com/kuei51307-hub)**, [PR #243](https://github.com/OthmanAdi/planning-with-files/pull/243), [PR #244](https://github.com/OthmanAdi/planning-with-files/pull/244), [PR #248](https://github.com/OthmanAdi/planning-with-files/pull/248), [PR #249](https://github.com/OthmanAdi/planning-with-files/pull/249), [PR #251](https://github.com/OthmanAdi/planning-with-files/pull/251), [PR #267](https://github.com/OthmanAdi/planning-with-files/pull/267), [PR #277](https://github.com/OthmanAdi/planning-with-files/pull/277), [PR #279](https://github.com/OthmanAdi/planning-with-files/pull/279), [PR #282](https://github.com/OthmanAdi/planning-with-files/pull/282)
|
||||
- Fixed active-plan display and listing for UTF-8 BOM-prefixed pointers, with regression coverage across the synchronized shell helpers.
|
||||
- Made IDE sync verification report missing canonical sources, with subprocess tests for read-only verification and unchanged sync behavior.
|
||||
- Bounded session catchup to exact planning filenames across the canonical scanners and the Hermes, MastraCode, and OpenCode adapters, with lookalike regression coverage.
|
||||
- Replaced the shell initializer's active-pointer write with the selector's contained atomic update and added hardlink, symlink, and junction regressions.
|
||||
- Routed Cursor's native PowerShell hooks through the shared plan resolver so named plans are injected on Windows, and made the resolver's `PWF_PLAN_ROOT` check run on Windows PowerShell 5.1.
|
||||
- Ported the several-plans rule into the Hermes plugin so two or more named plans without `PLAN_ID` get the selector notice instead of a pointer or timestamp guess.
|
||||
- Made shell and PowerShell initialization report attestation failures with a recovery command, and added the missing analytics Next Step section across template copies with regression coverage.
|
||||
- Made phase-status lock ownership exclusive even when a Windows-native `mkdir` reports simultaneous success to two writers.
|
||||
|
||||
- **[@Dphoshoba](https://github.com/Dphoshoba)**, [PR #242](https://github.com/OthmanAdi/planning-with-files/pull/242)
|
||||
- Proposed and implemented named-plan listing with phase counts and a shared active-pointer marker.
|
||||
@@ -210,7 +215,7 @@ These amazing people have contributed code, documentation, or significant improv
|
||||
- Added `.codex/hooks/pre-compact.sh` (POSIX sh, reuses `resolve-plan-dir.sh`, emits the same flush reminder and `Plan-SHA256` line as the canonical hook), wired it into `.codex/hooks.json`, corrected the `docs/codex.md` hook table, and added two targeted tests
|
||||
- **Impact:** Codex users on the native `hooks.json` route now get the pre-compaction progress-flush reminder. The hook stays dormant on runtimes that never fire a PreCompact event, with `|| true` wiring that cannot break a session
|
||||
|
||||
- **[@Fat-Jan](https://github.com/Fat-Jan)** (Alonso) - [PR #184](https://github.com/OthmanAdi/planning-with-files/pull/184)
|
||||
- **[@Fat-Jan](https://github.com/Alonso-li)** (Alonso, now @Alonso-li) - [PR #184](https://github.com/OthmanAdi/planning-with-files/pull/184)
|
||||
- Updated the `docs/codex.md` verification block to grep `^(hooks|codex_hooks)\s` instead of the bare `^codex_hooks\s`, and aligned the follow-up troubleshooting sentence with the `hooks = true` guidance stated earlier in the same document
|
||||
- The bare pattern stopped matching once Codex moved its canonical feature key from `codex_hooks` to `hooks` in 0.129.0 (openai/codex#20522); the alias still resolves in `config.toml`, but `codex features list` prints only the canonical `hooks`, so the verify step was telling correctly configured users to upgrade
|
||||
- **Impact:** the documented verification command matches on current Codex versions again, and `docs/codex.md` is internally consistent across the six places that reference the feature flag
|
||||
@@ -417,7 +422,7 @@ Thank you to everyone who reported issues, provided feedback, and helped test fi
|
||||
- [@popey](https://github.com/popey) (Alan Pope) - [PR #215](https://github.com/OthmanAdi/planning-with-files/pull/215) (bumped the pinned Tessl action SHA past a migration that had silently stopped reviews from running; the range it moves across also closes a marker-spoofing hole in the commit this repo had been pinned to)
|
||||
- [@SomSamantray](https://github.com/SomSamantray) (Som Samantray) - [PR #216](https://github.com/OthmanAdi/planning-with-files/pull/216) (audited the language variants against the canonical skill and proved the drift issue #130 predicted: 12 missing scripts, a missing Windows UTF-8 fix, and sync tooling that covered only 3 dispatch targets; that analysis is what v3.10.0 acted on, closing the gap additively instead of by deletion)
|
||||
- [@marcmuon](https://github.com/marcmuon) (Marc Kelechava) - Issue #195 (one-shot `codex exec` sessions sharing a cwd with an incomplete plan got hijacked and mutated orchestrator-owned plan files; the report's reproductions, root-cause file list, and acceptance criteria shipped directly as the `PLANNING_DISABLED=1` opt-out in v3.4.0)
|
||||
- [@mfehlhaber](https://github.com/mfehlhaber): Issue #220 (identified that the Codex POSIX `SessionStart` and `UserPromptSubmit` routes bypassed the JSON adapter, causing planning context beginning with `[` to be rejected as invalid event JSON; fixed in v3.10.1), Issue #231 (traced Pi's generic attestation failure to six CRLF shell scripts in the npm `3.10.2` tarball, separated the clean repository source from the broken package artifact, and identified the missing package-time validation boundary)
|
||||
- [@mfehlhaber](https://github.com/mfehlhaber): Issue #220 (identified that the Codex POSIX `SessionStart` and `UserPromptSubmit` routes bypassed the JSON adapter, causing planning context beginning with `[` to be rejected as invalid event JSON; fixed in v3.10.1), Issue #231 (traced Pi's generic attestation failure to six CRLF shell scripts in the npm `3.10.2` tarball, separated the clean repository source from the broken package artifact, and identified the missing package-time validation boundary); [Issue #278](https://github.com/OthmanAdi/planning-with-files/issues/278) (reported the missing Next Step section in generated analytics plans, fixed in v3.20.5)
|
||||
|
||||
- [@Whxuan0701](https://github.com/Whxuan0701) (WeiHaoxuan) - [PR #223](https://github.com/OthmanAdi/planning-with-files/pull/223), [PR #222](https://github.com/OthmanAdi/planning-with-files/pull/222), [PR #224](https://github.com/OthmanAdi/planning-with-files/pull/224) (found that the `PLANNING_DISABLED=1` opt-out from #195 had never reached any of the ten GitHub Copilot hook entry points, that the #191 zero-phase guard was missing from the Copilot PowerShell stop hook, and that the Hermes determinism probe hardcoded `python` so it could not run where only `python3` exists; three single-commit PRs, each with a test that executes the real script. Auditing them surfaced three further defects fixed in the same release: the Cursor route had the same opt-out gap across all eight of its hooks, the disabled `PreToolUse` branch was widening Copilot's permissions rather than staying neutral, and `error-occurred.ps1` had never logged an error on Windows because it read stdin into PowerShell's automatic `$input` variable)
|
||||
|
||||
@@ -450,6 +455,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
|
||||
|
||||
---
|
||||
|
||||
**Total Contributors:** 65+ and growing!
|
||||
**Total Contributors:** 77 (76 community contributors plus the maintainer)
|
||||
|
||||
*Last updated: 2026-09-19*
|
||||
*Last updated: 2026-09-23*
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
<div align="center">
|
||||
<img src="media/v3-banner-1400.jpg" alt="planning-with-files: task_plan.md, findings.md, and progress.md as three stone tablets" width="100%">
|
||||
<img src="media/pwf-banner-v5.webp" alt="PWF: Every task. Every step. Three planning files on a brass-inlaid base beneath an engraved arch" width="100%">
|
||||
</div>
|
||||
|
||||
<h1 align="center">
|
||||
@@ -22,8 +22,11 @@ Persistent file-based planning for AI coding agents and long-running agent tasks
|
||||
<p align="center">
|
||||
<a href="https://github.com/OthmanAdi/planning-with-files/stargazers"><img src="https://img.shields.io/github/stars/OthmanAdi/planning-with-files?style=flat&color=yellow" alt="Stars"></a>
|
||||
<a href="https://github.com/OthmanAdi/planning-with-files/releases"><img src="https://img.shields.io/github/v/release/OthmanAdi/planning-with-files?style=flat&label=release" alt="Latest release"></a>
|
||||
<a href="https://skills.sh/othmanadi/planning-with-files"><img src="https://skills.sh/b/othmanadi/planning-with-files" alt="skills.sh installs"></a>
|
||||
<a href="https://skillsplayground.com/skills/othmanadi-planning-with-files-planning-with-files/"><img src="https://skillsplayground.com/badges/installs/othmanadi-planning-with-files-planning-with-files.svg" alt="Skills Playground installs"></a>
|
||||
<a href="https://skill-history.com/othmanadi/planning-with-files"><img src="https://skill-history.com/badge/othmanadi/planning-with-files.svg" alt="Downloads"></a>
|
||||
<a href="https://github.com/OthmanAdi/planning-with-files/issues?q=is%3Aissue+is%3Aclosed"><img src="https://img.shields.io/github/issues-closed/OthmanAdi/planning-with-files?color=success" alt="Closed issues"></a>
|
||||
<a href="https://github.com/OthmanAdi/planning-with-files/pulls?q=is%3Apr+is%3Aclosed"><img src="https://img.shields.io/github/issues-pr-closed/OthmanAdi/planning-with-files?color=success" alt="Closed PRs"></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
@@ -45,33 +48,24 @@ Persistent file-based planning for AI coding agents and long-running agent tasks
|
||||
<sub>Proof, comparisons and the repository reference are <a href="#reference">further down</a> · <a href="docs/installation.md">Full install guide</a></sub>
|
||||
</p>
|
||||
|
||||
|
||||
## Quick Install
|
||||
|
||||
```bash
|
||||
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
|
||||
```
|
||||
|
||||
All install methods: [docs/installation.md](docs/installation.md).
|
||||
|
||||
---
|
||||
|
||||
## Before and after /clear
|
||||
|
||||
Every coding agent loses its working memory when the context window resets. The plan does not have to die with it.
|
||||
|
||||
### Without planning files
|
||||
|
||||
<img src="media/terminal-without-plan.svg" alt="Terminal after /clear without planning files: the user types continue, the agent replies that it has no context from an earlier session and asks the user to describe the task and where they left off" width="560">
|
||||
|
||||
The agent re-reads the repo, asks you to restate the goal, and rediscovers work it already finished.
|
||||
|
||||
---
|
||||
|
||||
### With planning-with-files
|
||||
|
||||
<img src="media/terminal-with-plan.svg" alt="Terminal after /clear with planning-with-files: the hook injects a plan data block showing Phase 2 complete and Phase 3 in progress, and the agent resumes Phase 3 by adding the expiry edge-case tests" width="560">
|
||||
|
||||
The transcript is illustrative; the `===BEGIN PLAN DATA===` block is the skill's real injection format, written into context by the `UserPromptSubmit` hook from `task_plan.md` on disk. In the project's internal recovery benchmark, a fresh session with the files on disk resumed in 5.0 turns on average against 13.3 for a raw agent (internal v1, author-run; method and limits in [docs/evals.md](docs/evals.md)). That benchmark used the earlier default transcript-catchup behavior. Current automatic recovery uses project files only, so the figure is historical evidence rather than a fresh measurement of the current default.
|
||||
|
||||
| At a glance | |
|
||||
|---|---:|
|
||||
| Plan files | **3** |
|
||||
| Agents covered | **60+** |
|
||||
| Pass rate (with skill) | **96.7%** |
|
||||
| Test suite | **1084 tests** |
|
||||
| Survives `/clear` | **yes** |
|
||||
<p align="center">
|
||||
<a href="media/pwf-context-story-v1.mp4"><img src="media/pwf-context-story-v1.gif" alt="Illustrated workflow: planning files preserve the task state through a context reset" width="760"></a>
|
||||
</p>
|
||||
|
||||
## Built for long-running agent tasks
|
||||
|
||||
@@ -80,23 +74,8 @@ The transcript is illustrative; the `===BEGIN PLAN DATA===` block is the skill's
|
||||
>
|
||||
> That is the difference between an agent that forgets after `/clear`, compaction or a crash and one that resumes at the current phase. In the project's own measurements the plan on disk turned a 13.3-turn re-orientation into 5.0 turns, and the skill won 3 of 3 blind A/B comparisons ([numbers and limits](#benchmark-results)). Every mechanism below is a file on disk plus a hook, so it works the same on hour ten as on turn one.
|
||||
|
||||
| What breaks long agent runs | What the skill does about it |
|
||||
|---|---|
|
||||
| The context window is wiped by `/clear`, compaction, or a crash | The plan is re-read from disk on the next turn; `SessionStart`, `UserPromptSubmit` and `PreCompact` hooks carry the current phase back in |
|
||||
| Goal drift after 50+ tool calls | The plan head is re-injected every turn; `PWF_INJECT=smart` keeps the goal, the next step and the active phase in the window late in a long plan |
|
||||
| The agent declares "done" early | Gated mode: the Stop gate holds the stop only while an `in_progress` phase remains, with a block cap and stall detection so an incomplete plan alone never traps a session |
|
||||
| The plan is silently rewritten by a tool result, a collaborator, or a bug | SHA-256 attestation: a plan body that no longer matches the approved hash is refused at injection with `[PLAN TAMPERED]` |
|
||||
| Two sessions overwrite each other's phases | The parallel-write guard reports when checked items or completed phases go down between turns |
|
||||
| Autonomous loops burn tokens on recitation | Autonomous mode drops the per-tool-call recitation and replaces the raw progress tail with a fixed-shape ledger summary; injection is KV-cache stable and one hook fire costs about 289 ms |
|
||||
| Hooks that quietly stop firing | `/plan-doctor` self-checks resolution, injection, attestation, install surfaces and per-fire latency |
|
||||
|
||||
Everything in that table is opt-in per plan and byte-identical to the previous behavior when no mode marker is set. Details: [v3 Long-Running Agent Features](#v3-long-running-agent-features) and [docs/long-running-agent-tasks.md](docs/long-running-agent-tasks.md).
|
||||
|
||||
<a id="the-problem"></a>
|
||||
<a id="the-solution-3-file-pattern"></a>
|
||||
<a id="the-core-principle"></a>
|
||||
<a id="why-this-skill"></a>
|
||||
<a id="the-manus-principles"></a>
|
||||
<div><a id="the-problem"></a><a id="the-solution-3-file-pattern"></a><a id="the-core-principle"></a><a id="why-this-skill"></a><a id="the-manus-principles"></a></div>
|
||||
|
||||
## The 3-file pattern
|
||||
|
||||
@@ -107,7 +86,7 @@ Filesystem = Disk (persistent, unlimited)
|
||||
→ Anything important gets written to disk.
|
||||
```
|
||||
|
||||
For every complex task the skill keeps exactly this in your project, and nothing else:
|
||||
The skill keeps your plan, findings, and progress in your project:
|
||||
|
||||
```
|
||||
your-project/
|
||||
@@ -123,85 +102,14 @@ The pattern is the one Manus described before [Meta acquired it for $2 billion o
|
||||
> "Markdown is my 'working memory' on disk. Since I process information iteratively and my active context has limits, Markdown files serve as scratch pads for notes, checkpoints for progress, building blocks for final deliverables."
|
||||
> — Manus AI
|
||||
|
||||
| Principle | Implementation |
|
||||
|-----------|----------------|
|
||||
| Filesystem as memory | Store in files, not context |
|
||||
| Plan recitation | Re-read plan before decisions (hooks) |
|
||||
| Error persistence | Log failures in plan file |
|
||||
| Goal tracking | Checkboxes show progress |
|
||||
| Completion verification | Stop hook checks all phases |
|
||||
|
||||
## Quick Install
|
||||
<a id="hermes-agent-first-class-support-cli-and-desktop"></a>
|
||||
|
||||
**Claude Code, plugin route** (ships everything: skill, hooks, slash commands):
|
||||
## First-class hosts: native plugins
|
||||
|
||||
```
|
||||
/plugin marketplace add OthmanAdi/planning-with-files
|
||||
/plugin install planning-with-files@planning-with-files
|
||||
```
|
||||
> [!TIP]
|
||||
> **On these hosts planning-with-files runs as a native plugin: per-turn plan injection, progress reminders, the completion gate, `/pwf` commands and model-callable tools, with no shell hooks to register.** Every other platform gets the skill through the Agent Skills standard and, where the host supports it, the frontmatter or config-file hooks listed in the [platform setup guides](#enhanced-support-per-ide-setup-guides).
|
||||
|
||||
**Every other agent**, one line, 60+ agents via the [Agent Skills](https://agentskills.io) standard:
|
||||
|
||||
```bash
|
||||
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
|
||||
```
|
||||
|
||||
**npm**, to pin an exact version into a project or vendor it:
|
||||
|
||||
```bash
|
||||
npm install planning-with-files
|
||||
```
|
||||
|
||||
The package carries `SKILL.md`, `scripts/` and `templates/`, so this is the route for locking a version into a repo's dependencies or copying the skill in yourself. It does not register hooks on its own.
|
||||
|
||||
**Pi Coding Agent**, same npm package, wired up for you (skill, extension, status bar):
|
||||
|
||||
```bash
|
||||
pi install npm:planning-with-files
|
||||
```
|
||||
|
||||
**Hermes Agent** (Nous Research), native plugin plus skill bundle, CLI and Desktop:
|
||||
|
||||
```bash
|
||||
hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes
|
||||
hermes plugins install OthmanAdi/planning-with-files/.hermes/plugins/planning-with-files
|
||||
hermes plugins enable planning-with-files
|
||||
```
|
||||
|
||||
**OpenCode**, native plugin plus the skill (the `npx skills add` command above lands in `~/.agents/skills/`, which OpenCode reads):
|
||||
|
||||
```json
|
||||
{ "plugin": ["opencode-planning-with-files"] }
|
||||
```
|
||||
|
||||
in `opencode.json` or `~/.config/opencode/opencode.json`; OpenCode installs it on the next start.
|
||||
|
||||
**DeepSeek Harness (DSH)**, native plugin plus the skill (the `npx skills add` command above lands in `~/.agents/skills/`, which DSH reads):
|
||||
|
||||
```bash
|
||||
dsh plugin --profile web add dsh-planning-with-files
|
||||
```
|
||||
|
||||
then restart `dsh web`; the same command works for the `headless`, `sdk` and `acp` profiles.
|
||||
|
||||
Under a minute. Safe to re-run. Trigger it by typing `/plan` (plugin) or asking the agent to "plan this task"; the skill also self-triggers on multi-step tasks.
|
||||
|
||||
What each route actually ships:
|
||||
|
||||
| Route | Skill + scripts + templates | Slash commands | Hooks |
|
||||
|---|---|---|---|
|
||||
| Claude Code plugin | yes | **yes** | **yes** |
|
||||
| `npx skills add` | yes | no | frontmatter hooks, see note |
|
||||
| `npm install` | yes, under `node_modules/` | no | no, copy the skill in yourself |
|
||||
| `pi install npm:` | yes | **yes**, Pi commands | **yes**, via the Pi extension |
|
||||
| `hermes plugins install` | yes, with the skill bundle | **yes**, `/pwf`, `/pwf-status` | **yes**, plugin hooks incl. the gate |
|
||||
| OpenCode `opencode.json` plugin | yes, with the skill | **yes**, `/pwf`, `/pwf-status` (two copied command files) | **yes**, plugin hooks incl. the gate |
|
||||
| DeepSeek Harness `dsh plugin add` | yes, with the skill | **yes**, `/pwf`, `/pwf-status` | **yes**, plugin hooks incl. the gate |
|
||||
| ClawHub / manual copy | yes | no | frontmatter hooks, see note |
|
||||
|
||||
Skill-route installs can end up silently hook-less (project trust not accepted, or frontmatter hooks not registering on project-level installs). The hooks are the differentiating mechanism, so if they matter to you, use the plugin route, then verify with `/plan-doctor`. Full matrix and the two silent killers: [docs/installation.md](docs/installation.md#what-each-install-route-actually-ships).
|
||||
|
||||
Install acting up? Open your agent and say: *"Read docs/installation.md and docs/troubleshooting.md from OthmanAdi/planning-with-files and fix my install."* Then run `/plan-doctor`.
|
||||
|
||||
<details>
|
||||
<summary><strong>🌐 Available in 5 other languages</strong></summary>
|
||||
@@ -239,24 +147,7 @@ They live under `skills/i18n/`, one directory deeper than the canonical skill. T
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Prefer <code>/planning-with-files</code> with no prefix?</strong></summary>
|
||||
|
||||
Copy the skill to your local folder:
|
||||
|
||||
**macOS/Linux:**
|
||||
```bash
|
||||
cp -r ~/.claude/plugins/cache/planning-with-files/planning-with-files/*/skills/planning-with-files ~/.claude/skills/
|
||||
```
|
||||
|
||||
**Windows (PowerShell):**
|
||||
```powershell
|
||||
Copy-Item -Recurse -Path "$env:USERPROFILE\.claude\plugins\cache\planning-with-files\planning-with-files\*\skills\planning-with-files" -Destination "$env:USERPROFILE\.claude\skills\"
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<details id="enhanced-support-per-ide-setup-guides">
|
||||
<summary><strong>Enhanced Support: per-IDE setup guides</strong></summary>
|
||||
|
||||
| IDE | Installation Guide | Integration |
|
||||
@@ -347,6 +238,10 @@ One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from
|
||||
|
||||
| Version | Highlights |
|
||||
|---------|------------|
|
||||
| **v3.20.7** | Fixes npm capability disclosure metadata and three unavailable contributor portrait endpoints. The npm package continues to ship the canonical skill and full repository README. |
|
||||
| **v3.20.6** | Phase-status writers claim one lock owner even with Windows-native `mkdir` (#282). OpenCode, DSH and Hermes safely replace linked active pointers (#283, #284). PowerShell named plans reject read-only pointers before creation (#285), work under bracketed paths (#286), and retry transient concurrent pointer writes and inspection races (#287). The remaining `ReplaceFile` artifact case stays open in #254. |
|
||||
| **v3.20.5** | OpenCode replay tolerates malformed parts (#273). Initialization reports attestation failures accurately (#277), analytics plans include Next Step (#279), and PowerShell denied writes fail without activating an incomplete named plan (#280). |
|
||||
| **v3.20.4** | PowerShell route on OneDrive: an `.active_plan` pointer carrying the OneDrive Files On-Demand reparse attribute no longer counts as unsafe, so the Cursor hooks, the resolver and `set-active-plan.ps1` work in projects under OneDrive (#275). The session-catchup copy guard checks tracked copies only (#274). |
|
||||
| **v3.20.3** | A symlinked or junctioned directory under `.planning/` is never a plan on any route: the shell counters skip it (PR #271 by @ShaunLinTW, #270), and the selection paths of the shell family plus the Codex, OpenCode and DSH counters refuse it too, so one real plan next to a linked one no longer becomes an mtime guess. |
|
||||
| **v3.20.2** | Hermes plugin: Hermes 0.21.3 re-homes `TERMINAL_CWD` to the home directory on the first CLI turn, so the plan in the launch directory was skipped silently. The first turn now says why nothing was injected and names the `PWF_PLAN_ROOT` pin, `/pwf-status` and `/pwf` print the same diagnostic, and the slash commands honor the pin (#272, reported by @ericshunhinglee-cloud). |
|
||||
| **v3.20.1** | Fixes four maintainer-filed issues from the v3.19.0 and v3.20.0 cycles: newline-safe shell slugs (#257, PR #266 by @TayfurYldz), attestation bound to the current project when `PWF_PLAN_ROOT` is inherited (#261, PR #265 by @TayfurYldz), malformed OpenCode part rows skipped by session catchup (#258, PR #263 by @ShaunLinTW), and the several-plans rule in the Hermes plugin (#264, PR #267 by @kuei51307-hub). |
|
||||
@@ -473,7 +368,101 @@ Full list of everyone who made this project better: [CONTRIBUTORS.md](./CONTRIBU
|
||||
|
||||
</details>
|
||||
|
||||
All install methods: [docs/installation.md](docs/installation.md).
|
||||
|
||||
<details id="full-reference">
|
||||
<summary><strong>📚 Commands, Multi-agent runs, Benchmarks & more</strong> <code>[15 sections]</code></summary>
|
||||
|
||||
### Long-run safeguards
|
||||
|
||||
| What breaks long agent runs | What the skill does about it |
|
||||
|---|---|
|
||||
| The context window is wiped by `/clear`, compaction, or a crash | The plan is re-read from disk on the next turn; `SessionStart`, `UserPromptSubmit` and `PreCompact` hooks carry the current phase back in |
|
||||
| Goal drift after 50+ tool calls | The plan head is re-injected every turn; `PWF_INJECT=smart` keeps the goal, the next step and the active phase in the window late in a long plan |
|
||||
| The agent declares "done" early | Gated mode: the Stop gate holds the stop only while an `in_progress` phase remains, with a block cap and stall detection so an incomplete plan alone never traps a session |
|
||||
| The plan is silently rewritten by a tool result, a collaborator, or a bug | SHA-256 attestation: a plan body that no longer matches the approved hash is refused at injection with `[PLAN TAMPERED]` |
|
||||
| Two sessions overwrite each other's phases | The parallel-write guard reports when checked items or completed phases go down between turns |
|
||||
| Autonomous loops burn tokens on recitation | Autonomous mode drops the per-tool-call recitation and replaces the raw progress tail with a fixed-shape ledger summary; injection is KV-cache stable and one hook fire costs about 289 ms |
|
||||
| Hooks that quietly stop firing | `/plan-doctor` self-checks resolution, injection, attestation, install surfaces and per-fire latency |
|
||||
|
||||
Everything in that table is opt-in per plan and byte-identical to the previous behavior when no mode marker is set. Details: [v3 Long-Running Agent Features](#v3-long-running-agent-features) and [docs/long-running-agent-tasks.md](docs/long-running-agent-tasks.md).
|
||||
|
||||
### Installation routes
|
||||
|
||||
|
||||
**Claude Code, plugin route** (ships everything: skill, hooks, slash commands):
|
||||
|
||||
```
|
||||
/plugin marketplace add OthmanAdi/planning-with-files
|
||||
/plugin install planning-with-files@planning-with-files
|
||||
```
|
||||
|
||||
**Every other agent**, one line, 60+ agents via the [Agent Skills](https://agentskills.io) standard:
|
||||
|
||||
```bash
|
||||
npx skills add OthmanAdi/planning-with-files --skill planning-with-files -g
|
||||
```
|
||||
|
||||
**npm**, to pin an exact version into a project or vendor it:
|
||||
|
||||
```bash
|
||||
npm install planning-with-files
|
||||
```
|
||||
|
||||
The package carries `SKILL.md`, `scripts/` and `templates/`, so this is the route for locking a version into a repo's dependencies or copying the skill in yourself. It does not register hooks on its own.
|
||||
|
||||
**Pi Coding Agent**, same npm package, wired up for you (skill, extension, status bar):
|
||||
|
||||
```bash
|
||||
pi install npm:planning-with-files
|
||||
```
|
||||
|
||||
**Hermes Agent** (Nous Research), native plugin plus skill bundle, CLI and Desktop:
|
||||
|
||||
```bash
|
||||
hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes
|
||||
hermes plugins install OthmanAdi/planning-with-files/.hermes/plugins/planning-with-files
|
||||
hermes plugins enable planning-with-files
|
||||
```
|
||||
|
||||
**OpenCode**, native plugin plus the skill (the `npx skills add` command above lands in `~/.agents/skills/`, which OpenCode reads):
|
||||
|
||||
```json
|
||||
{ "plugin": ["opencode-planning-with-files"] }
|
||||
```
|
||||
|
||||
in `opencode.json` or `~/.config/opencode/opencode.json`; OpenCode installs it on the next start.
|
||||
|
||||
**DeepSeek Harness (DSH)**, native plugin plus the skill (the `npx skills add` command above lands in `~/.agents/skills/`, which DSH reads):
|
||||
|
||||
```bash
|
||||
dsh plugin --profile web add dsh-planning-with-files
|
||||
```
|
||||
|
||||
then restart `dsh web`; the same command works for the `headless`, `sdk` and `acp` profiles.
|
||||
|
||||
Under a minute. Safe to re-run. Trigger it by typing `/plan` (plugin) or asking the agent to "plan this task"; the skill also self-triggers on multi-step tasks.
|
||||
|
||||
What each route actually ships:
|
||||
|
||||
| Route | Skill + scripts + templates | Slash commands | Hooks |
|
||||
|---|---|---|---|
|
||||
| Claude Code plugin | yes | **yes** | **yes** |
|
||||
| `npx skills add` | yes | no | frontmatter hooks, see note |
|
||||
| `npm install` | yes, under `node_modules/` | no | no, copy the skill in yourself |
|
||||
| `pi install npm:` | yes | **yes**, Pi commands | **yes**, via the Pi extension |
|
||||
| `hermes plugins install` | yes, with the skill bundle | **yes**, `/pwf`, `/pwf-status` | **yes**, plugin hooks incl. the gate |
|
||||
| OpenCode `opencode.json` plugin | yes, with the skill | **yes**, `/pwf`, `/pwf-status` (two copied command files) | **yes**, plugin hooks incl. the gate |
|
||||
| DeepSeek Harness `dsh plugin add` | yes, with the skill | **yes**, `/pwf`, `/pwf-status` | **yes**, plugin hooks incl. the gate |
|
||||
| ClawHub / manual copy | yes | no | frontmatter hooks, see note |
|
||||
|
||||
Skill-route installs can end up silently hook-less (project trust not accepted, or frontmatter hooks not registering on project-level installs). The hooks are the differentiating mechanism, so if they matter to you, use the plugin route, then verify with `/plan-doctor`. Full matrix and the two silent killers: [docs/installation.md](docs/installation.md#what-each-install-route-actually-ships).
|
||||
|
||||
Install acting up? Open your agent and say: *"Read docs/installation.md and docs/troubleshooting.md from OthmanAdi/planning-with-files and fix my install."* Then run `/plan-doctor`.
|
||||
|
||||
|
||||
Hermes needs its skill bundle from `.hermes/skills/planning-with-files` (`hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes`); OpenCode and DeepSeek Harness read the skill that `npx skills add ... -g` places in `~/.agents/skills/`. Each host's own `/plan` command is never shadowed.
|
||||
|
||||
|
||||
|
||||
<a id="works-across-18-platforms"></a>
|
||||
|
||||
@@ -487,28 +476,12 @@ One skill, three integration tiers. Know what your agent gets before you install
|
||||
| **Standard Agent Skills** | Continue, Pi, OpenClaw, Autohand Code, Antigravity, Kilocode, AdaL CLI | SKILL.md discovery via `npx skills add`; the pattern without lifecycle hooks |
|
||||
| **Agent Skills standard path** (in-tree since v3.7.0) | Zed, Amp, Warp, Devin, Antigravity, Gemini CLI, Cursor | `.agents/skills/planning-with-files/` discovered from a plain `git clone`, no per-tool setup |
|
||||
|
||||
Per-platform setup guides, discovery paths and sandbox runtimes are in the collapsible sections under [Quick Install](#quick-install).
|
||||
Per-platform setup guides, discovery paths and sandbox runtimes are in the collapsible sections below [First-class hosts: native plugins](#first-class-hosts-native-plugins).
|
||||
|
||||
<a id="hermes-agent-first-class-support-cli-and-desktop"></a>
|
||||
|
||||
## First-class hosts: native plugins
|
||||
|
||||
> [!TIP]
|
||||
> **On these hosts planning-with-files runs as a native plugin: per-turn plan injection, progress reminders, the completion gate, `/pwf` commands and model-callable tools, with no shell hooks to register.** Every other platform gets the skill through the Agent Skills standard and, where the host supports it, the frontmatter or config-file hooks listed in the tables above.
|
||||
|
||||
| Host | Install | What runs natively | Guide |
|
||||
|---|---|---|---|
|
||||
| Claude Code | `/plugin install planning-with-files@planning-with-files` | 6 lifecycle hooks, 13 slash commands, `/plan-doctor` | [docs/installation.md](docs/installation.md) |
|
||||
| Pi Coding Agent | `pi install npm:planning-with-files` | 8 Pi events via the bundled extension, `/plan-execute` approval gate, status bar | [docs/pi-agent.md](docs/pi-agent.md) |
|
||||
| Hermes Agent (CLI and Desktop) | `hermes plugins install OthmanAdi/planning-with-files/.hermes/plugins/planning-with-files` then `hermes plugins enable planning-with-files` | `pre_llm_call` injection, `post_tool_call` reminders, `pre_verify` gate, `/pwf`, tools | [docs/hermes.md](docs/hermes.md) |
|
||||
| OpenCode | `"plugin": ["opencode-planning-with-files"]` in `opencode.json` | `chat.message` injection, write reminders, compaction flush, `session.idle` gate, `/pwf`, `pwf_*` tools | [docs/opencode.md](docs/opencode.md) |
|
||||
| DeepSeek Harness | `dsh plugin --profile web add dsh-planning-with-files` | `agent/pre-step` injection, write reminders, post-compaction restore, `agent/turn-stopping` gate, `/pwf`, `pwf_*` tools | [docs/deepseek-harness.md](docs/deepseek-harness.md) |
|
||||
|
||||
Hermes needs its skill bundle from `.hermes/skills/planning-with-files` (`hermes skills install OthmanAdi/planning-with-files/.hermes/skills/planning-with-files --yes`); OpenCode and DeepSeek Harness read the skill that `npx skills add ... -g` places in `~/.agents/skills/`. Each host's own `/plan` command is never shadowed.
|
||||
|
||||
## Multi-agent runs: orchestrators, workers and subagents
|
||||
|
||||
> [!NOTE]
|
||||
> **NOTE**
|
||||
> **Markdown on disk is the shared state between agents.** One orchestrator owns `task_plan.md` and the shared summaries; every worker appends to its own ledger or assigned file. Pin each independent task with `PLAN_ID` before starting its host, or use separate worktrees.
|
||||
|
||||
- **Run ledger per agent.** Workers append one JSON line per event to `.planning/<id>/ledger-<agent>.jsonl` (`ledger-append.sh`); `ledger-summary.sh` synthesizes a fixed-shape, KV-cache-stable block from all ledgers that replaces the raw `progress.md` tail in autonomous and gated mode. No free text from disk reaches the model through that block.
|
||||
@@ -528,7 +501,7 @@ To find a saved plan, run the installed `scripts/set-active-plan.sh --list` help
|
||||
The agent stops at the first rung that applies:
|
||||
|
||||
```
|
||||
1. Task needs 3+ steps or 5+ tool calls? → create the three files first
|
||||
1. Starting work with planning-with-files? → create the three files first
|
||||
2. Learned something? → append it to findings.md
|
||||
3. Did something? → log it in progress.md
|
||||
4. Phase done? → check it off in task_plan.md
|
||||
@@ -580,8 +553,8 @@ Slash commands ship with the Claude Code plugin route (see the install matrix ab
|
||||
|
||||
Typing `/plan` prefix-matches every `plan*` command in autocomplete; `/planning-with-files:status` autocompletes as `/status` (the older `/plan:status` label predates the rename).
|
||||
|
||||
<details>
|
||||
<summary><strong>Pi, OpenCode, Hermes and DeepSeek Harness commands, and command names per host</strong></summary>
|
||||
|
||||
### <strong>Pi, OpenCode, Hermes and DeepSeek Harness commands, and command names per host</strong>
|
||||
|
||||
### Pi extension commands
|
||||
|
||||
@@ -639,7 +612,7 @@ The DSH plugin registers these in-session commands, typed with no prefix. `/plan
|
||||
|
||||
On the plugin route the model-invocable SKILL is `planning-with-files:planning-with-files`; the doubled form is the skill id, not a command you type. The five language variants live under `skills/i18n/`, which the plugin scan does not reach, so there is no `planning-with-files:planning-with-files-de` to invoke by name — reach a translation through its `/plan-ar`, `/plan-de`, `/plan-es`, `/plan-zh` or `/plan-zht` command, or install it as its own skill with `npx skills add OthmanAdi/planning-with-files --skill planning-with-files-de -g`, which registers it under its own name. There is no `/pwf-de` and no `/planning-with-files:planning-with-files-goal`; `/pwf` is just a short alias for `/plan`.
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
## v3 Long-Running Agent Features
|
||||
|
||||
@@ -697,14 +670,6 @@ Pi runtime modes:
|
||||
3. **Log ALL Errors** — They help avoid repetition
|
||||
4. **Never Repeat Failures** — Track attempts, mutate approach
|
||||
|
||||
## When to Use
|
||||
|
||||
**Use this pattern for:**
|
||||
- Multi-step tasks (3+ steps)
|
||||
- Research tasks
|
||||
- Building/creating projects
|
||||
- Tasks spanning many tool calls
|
||||
- Long-running agent sessions that must survive `/clear` and compaction
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
@@ -722,7 +687,7 @@ Pi runtime modes:
|
||||
|
||||
## Reference
|
||||
|
||||
Everything below is the proof and the reference half: the benchmarks and their limits, what lands in your project and what the repository ships, and every guide in `docs/`. Release history and community projects sit in the collapsible sections under [Quick Install](#quick-install).
|
||||
Everything below is the proof and the reference half: the benchmarks and their limits, what lands in your project and what the repository ships, and every guide in `docs/`. Release history and community projects sit in the collapsible sections below [First-class hosts: native plugins](#first-class-hosts-native-plugins).
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
@@ -765,8 +730,8 @@ Protocol: the session is hard-stopped at roughly half done, and a fresh session
|
||||
|
||||
What the skill writes into your project is three markdown files (see [the 3-file pattern](#the-solution-3-file-pattern)). What the repository ships:
|
||||
|
||||
<details>
|
||||
<summary><strong>Repository layout</strong></summary>
|
||||
|
||||
### <strong>Repository layout</strong>
|
||||
|
||||
```
|
||||
planning-with-files/
|
||||
@@ -788,9 +753,9 @@ planning-with-files/
|
||||
└── README.md
|
||||
```
|
||||
|
||||
Every release maintains 19 tracked parity targets plus the gitignored ClawHub upload stage when it is present. `scripts/bump-version.py` updates every available target, and CI fails if a tracked variant lags.
|
||||
Every release maintains 20 tracked parity targets plus the gitignored ClawHub upload stage when it is present. `scripts/bump-version.py` updates every available target, and CI fails if a tracked variant lags. The npm package's `SKILL.md` is byte-identical to the canonical skill.
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
## Documentation
|
||||
@@ -825,6 +790,97 @@ MIT License — feel free to use, modify, and distribute.
|
||||
|
||||
**Author:** [Ahmad Othman Ammar Adi](https://github.com/OthmanAdi)
|
||||
|
||||
</details>
|
||||
|
||||
## Star History
|
||||
|
||||
<a href="https://repostars.dev/?repos=OthmanAdi%2Fplanning-with-files&theme=copper"><img src="https://repostars.dev/api/embed?repo=OthmanAdi%2Fplanning-with-files&theme=copper" width="100%" alt="Star History Chart" /></a>
|
||||
<a href="https://repostars.dev/?repos=OthmanAdi%2Fplanning-with-files&theme=aurora"><img src="https://wsrv.nl/?url=https%3A%2F%2Frepostars.dev%2Fapi%2Fog%3Frepos%3DOthmanAdi%252Fplanning-with-files%26theme%3Daurora&cy=228&ch=334&maxage=1d" width="100%" alt="Star History Chart" /></a>
|
||||
|
||||
## ClawHub Downloads
|
||||
|
||||
<a href="https://skill-history.com/othmanadi/planning-with-files"><img src="https://skill-history.com/chart/othmanadi/planning-with-files.svg" width="100%" alt="ClawHub Download History Chart" /></a>
|
||||
|
||||
## Contributors
|
||||
|
||||
Code, documentation, and issue contributors. Select a portrait to open a GitHub profile or archived credit. [Full credits](CONTRIBUTORS.md).
|
||||
|
||||
<!-- contributor-portraits:start -->
|
||||
<p align="center">
|
||||
<a href="https://github.com/kaichen" title="@kaichen"><img src="https://github.com/kaichen.png?size=56" width="48" height="48" alt="@kaichen"></a>
|
||||
<a href="https://github.com/fuahyo" title="@fuahyo"><img src="https://github.com/fuahyo.png?size=56" width="48" height="48" alt="@fuahyo"></a>
|
||||
<a href="https://github.com/lasmarois" title="@lasmarois"><img src="https://github.com/lasmarois.png?size=56" width="48" height="48" alt="@lasmarois"></a>
|
||||
<a href="https://github.com/aimasteracc" title="@aimasteracc"><img src="https://github.com/aimasteracc.png?size=56" width="48" height="48" alt="@aimasteracc"></a>
|
||||
<a href="https://github.com/SaladDay" title="@SaladDay"><img src="https://github.com/SaladDay.png?size=56" width="48" height="48" alt="@SaladDay"></a>
|
||||
<a href="https://github.com/murphyXu" title="@murphyXu"><img src="https://github.com/murphyXu.png?size=56" width="48" height="48" alt="@murphyXu"></a>
|
||||
<a href="https://github.com/ZWkang" title="@ZWkang"><img src="https://github.com/ZWkang.png?size=56" width="48" height="48" alt="@ZWkang"></a>
|
||||
<a href="https://github.com/EListenX" title="@EListenX"><img src="https://github.com/EListenX.png?size=56" width="48" height="48" alt="@EListenX"></a>
|
||||
<a href="https://github.com/lincolnwan" title="@lincolnwan"><img src="https://github.com/lincolnwan.png?size=56" width="48" height="48" alt="@lincolnwan"></a>
|
||||
<a href="https://github.com/ciberponk" title="@ciberponk"><img src="https://github.com/ciberponk.png?size=56" width="48" height="48" alt="@ciberponk"></a>
|
||||
<a href="https://github.com/ttttmr" title="@ttttmr"><img src="https://github.com/ttttmr.png?size=56" width="48" height="48" alt="@ttttmr"></a>
|
||||
<a href="https://github.com/mvanhorn" title="@mvanhorn"><img src="https://github.com/mvanhorn.png?size=56" width="48" height="48" alt="@mvanhorn"></a>
|
||||
<a href="https://github.com/ebrevdo" title="@ebrevdo"><img src="https://github.com/ebrevdo.png?size=56" width="48" height="48" alt="@ebrevdo"></a>
|
||||
<a href="https://github.com/bailob" title="@bailob"><img src="https://github.com/bailob.png?size=56" width="48" height="48" alt="@bailob"></a>
|
||||
<a href="https://github.com/ericshunhinglee-cloud" title="@ericshunhinglee-cloud"><img src="https://github.com/ericshunhinglee-cloud.png?size=56" width="48" height="48" alt="@ericshunhinglee-cloud"></a>
|
||||
<a href="https://github.com/ShaunLinTW" title="@ShaunLinTW"><img src="https://github.com/ShaunLinTW.png?size=56" width="48" height="48" alt="@ShaunLinTW"></a>
|
||||
<a href="https://github.com/TayfurYldz" title="@TayfurYldz"><img src="https://github.com/TayfurYldz.png?size=56" width="48" height="48" alt="@TayfurYldz"></a>
|
||||
<a href="https://github.com/kuei51307-hub" title="@kuei51307-hub"><img src="https://github.com/kuei51307-hub.png?size=56" width="48" height="48" alt="@kuei51307-hub"></a>
|
||||
<a href="https://github.com/Dphoshoba" title="@Dphoshoba"><img src="https://github.com/Dphoshoba.png?size=56" width="48" height="48" alt="@Dphoshoba"></a>
|
||||
<a href="https://github.com/sunznx" title="@sunznx"><img src="https://github.com/sunznx.png?size=56" width="48" height="48" alt="@sunznx"></a>
|
||||
<a href="https://github.com/hzura" title="@hzura"><img src="https://github.com/hzura.png?size=56" width="48" height="48" alt="@hzura"></a>
|
||||
<a href="https://github.com/wangxiaodong1021" title="@wangxiaodong1021"><img src="https://github.com/wangxiaodong1021.png?size=56" width="48" height="48" alt="@wangxiaodong1021"></a>
|
||||
<a href="https://github.com/sortakool" title="@sortakool"><img src="https://github.com/sortakool.png?size=56" width="48" height="48" alt="@sortakool"></a>
|
||||
<a href="https://github.com/lowmiaq-gmail" title="@lowmiaq-gmail"><img src="https://github.com/lowmiaq-gmail.png?size=56" width="48" height="48" alt="@lowmiaq-gmail"></a>
|
||||
<a href="https://github.com/webwww123" title="@webwww123"><img src="https://github.com/webwww123.png?size=56" width="48" height="48" alt="@webwww123"></a>
|
||||
<a href="https://github.com/killianMei" title="@killianMei"><img src="https://github.com/killianMei.png?size=56" width="48" height="48" alt="@killianMei"></a>
|
||||
<a href="https://github.com/GlitterKill" title="@GlitterKill"><img src="https://github.com/GlitterKill.png?size=56" width="48" height="48" alt="@GlitterKill"></a>
|
||||
<a href="https://github.com/seathatflowsinourveins" title="@seathatflowsinourveins"><img src="https://github.com/seathatflowsinourveins.png?size=56" width="48" height="48" alt="@seathatflowsinourveins"></a>
|
||||
<a href="https://github.com/fd44fdg" title="@fd44fdg"><img src="https://github.com/fd44fdg.png?size=56" width="48" height="48" alt="@fd44fdg"></a>
|
||||
<a href="https://github.com/jschmied" title="@jschmied"><img src="https://github.com/jschmied.png?size=56" width="48" height="48" alt="@jschmied"></a>
|
||||
<a href="https://github.com/yolo0731" title="@yolo0731"><img src="https://github.com/yolo0731.png?size=56" width="48" height="48" alt="@yolo0731"></a>
|
||||
<a href="https://github.com/ziyu4huang" title="@ziyu4huang"><img src="https://github.com/ziyu4huang.png?size=56" width="48" height="48" alt="@ziyu4huang"></a>
|
||||
<a href="https://github.com/kcinzgg" title="@kcinzgg"><img src="https://github.com/kcinzgg.png?size=56" width="48" height="48" alt="@kcinzgg"></a>
|
||||
<a href="https://github.com/mahdiit" title="@mahdiit"><img src="https://github.com/mahdiit.png?size=56" width="48" height="48" alt="@mahdiit"></a>
|
||||
<a href="https://github.com/Dikshj" title="@Dikshj"><img src="https://github.com/Dikshj.png?size=56" width="48" height="48" alt="@Dikshj"></a>
|
||||
<a href="https://github.com/2023Anita" title="@2023Anita"><img src="https://github.com/2023Anita.png?size=56" width="48" height="48" alt="@2023Anita"></a>
|
||||
<a href="https://github.com/GongYuanCaiJi" title="@GongYuanCaiJi"><img src="https://github.com/GongYuanCaiJi.png?size=56" width="48" height="48" alt="@GongYuanCaiJi"></a>
|
||||
<a href="https://github.com/Alonso-li" title="@Fat-Jan, now @Alonso-li"><img src="https://github.com/Alonso-li.png?size=56" width="48" height="48" alt="@Fat-Jan"></a>
|
||||
<a href="https://github.com/shunfeng8421" title="@shunfeng8421"><img src="https://github.com/shunfeng8421.png?size=56" width="48" height="48" alt="@shunfeng8421"></a>
|
||||
<a href="https://github.com/Skulli485" title="@Skulli485"><img src="https://github.com/Skulli485.png?size=56" width="48" height="48" alt="@Skulli485"></a>
|
||||
<a href="https://github.com/carterusedulm2-maker" title="@carterusedulm2-maker"><img src="https://github.com/carterusedulm2-maker.png?size=56" width="48" height="48" alt="@carterusedulm2-maker"></a>
|
||||
<a href="https://github.com/gauravvojha" title="@gauravvojha"><img src="https://github.com/gauravvojha.png?size=56" width="48" height="48" alt="@gauravvojha"></a>
|
||||
<a href="CONTRIBUTORS.md" title="@CleanDev-Fix, archived credit"><img src="https://github.com/identicons/CleanDev-Fix.png" width="48" height="48" alt="@CleanDev-Fix"></a>
|
||||
<a href="https://github.com/bmyury" title="@bmyury"><img src="https://github.com/bmyury.png?size=56" width="48" height="48" alt="@bmyury"></a>
|
||||
<a href="https://github.com/oaabahussain" title="@oaabahussain"><img src="https://github.com/oaabahussain.png?size=56" width="48" height="48" alt="@oaabahussain"></a>
|
||||
<a href="https://github.com/gavinlinasd" title="@gavinlinasd"><img src="https://github.com/gavinlinasd.png?size=56" width="48" height="48" alt="@gavinlinasd"></a>
|
||||
<a href="https://github.com/xiaolai" title="@xiaolai"><img src="https://github.com/xiaolai.png?size=56" width="48" height="48" alt="@xiaolai"></a>
|
||||
<a href="https://github.com/githubYiheng" title="@githubYiheng"><img src="https://github.com/githubYiheng.png?size=56" width="48" height="48" alt="@githubYiheng"></a>
|
||||
<a href="https://github.com/09ashishkapoor" title="@09ashishkapoor"><img src="https://github.com/09ashishkapoor.png?size=56" width="48" height="48" alt="@09ashishkapoor"></a>
|
||||
<a href="https://github.com/shawnli1874" title="@shawnli1874"><img src="https://github.com/shawnli1874.png?size=56" width="48" height="48" alt="@shawnli1874"></a>
|
||||
<a href="https://github.com/Leon-Algo" title="@Leon-Algo"><img src="https://github.com/Leon-Algo.png?size=56" width="48" height="48" alt="@Leon-Algo"></a>
|
||||
<a href="https://github.com/YSAA1" title="@YSAA1"><img src="https://github.com/YSAA1.png?size=56" width="48" height="48" alt="@YSAA1"></a>
|
||||
<a href="https://github.com/kevinaimonster" title="@kevinaimonster"><img src="https://github.com/kevinaimonster.png?size=56" width="48" height="48" alt="@kevinaimonster"></a>
|
||||
<a href="https://github.com/wd041216-bit" title="@wd041216-bit"><img src="https://github.com/wd041216-bit.png?size=56" width="48" height="48" alt="@wd041216-bit"></a>
|
||||
<a href="https://github.com/popey" title="@popey"><img src="https://github.com/popey.png?size=56" width="48" height="48" alt="@popey"></a>
|
||||
<a href="https://github.com/jonthebeef" title="@jonthebeef"><img src="https://github.com/jonthebeef.png?size=56" width="48" height="48" alt="@jonthebeef"></a>
|
||||
<a href="https://github.com/codelyc" title="@codelyc"><img src="https://github.com/codelyc.png?size=56" width="48" height="48" alt="@codelyc"></a>
|
||||
<a href="https://github.com/Guozihong" title="@Guozihong"><img src="https://github.com/Guozihong.png?size=56" width="48" height="48" alt="@Guozihong"></a>
|
||||
<a href="https://github.com/fahmyelraie" title="@fahmyelraie"><img src="https://github.com/fahmyelraie.png?size=56" width="48" height="48" alt="@fahmyelraie"></a>
|
||||
<a href="https://github.com/olgasafonova" title="@olgasafonova"><img src="https://github.com/olgasafonova.png?size=56" width="48" height="48" alt="@olgasafonova"></a>
|
||||
<a href="https://github.com/AZLabsAI" title="@AZLabsAI"><img src="https://github.com/AZLabsAI.png?size=56" width="48" height="48" alt="@AZLabsAI"></a>
|
||||
<a href="https://github.com/raykuo998" title="@raykuo998"><img src="https://github.com/raykuo998.png?size=56" width="48" height="48" alt="@raykuo998"></a>
|
||||
<a href="https://github.com/gydx6" title="@gydx6"><img src="https://github.com/gydx6.png?size=56" width="48" height="48" alt="@gydx6"></a>
|
||||
<a href="https://github.com/waynelee2048" title="@waynelee2048"><img src="https://github.com/waynelee2048.png?size=56" width="48" height="48" alt="@waynelee2048"></a>
|
||||
<a href="https://github.com/tobrun" title="@tobrun"><img src="https://github.com/tobrun.png?size=56" width="48" height="48" alt="@tobrun"></a>
|
||||
<a href="https://github.com/markocupic024" title="@markocupic024"><img src="https://github.com/markocupic024.png?size=56" width="48" height="48" alt="@markocupic024"></a>
|
||||
<a href="https://github.com/tt-a1i" title="@tt-a1i"><img src="https://github.com/tt-a1i.png?size=56" width="48" height="48" alt="@tt-a1i"></a>
|
||||
<a href="https://github.com/Emin017" title="@Emin017"><img src="https://github.com/Emin017.png?size=56" width="48" height="48" alt="@Emin017"></a>
|
||||
<a href="https://github.com/TomXPRIME" title="@TomXPRIME"><img src="https://github.com/TomXPRIME.png?size=56" width="48" height="48" alt="@TomXPRIME"></a>
|
||||
<a href="https://github.com/DLI1996" title="@DLI1996"><img src="https://github.com/DLI1996.png?size=56" width="48" height="48" alt="@DLI1996"></a>
|
||||
<a href="https://github.com/Stephen-abc" title="@Stephen-abc"><img src="https://github.com/Stephen-abc.png?size=56" width="48" height="48" alt="@Stephen-abc"></a>
|
||||
<a href="https://github.com/igorcosta" title="@igorcosta"><img src="https://github.com/igorcosta.png?size=56" width="48" height="48" alt="@igorcosta"></a>
|
||||
<a href="https://github.com/Yigtwxx" title="@Yigtwxx"><img src="https://github.com/Yigtwxx.png?size=56" width="48" height="48" alt="@Yigtwxx"></a>
|
||||
<a href="https://github.com/RioTheGreat-ai" title="@RioTheGreat-ai"><img src="https://github.com/RioTheGreat-ai.png?size=56" width="48" height="48" alt="@RioTheGreat-ai"></a>
|
||||
<a href="https://github.com/kmichels" title="@kmichels"><img src="https://github.com/kmichels.png?size=56" width="48" height="48" alt="@kmichels"></a>
|
||||
<a href="CONTRIBUTORS.md" title="@voidborne-d, archived credit"><img src="https://github.com/identicons/voidborne-d.png" width="48" height="48" alt="@voidborne-d"></a>
|
||||
</p>
|
||||
<!-- contributor-portraits:end -->
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 270 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 8.5 MiB |
Binary file not shown.
@@ -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.");
|
||||
|
||||
@@ -11,11 +11,12 @@ Run before tagging a release:
|
||||
python scripts/bump-version.py 2.37.0
|
||||
python scripts/bump-version.py 2.37.0 --dry-run
|
||||
|
||||
Maintained targets (20 entries: 19 tracked files plus optional local staging):
|
||||
Maintained targets (21 entries: 20 tracked files plus optional local staging):
|
||||
skills/planning-with-files/SKILL.md (canonical)
|
||||
skills/i18n/planning-with-files-{ar,de,es,zh,zht}/SKILL.md
|
||||
.{codebuddy,codex,cursor,factory,hermes,mastracode,opencode}/skills/planning-with-files/SKILL.md
|
||||
.agents/skills/planning-with-files/SKILL.md (Agent Skills standard layout)
|
||||
.pi/skills/planning-with-files/SKILL.md (canonical npm skill)
|
||||
clawhub-upload/SKILL.md (gitignored; bumped when present)
|
||||
.claude-plugin/plugin.json
|
||||
.claude-plugin/marketplace.json
|
||||
@@ -25,7 +26,6 @@ Maintained targets (20 entries: 19 tracked files plus optional local staging):
|
||||
|
||||
Files intentionally left behind (see LAGGING_FILES; do not bump automatically):
|
||||
.continue and .gemini (intentionally behind),
|
||||
.pi SKILL.md (no version field; the Pi version lives in its package.json above),
|
||||
.kiro (-kiro-suffixed scheme)
|
||||
"""
|
||||
from __future__ import annotations
|
||||
@@ -56,12 +56,13 @@ PARITY_FILES = [
|
||||
(".mastracode/skills/planning-with-files/SKILL.md", "skill_md"),
|
||||
(".opencode/skills/planning-with-files/SKILL.md", "skill_md"),
|
||||
(".agents/skills/planning-with-files/SKILL.md", "skill_md"),
|
||||
(".pi/skills/planning-with-files/SKILL.md", "skill_md"),
|
||||
("clawhub-upload/SKILL.md", "skill_md"),
|
||||
(".claude-plugin/plugin.json", "plugin_json"),
|
||||
(".claude-plugin/marketplace.json", "marketplace_json"),
|
||||
(".codex-plugin/plugin.json", "plugin_json"),
|
||||
("CITATION.cff", "citation_cff"),
|
||||
# npm package for the Pi channel (issue #213: it sat at a third-party 1.1.0
|
||||
# npm package for the official skill and Pi extension (issue #213: it sat at a third-party 1.1.0
|
||||
# for 15 releases because nothing bumped it). Same single-"version" JSON
|
||||
# shape as plugin.json, so the handler is shared. Remember: bumping only
|
||||
# changes the file; `npm publish` from .pi/skills/planning-with-files/ is a
|
||||
@@ -72,7 +73,7 @@ PARITY_FILES = [
|
||||
# Publish staging that remains parity-locked whenever it exists, but is
|
||||
# intentionally absent from clean clones because the directory is gitignored.
|
||||
# Keep these paths in PARITY_FILES so maintainer worktrees still bump and
|
||||
# validate them as part of the canonical 20-entry release set.
|
||||
# validate them as part of the canonical 21-entry release set.
|
||||
OPTIONAL_PARITY_FILES = {
|
||||
"clawhub-upload/SKILL.md": "optional gitignored ClawHub publish staging",
|
||||
}
|
||||
@@ -81,7 +82,6 @@ OPTIONAL_PARITY_FILES = {
|
||||
LAGGING_FILES = [
|
||||
".continue/skills/planning-with-files/SKILL.md",
|
||||
".gemini/skills/planning-with-files/SKILL.md",
|
||||
".pi/skills/planning-with-files/SKILL.md", # no version field; npm version lives in its package.json (parity set)
|
||||
".kiro/skills/planning-with-files/SKILL.md", # kiro scheme (2.32.0-kiro)
|
||||
]
|
||||
|
||||
|
||||
+142
-29
@@ -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)"
|
||||
}
|
||||
}
|
||||
|
||||
+52
-7
@@ -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
|
||||
|
||||
+38
-12
@@ -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
|
||||
|
||||
+29
-11
@@ -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
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user