Compare commits

...
26 Commits
Author SHA1 Message Date
OthmanAdi 7a0a020f16 release: v3.19.0
PowerShell named-plan slug mode (#247), exact planning filename
boundary for session catchup across every shipped copy (#248), and
selector-routed active-pointer replacement with planning-root
containment in both initializers (#249), plus the maintainer follow-ups
from the release review.

CHANGELOG entry, contributor credits for @ShaunLinTW and
@kuei51307-hub, README releases row, CITATION date, and the
script-driven parity bump of the 19 tracked version files.
2026-09-17 10:11:23 +02:00
OthmanAdi bb48bb0a1e fix: verify the planning root in constant time before named-plan init
PR #249 probed the planning root with set-active-plan.sh --list, which
canonicalizes and parses every existing plan directory: on Git Bash a
slug init with 30 plans took 19 s. It also checked the pointer only
after the plan directory and files existed, so a refused pointer left a
new directory behind and a retry produced a -2 suffix.

Add --verify-root to set-active-plan.sh and -VerifyRoot to
set-active-plan.ps1: the planning root, when present, must be inside
the project and an existing pointer must be a replaceable regular
file. Nothing is read, listed or written. Both initializers call it
before creating anything; the same 30-plan init now takes under 3 s.

Also: the shared pointer keeps a umask-derived mode instead of the
0600 that mktemp creates, an unreadable pointer no longer aborts the
listing under set -e, and SCRIPT_DIR ignores CDPATH when it locates
the sibling scripts. All 18 selector copies and 10 initializer copies
are synced.
2026-09-17 10:11:23 +02:00
OthmanAdi ea8b17860d fix: iterate OpenCode planning parts lazily in session catchup
The exact-path lookup from #248 replaced LIMIT 1 with fetchall and a
Python revalidation loop. OpenCode write parts carry whole file bodies,
so a session with many planning writes materialized all of them before
the first validated row ended the loop (measured 20 MB peak for 2,000
10 KB writes). Iterate the cursor instead; the loop still stops at the
first exact match. Applied to every copy that carries the query.

The OpenCode lookalike test now seeds a later part so it fails on the
suffix-matching baseline instead of passing through the empty-parts
early return.
2026-09-17 10:11:23 +02:00
OthmanAdi 808694b726 fix: keep PowerShell plan ids ASCII and plan paths literal
Review follow-ups for the named-plan flow in init-session.ps1:

- Build the slug with -creplace. The case-insensitive -replace lets
  letters that .NET folds to ASCII, such as a dotted capital I, survive
  into the plan id, which the resolvers and the selector then reject.
  A slug that is still not ASCII falls back to untitled-<id>.
- Write the plan files with Out-File -LiteralPath. Once the target path
  is absolute, -FilePath treats [ and ] as wildcards and pwsh fails the
  write while the script still reports success.
- Inherit the root .mode marker case-sensitively, matching
  init-session.sh and the injector.
- Treat an empty positional name as legacy root mode and report
  "untitled" for -PlanDir without a name, both like the shell twin.

The tests drop a developer's PWF_PLAN_ROOT pin from the child
environment and cover each item, with the bracketed-path case run
under pwsh only because Windows PowerShell 5.1 relocates its own cwd
for such paths.
2026-09-17 10:11:23 +02:00
OthmanAdi c82f647718 fix: replace PowerShell active pointers through the selector
PR #247 gave init-session.ps1 the same named-plan flow as the shell
initializer, but it wrote .planning\.active_plan with Set-Content. That
write follows a reparse point and truncates a hardlinked pointer in
place, so it could overwrite whichever file shared the inode, and it
created the plan even when .planning was a junction to a directory
outside the project.

Route the pointer write through set-active-plan.ps1, which already owns
the contained atomic replacement, and run its listing check on the
physical planning root before creating anything beneath it. This is the
PowerShell twin of PR #249. A missing selector now stops named-plan
creation, matching the shell initializer. Ten copies synced, four
regressions added: hardlinked pointer, symlinked pointer, junctioned
planning root, and the selector requirement.
2026-09-17 10:11:23 +02:00
OthmanAdi e9da40fc87 fix: require exact planning filenames in unsynced catchup copies
PR #248 replaced suffix matching with an exact-basename rule in the
session-catchup.py copies that sync-ide-folders.py maintains. Three more
copies live outside that tool and kept the old boundary: the root
scripts/session-catchup.py, which is the Claude Code plugin install path,
and the five translated skills/i18n copies. A later write to a lookalike
such as draft_task_plan.md could still move their catchup anchor forward.

Apply the same helper to all six, replace the LIKE suffix query in the
root and zh OpenCode paths with the exact-path query and Python
revalidation, and add a test that loads every shipped copy so the
boundary cannot drift again in one of them.
2026-09-17 10:11:23 +02:00
kuei51307-hub 893cb38299 fix(init): replace active pointers safely 2026-09-17 10:10:50 +02:00
kuei51307-hub 02eaf0b64d fix(catchup): require exact planning filenames 2026-09-17 10:10:38 +02:00
Shaun Lin aae2d1ebc5 fix: attest PowerShell plans across hosts 2026-09-17 10:10:27 +02:00
Shaun Lin f1ebb38d42 fix: add PowerShell slug-mode plan initialization 2026-09-17 10:10:27 +02:00
OthmanAdi 746f57a7c5 release: v3.18.3 2026-09-16 13:23:11 +02:00
OthmanAdi 0d41eeeddd fix: silence completed-plan Stop notices 2026-09-16 13:21:35 +02:00
OthmanAdi f12e714e3f release: v3.18.2 2026-09-16 11:10:01 +02:00
OthmanAdi 7f8b6da3b2 fix: preserve UTF-8 in isolated adapter hooks 2026-09-16 11:08:56 +02:00
Shaun Lin 7297d964eb fix: isolate Python in adapter shell hooks 2026-09-16 11:08:56 +02:00
kuei51307-hub 8379610e83 fix(sync): report missing canonical sources 2026-09-16 11:08:52 +02:00
OthmanAdi 7c11cb7570 release: v3.18.1 2026-09-15 10:41:57 +02:00
OthmanAdi e7d8be14f4 test: preserve BOM pointers across display and listing 2026-09-15 10:41:57 +02:00
kuei51307-hub 6834e65f0b fix(plans): accept BOM-prefixed active pointers 2026-09-15 10:41:37 +02:00
OthmanAdi 8699bc573c fix: allow Windows CI to finish the full test suite 2026-09-14 08:31:42 +02:00
OthmanAdi 10d4a585a9 release: v3.18.0 2026-09-13 13:27:57 +02:00
OthmanAdi ae7e3ae817 fix: make plan listing safe and useful across install surfaces 2026-09-13 13:27:56 +02:00
Dphoshoba 6317beb930 feat: list active planning sessions 2026-09-13 13:27:41 +02:00
Ahmad Othman Ammar Adi 1ec8f4eb5c Update README.md 2026-09-10 00:00:01 +02:00
Ahmad Othman Ammar Adi b19fa8e8d9 Update README.md 2026-09-09 18:59:43 +02:00
OthmanAdi 716318a827 docs: showcase top trending achievements in README 2026-09-09 18:21:19 +02:00
151 changed files with 16834 additions and 1477 deletions
+8 -2
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.2"
version: "3.19.0"
---
# Planning with Files
@@ -227,6 +227,12 @@ Helper scripts for automation:
- `scripts/attest-plan.sh` (and `.ps1`) — Lock the current `task_plan.md` content with a SHA-256 attestation (v2.37.0). Hooks then refuse to inject plan content if the file diverges from the attested hash. Use `--show` to print the stored hash, `--clear` to remove the attestation. See `/plan-attest` command.
- `scripts/plan-doctor.sh` — One-pass self-check for the mechanisms that fail silently (v3.6.0): plan resolution, hook injection, canonicalizer path shape, attestation state, install surfaces, per-fire hook latency. Run it whenever hooks seem quiet or after installing on a new machine. See `/plan-doctor` command.
### List saved plans
To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
### Parallel task workflow
For independent tasks in the same repository, create a named plan for each and pin each agent host to its own plan:
@@ -359,7 +365,7 @@ The mode is set by writing a `.mode` file next to the plan (`.planning/<id>/.mod
### The legacy invariant (promise)
With no `.mode` file and no other v3 marker, the hooks produce byte-identical output to v2.43, including the raw `progress.md` tail and the `===BEGIN PLAN DATA===` / `===END PLAN DATA===` delimiters. Every v3 behavior is additive and opt-in. No existing workflow changes.
With no `.mode` file and no other v3 marker, plan injection preserves the v2.43 output, including the raw `progress.md` tail and the `===BEGIN PLAN DATA===` / `===END PLAN DATA===` delimiters. Autonomous and gated behavior remains opt-in. Since v3.18.3, completed plans are silent through the shared Stop gate and Codex Stop hook. Explicit `check-complete.sh` or `check-complete.ps1` calls without the gate flag still report completion; incomplete-plan notices and gate decisions are unchanged.
### What each mode does
@@ -10,7 +10,8 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall -> allow stop)
# When all hold, emits a single-line block-decision JSON on stdout and exits 0.
# Otherwise advisory output and exit 0. Without -Gate, byte-equivalent to v2.43.
# Otherwise reports incomplete plans and exits 0; completed plans stay silent
# with -Gate, including legacy plans without .mode. Explicit reports are unchanged.
#
# Stdin: read only when input is redirected ([Console]::IsInputRedirected), so an
# interactive console never blocks. Hook-piped JSON is EOF-terminated.
@@ -85,9 +86,10 @@ if ($TOTAL -eq 0) {
exit 0
}
# advisory_report: the v2.43 status echo.
# Keep explicit reports, but omit routine success from automatic gate checks.
function Write-AdvisoryReport {
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
if ($Gate) { return }
Write-Host ('[planning-with-files] ALL PHASES COMPLETE (' + $COMPLETE + '/' + $TOTAL + '). If the user has additional work, add new phases to task_plan.md before starting.')
} else {
Write-Host ('[planning-with-files] Task in progress (' + $COMPLETE + '/' + $TOTAL + ' phases complete). Update progress.md before stopping.')
@@ -21,8 +21,9 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall → allow stop)
# When all hold, it emits a single-line block-decision JSON on stdout and
# exits 0. Otherwise it falls back to advisory output and exits 0.
# Without --gate, or in non-gated mode, behavior is byte-equivalent to v2.43.
# exits 0. Otherwise it reports incomplete plans and exits 0; completed
# plans stay silent in --gate mode, including legacy plans without .mode.
# Without --gate, the explicit advisory report is unchanged.
#
# Stdin handling: the Claude Code Stop hook pipes a JSON payload on stdin. To
# avoid hanging when nothing is piped, stdin is read ONLY when fd 0 is not a
@@ -119,9 +120,11 @@ if [ "$TOTAL" -eq 0 ]; then
exit 0
fi
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
# Explicit status reports retain completion text. Automatic gate checks have
# nothing to report on success; keep evaluating all gate guards before here.
advisory_report() {
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
[ "$GATE" -eq 1 ] && return 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete). Update progress.md before stopping."
@@ -1,5 +1,6 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
# .\init-session.ps1 -PlanDir # isolated plan with generated slug
# .\init-session.ps1 -Autonomous # v3 autonomous mode (opt-in)
# .\init-session.ps1 -Gated # v3 gated mode (opt-in, implies autonomous)
# Templates: default, analytics
@@ -12,6 +13,7 @@
param(
[string]$ProjectName = "project",
[string]$Template = "default",
[switch]$PlanDir,
[switch]$Autonomous,
[switch]$Gated
)
@@ -38,7 +40,45 @@ function Get-Nonce {
($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
function Get-PlanSlug([string]$Name) {
# -creplace: the case-insensitive -replace lets letters that .NET folds to
# ASCII (a dotted capital I, the Kelvin sign) survive into the plan id.
$slug = $Name.ToLowerInvariant() -creplace '[^a-z0-9]', '-'
$slug = $slug -creplace '-{2,}', '-'
$slug = $slug.Trim('-')
if ($slug.Length -gt 40) {
$slug = $slug.Substring(0, 40).TrimEnd('-')
}
# The resolvers and the selector only accept ASCII plan ids.
if ($slug -cnotmatch '^[a-z0-9-]*$') {
return ""
}
return $slug
}
function Get-ShortId {
return ([Guid]::NewGuid().ToString('N')).Substring(0, 8)
}
function Get-InheritedMode([string]$CurrentMode) {
$RootModePath = Join-Path (Get-Location).Path ".mode"
if (-not (Test-Path -LiteralPath $RootModePath)) {
return $CurrentMode
}
if ($CurrentMode -eq "gated") {
return $CurrentMode
}
$RootMode = Get-Content -LiteralPath $RootModePath -Raw -ErrorAction SilentlyContinue
# Case-sensitive like inherit_root_mode in init-session.sh and the injector.
if ($RootMode -cmatch 'gate') {
return "gated"
}
if ($RootMode -cmatch 'autonomous') {
return "autonomous"
}
return $CurrentMode
}
# Validate template
if ($Template -ne "default" -and $Template -ne "analytics") {
@@ -46,11 +86,98 @@ if ($Template -ne "default" -and $Template -ne "analytics") {
$Template = "default"
}
# Match init-session.sh: zero args (or an empty name) preserve legacy root
# mode. A positional project name or -PlanDir creates an isolated
# .planning/<date>-<slug>/ plan.
$NamedPlan = $PSBoundParameters.ContainsKey("ProjectName") -and -not [string]::IsNullOrEmpty($ProjectName)
$UsePlanDir = $PlanDir -or $NamedPlan
if ($UsePlanDir) {
$PlanningRoot = Join-Path (Get-Location).Path ".planning"
# Match init-session.sh: set-active-plan.ps1 owns every write to the
# shared pointer, so a named plan cannot be created without it.
$PlanSelector = Join-Path $ScriptDir "set-active-plan.ps1"
if (-not (Test-Path -LiteralPath $PlanSelector -PathType Leaf)) {
Write-Error "Error: set-active-plan.ps1 is required to create a named plan safely."
exit 1
}
New-Item -ItemType Directory -Path $PlanningRoot -Force | Out-Null
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. A
# script that returns without exit leaves $LASTEXITCODE alone, so reset
# it first and treat a thrown error as a failure too.
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) {
Write-Error "Error: the planning directory or the active plan pointer is outside the project or cannot be verified."
exit 1
}
if ($NamedPlan) {
$Slug = Get-PlanSlug $ProjectName
} else {
$Slug = ""
$ProjectName = "untitled"
}
if ([string]::IsNullOrEmpty($Slug)) {
$Slug = "untitled-$(Get-ShortId)"
}
$BaseId = "$DATE-$Slug"
$PlanId = $BaseId
$Counter = 2
while (Test-Path -LiteralPath (Join-Path $PlanningRoot $PlanId)) {
$PlanId = "$BaseId-$Counter"
$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
}
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
}
$TaskPlanPath = Join-Path $TargetDir "task_plan.md"
$FindingsPath = Join-Path $TargetDir "findings.md"
$ProgressPath = Join-Path $TargetDir "progress.md"
if ($UsePlanDir) {
$TaskPlanDisplay = $TaskPlanPath
$FindingsDisplay = $FindingsPath
$ProgressDisplay = $ProgressPath
} else {
$TaskPlanDisplay = "task_plan.md"
$FindingsDisplay = "findings.md"
$ProgressDisplay = "progress.md"
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item $AnalyticsPlan "task_plan.md"
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
} else {
@"
# Task Plan: [Brief Description]
@@ -99,18 +226,18 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
}
Write-Host "Created task_plan.md"
Write-Host "Created $TaskPlanDisplay"
} else {
Write-Host "task_plan.md already exists, skipping"
Write-Host "$TaskPlanDisplay already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item $AnalyticsFindings "findings.md"
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
} else {
@"
# Findings & Decisions
@@ -131,15 +258,15 @@ if (-not (Test-Path "findings.md")) {
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
}
Write-Host "Created findings.md"
Write-Host "Created $FindingsDisplay"
} else {
Write-Host "findings.md already exists, skipping"
Write-Host "$FindingsDisplay already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
if (-not (Test-Path -LiteralPath $ProgressPath)) {
if ($Template -eq "analytics") {
@"
# Progress Log
@@ -160,7 +287,7 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
} else {
@"
# Progress Log
@@ -181,23 +308,28 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
}
Write-Host "Created progress.md"
Write-Host "Created $ProgressDisplay"
} else {
Write-Host "progress.md already exists, skipping"
Write-Host "$ProgressDisplay already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
if ($UsePlanDir) {
Write-Host "Active plan recorded: $(Join-Path $PlanningRoot '.active_plan')"
Write-Host "Pin this terminal to the plan for parallel sessions:"
Write-Host " `$env:PLAN_ID='$PlanId'"
} else {
Write-Host "Files: task_plan.md, findings.md, progress.md"
}
# v3 opt-in mode side effects. No-op when -Autonomous/-Gated were not passed, so
# the default path stays byte-equivalent to v2.43.0. PS1 init writes in CWD, so
# dotfiles live in CWD and attest-plan.ps1 falls back to the legacy
# .plan-attestation at the project root.
# the default path stays byte-equivalent to v2.43.0. Dotfiles live beside the
# selected plan; root mode therefore retains the legacy project-root behavior.
if ($Mode -ne "") {
$PlanDirPwf = (Get-Location).Path
$PlanDirPwf = $TargetDir
# (a) reset gate block counter, drop stale gate ledger.
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii
@@ -216,13 +348,42 @@ if ($Mode -ne "") {
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
$PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
if ((Test-Path -LiteralPath $AttestPs1) -and (Test-Path -LiteralPath $PlanFilePwf)) {
if (Test-Path -LiteralPath $PlanFilePwf) {
$HadPlanId = Test-Path Env:PLAN_ID
$PreviousPlanId = $env:PLAN_ID
try {
& $AttestPs1 *> $null
if ($UsePlanDir) {
$env:PLAN_ID = $PlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
$IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
if ($IsWindowsHost) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
}
} else {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
}
}
} catch {
# attestation failure must not abort init; the mode marker still stands.
} finally {
if ($HadPlanId) {
$env:PLAN_ID = $PreviousPlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
}
}
@@ -83,7 +83,8 @@ done
DATE=$(date +%Y-%m-%d)
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# CDPATH must not redirect the cd that locates the sibling scripts.
SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
TEMPLATE_DIR="$SKILL_ROOT/templates"
@@ -382,6 +383,20 @@ if [ "$SLUG_MODE" -eq 1 ]; then
BASE_ID="${DATE}-${SLUG}"
PLAN_ID="$BASE_ID"
PLAN_ROOT="${PWD}/.planning"
PLAN_SELECTOR="${SCRIPT_DIR}/set-active-plan.sh"
if [ ! -f "${PLAN_SELECTOR}" ]; then
echo "Error: set-active-plan.sh is required to create a named plan safely." >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. The
# selector's check is constant time; --list would parse every plan.
if ! sh "${PLAN_SELECTOR}" --verify-root; then
exit 1
fi
counter=2
while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
PLAN_ID="${BASE_ID}-${counter}"
@@ -393,7 +408,13 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
# Reuse the selector's contained, atomic pointer replacement. Direct shell
# redirection would truncate a pre-existing hardlink and could overwrite a
# different file that shares the same inode.
if ! sh "${PLAN_SELECTOR}" "${PLAN_ID}" >/dev/null; then
echo "Error: could not safely update ${PLAN_ROOT}/.active_plan." >&2
exit 1
fi
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
@@ -407,9 +407,6 @@ def get_session_candidates(
return 'claude', []
PLANNING_LIKE_SQL = ('%task_plan.md', '%findings.md', '%progress.md')
def get_opencode_db_path() -> Optional[Path]:
"""Resolve OpenCode SQLite path. Same on all OS per xdg-basedir."""
xdg = os.environ.get('XDG_DATA_HOME')
@@ -576,28 +573,42 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
update_time = None
update_idx = -1
for idx, (sid, _) in enumerate(previous_sessions):
params = (sid,) + PLANNING_LIKE_SQL
cur.execute(
"""
SELECT time_created FROM part
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
IN ('task_plan.md', 'findings.md', 'progress.md')
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/task_plan.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/findings.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/progress.md'
)
ORDER BY time_created DESC
LIMIT 1
ORDER BY time_created DESC, id DESC
""",
params,
(sid,),
)
row = cur.fetchone()
if row:
update_sid = sid
update_time = row[0]
update_idx = idx
# Iterate lazily: write parts carry whole file bodies, and fetchall
# would materialize every planning write of the session before the
# first validated row ends the loop.
for candidate_time, data_str in cur:
data = json_loads(data_str)
if not isinstance(data, dict):
continue
state = data.get('state')
input_ = state.get('input') if isinstance(state, dict) else None
file_path = input_.get('filePath') if isinstance(input_, dict) else None
if planning_file_from_path(file_path):
update_sid = sid
update_time = candidate_time
update_idx = idx
break
if update_sid:
break
if not update_sid:
@@ -685,12 +696,17 @@ def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
"""Return a planning filename only when it is the path's exact basename.
A suffix check treats lookalikes such as ``draft_task_plan.md`` as real
planning updates and can anchor catchup at unrelated transcript content.
Normalize separators so the same boundary rule works for Unix and Windows
session records.
"""
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
return basename if basename in PLANNING_FILES else None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
+290 -16
View File
@@ -1,27 +1,269 @@
# planning-with-files: set or display the active plan pointer (PowerShell).
# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[string]$PlanId = ""
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$PlanRoot = Join-Path (Get-Location) ".planning"
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
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)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
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.
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
(Test-WithinRoot $ActiveFile)
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
if (Test-Path $ActiveFile) {
$current = (Get-Content $ActiveFile -Raw -Encoding UTF8).Trim()
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ($current -ne "" -and (Test-Path $planDir)) {
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} elseif ($current -ne "") {
Write-Output "Active plan pointer: $current (directory not found - stale pointer)"
} else {
Write-Output "No active plan set."
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
@@ -29,21 +271,53 @@ if ($PlanId -eq "") {
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path $PlanDir)) {
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
if (-not (Test-Path $PlanRoot)) {
New-Item -ItemType Directory -Path $PlanRoot -Force | Out-Null
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($ActiveFile, $PlanId, $utf8NoBom)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file lives beside the pointer, keeping replacement on the same filesystem.
$tempFile = Join-Path $PlanRoot ('.active_plan.' + [guid]::NewGuid().ToString('N') + '.tmp')
$createdTemp = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$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)
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
exit 1
} finally {
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
+351 -38
View File
@@ -1,50 +1,363 @@
#!/bin/sh
# planning-with-files: set or display the active plan pointer.
#
# Usage:
# set-active-plan.sh <plan_id> — pin .planning/.active_plan to plan_id
# set-active-plan.sh — print the current active plan (if any)
#
# The active plan is stored in .planning/.active_plan and is read by
# resolve-plan-dir.sh when no $PLAN_ID env var is set.
set -e
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|--verify-root|PLAN_ID]
# Operates on the current project; listing never binds a host or injects data.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
PWF_ROOT_PIN=""
# No args → show current active plan
if [ "${1:-}" = "" ]; then
if [ -f "${ACTIVE_FILE}" ]; then
plan_id="$(tr -d '\r\n' < "${ACTIVE_FILE}")"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ]; then
echo "Active plan: ${plan_id}"
echo "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
echo "Active plan pointer: ${plan_id} (directory not found — stale pointer)"
else
echo "No active plan set."
fi
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Prints the canonical absolute path on success; prints nothing and returns 1
# on a full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
canonicalize() {
target="$1"
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
fi
return 1
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
echo "No active plan set."
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
cand_real="$(canonicalize "${check_target}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""
}
{
line = $0
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && primary == "" && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
primary = line
}
}
END {
finish()
printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && [ -r "${_plan_file}" ] || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.'
fi
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list|--verify-root|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--verify-root checks the planning root and pointer without listing or selecting.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
echo "Error: plan directory not found: ${PLAN_DIR}" >&2
echo "Run: init-session.sh \"${PLAN_ID}\" to create it, or check .planning/ for available plans." >&2
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
printf "%s\n" "${PLAN_ID}" > "${ACTIVE_FILE}"
echo "Active plan set to: ${PLAN_ID}"
echo "Path: ${PLAN_DIR}"
echo ""
echo "To pin this terminal session only:"
echo " export PLAN_ID=${PLAN_ID}"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
+1 -1
View File
@@ -10,7 +10,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Installs across 60+ agents.",
"version": "3.17.2"
"version": "3.19.0"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.17.2",
"version": "3.19.0",
"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.17.2"
version: "3.19.0"
---
@@ -213,6 +213,12 @@ Helper scripts for automation:
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history
### List saved plans
To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
@@ -10,7 +10,8 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall -> allow stop)
# When all hold, emits a single-line block-decision JSON on stdout and exits 0.
# Otherwise advisory output and exit 0. Without -Gate, byte-equivalent to v2.43.
# Otherwise reports incomplete plans and exits 0; completed plans stay silent
# with -Gate, including legacy plans without .mode. Explicit reports are unchanged.
#
# Stdin: read only when input is redirected ([Console]::IsInputRedirected), so an
# interactive console never blocks. Hook-piped JSON is EOF-terminated.
@@ -85,9 +86,10 @@ if ($TOTAL -eq 0) {
exit 0
}
# advisory_report: the v2.43 status echo.
# Keep explicit reports, but omit routine success from automatic gate checks.
function Write-AdvisoryReport {
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
if ($Gate) { return }
Write-Host ('[planning-with-files] ALL PHASES COMPLETE (' + $COMPLETE + '/' + $TOTAL + '). If the user has additional work, add new phases to task_plan.md before starting.')
} else {
Write-Host ('[planning-with-files] Task in progress (' + $COMPLETE + '/' + $TOTAL + ' phases complete). Update progress.md before stopping.')
@@ -21,8 +21,9 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall → allow stop)
# When all hold, it emits a single-line block-decision JSON on stdout and
# exits 0. Otherwise it falls back to advisory output and exits 0.
# Without --gate, or in non-gated mode, behavior is byte-equivalent to v2.43.
# exits 0. Otherwise it reports incomplete plans and exits 0; completed
# plans stay silent in --gate mode, including legacy plans without .mode.
# Without --gate, the explicit advisory report is unchanged.
#
# Stdin handling: the Claude Code Stop hook pipes a JSON payload on stdin. To
# avoid hanging when nothing is piped, stdin is read ONLY when fd 0 is not a
@@ -119,9 +120,11 @@ if [ "$TOTAL" -eq 0 ]; then
exit 0
fi
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
# Explicit status reports retain completion text. Automatic gate checks have
# nothing to report on success; keep evaluating all gate guards before here.
advisory_report() {
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
[ "$GATE" -eq 1 ] && return 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete). Update progress.md before stopping."
@@ -1,5 +1,6 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
# .\init-session.ps1 -PlanDir # isolated plan with generated slug
# .\init-session.ps1 -Autonomous # v3 autonomous mode (opt-in)
# .\init-session.ps1 -Gated # v3 gated mode (opt-in, implies autonomous)
# Templates: default, analytics
@@ -12,6 +13,7 @@
param(
[string]$ProjectName = "project",
[string]$Template = "default",
[switch]$PlanDir,
[switch]$Autonomous,
[switch]$Gated
)
@@ -38,7 +40,45 @@ function Get-Nonce {
($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
function Get-PlanSlug([string]$Name) {
# -creplace: the case-insensitive -replace lets letters that .NET folds to
# ASCII (a dotted capital I, the Kelvin sign) survive into the plan id.
$slug = $Name.ToLowerInvariant() -creplace '[^a-z0-9]', '-'
$slug = $slug -creplace '-{2,}', '-'
$slug = $slug.Trim('-')
if ($slug.Length -gt 40) {
$slug = $slug.Substring(0, 40).TrimEnd('-')
}
# The resolvers and the selector only accept ASCII plan ids.
if ($slug -cnotmatch '^[a-z0-9-]*$') {
return ""
}
return $slug
}
function Get-ShortId {
return ([Guid]::NewGuid().ToString('N')).Substring(0, 8)
}
function Get-InheritedMode([string]$CurrentMode) {
$RootModePath = Join-Path (Get-Location).Path ".mode"
if (-not (Test-Path -LiteralPath $RootModePath)) {
return $CurrentMode
}
if ($CurrentMode -eq "gated") {
return $CurrentMode
}
$RootMode = Get-Content -LiteralPath $RootModePath -Raw -ErrorAction SilentlyContinue
# Case-sensitive like inherit_root_mode in init-session.sh and the injector.
if ($RootMode -cmatch 'gate') {
return "gated"
}
if ($RootMode -cmatch 'autonomous') {
return "autonomous"
}
return $CurrentMode
}
# Validate template
if ($Template -ne "default" -and $Template -ne "analytics") {
@@ -46,11 +86,98 @@ if ($Template -ne "default" -and $Template -ne "analytics") {
$Template = "default"
}
# Match init-session.sh: zero args (or an empty name) preserve legacy root
# mode. A positional project name or -PlanDir creates an isolated
# .planning/<date>-<slug>/ plan.
$NamedPlan = $PSBoundParameters.ContainsKey("ProjectName") -and -not [string]::IsNullOrEmpty($ProjectName)
$UsePlanDir = $PlanDir -or $NamedPlan
if ($UsePlanDir) {
$PlanningRoot = Join-Path (Get-Location).Path ".planning"
# Match init-session.sh: set-active-plan.ps1 owns every write to the
# shared pointer, so a named plan cannot be created without it.
$PlanSelector = Join-Path $ScriptDir "set-active-plan.ps1"
if (-not (Test-Path -LiteralPath $PlanSelector -PathType Leaf)) {
Write-Error "Error: set-active-plan.ps1 is required to create a named plan safely."
exit 1
}
New-Item -ItemType Directory -Path $PlanningRoot -Force | Out-Null
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. A
# script that returns without exit leaves $LASTEXITCODE alone, so reset
# it first and treat a thrown error as a failure too.
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) {
Write-Error "Error: the planning directory or the active plan pointer is outside the project or cannot be verified."
exit 1
}
if ($NamedPlan) {
$Slug = Get-PlanSlug $ProjectName
} else {
$Slug = ""
$ProjectName = "untitled"
}
if ([string]::IsNullOrEmpty($Slug)) {
$Slug = "untitled-$(Get-ShortId)"
}
$BaseId = "$DATE-$Slug"
$PlanId = $BaseId
$Counter = 2
while (Test-Path -LiteralPath (Join-Path $PlanningRoot $PlanId)) {
$PlanId = "$BaseId-$Counter"
$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
}
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
}
$TaskPlanPath = Join-Path $TargetDir "task_plan.md"
$FindingsPath = Join-Path $TargetDir "findings.md"
$ProgressPath = Join-Path $TargetDir "progress.md"
if ($UsePlanDir) {
$TaskPlanDisplay = $TaskPlanPath
$FindingsDisplay = $FindingsPath
$ProgressDisplay = $ProgressPath
} else {
$TaskPlanDisplay = "task_plan.md"
$FindingsDisplay = "findings.md"
$ProgressDisplay = "progress.md"
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item $AnalyticsPlan "task_plan.md"
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
} else {
@"
# Task Plan: [Brief Description]
@@ -99,18 +226,18 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
}
Write-Host "Created task_plan.md"
Write-Host "Created $TaskPlanDisplay"
} else {
Write-Host "task_plan.md already exists, skipping"
Write-Host "$TaskPlanDisplay already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item $AnalyticsFindings "findings.md"
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
} else {
@"
# Findings & Decisions
@@ -131,15 +258,15 @@ if (-not (Test-Path "findings.md")) {
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
}
Write-Host "Created findings.md"
Write-Host "Created $FindingsDisplay"
} else {
Write-Host "findings.md already exists, skipping"
Write-Host "$FindingsDisplay already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
if (-not (Test-Path -LiteralPath $ProgressPath)) {
if ($Template -eq "analytics") {
@"
# Progress Log
@@ -160,7 +287,7 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
} else {
@"
# Progress Log
@@ -181,23 +308,28 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
}
Write-Host "Created progress.md"
Write-Host "Created $ProgressDisplay"
} else {
Write-Host "progress.md already exists, skipping"
Write-Host "$ProgressDisplay already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
if ($UsePlanDir) {
Write-Host "Active plan recorded: $(Join-Path $PlanningRoot '.active_plan')"
Write-Host "Pin this terminal to the plan for parallel sessions:"
Write-Host " `$env:PLAN_ID='$PlanId'"
} else {
Write-Host "Files: task_plan.md, findings.md, progress.md"
}
# v3 opt-in mode side effects. No-op when -Autonomous/-Gated were not passed, so
# the default path stays byte-equivalent to v2.43.0. PS1 init writes in CWD, so
# dotfiles live in CWD and attest-plan.ps1 falls back to the legacy
# .plan-attestation at the project root.
# the default path stays byte-equivalent to v2.43.0. Dotfiles live beside the
# selected plan; root mode therefore retains the legacy project-root behavior.
if ($Mode -ne "") {
$PlanDirPwf = (Get-Location).Path
$PlanDirPwf = $TargetDir
# (a) reset gate block counter, drop stale gate ledger.
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii
@@ -216,13 +348,42 @@ if ($Mode -ne "") {
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
$PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
if ((Test-Path -LiteralPath $AttestPs1) -and (Test-Path -LiteralPath $PlanFilePwf)) {
if (Test-Path -LiteralPath $PlanFilePwf) {
$HadPlanId = Test-Path Env:PLAN_ID
$PreviousPlanId = $env:PLAN_ID
try {
& $AttestPs1 *> $null
if ($UsePlanDir) {
$env:PLAN_ID = $PlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
$IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
if ($IsWindowsHost) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
}
} else {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
}
}
} catch {
# attestation failure must not abort init; the mode marker still stands.
} finally {
if ($HadPlanId) {
$env:PLAN_ID = $PreviousPlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
}
}
@@ -83,7 +83,8 @@ done
DATE=$(date +%Y-%m-%d)
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# CDPATH must not redirect the cd that locates the sibling scripts.
SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
TEMPLATE_DIR="$SKILL_ROOT/templates"
@@ -382,6 +383,20 @@ if [ "$SLUG_MODE" -eq 1 ]; then
BASE_ID="${DATE}-${SLUG}"
PLAN_ID="$BASE_ID"
PLAN_ROOT="${PWD}/.planning"
PLAN_SELECTOR="${SCRIPT_DIR}/set-active-plan.sh"
if [ ! -f "${PLAN_SELECTOR}" ]; then
echo "Error: set-active-plan.sh is required to create a named plan safely." >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. The
# selector's check is constant time; --list would parse every plan.
if ! sh "${PLAN_SELECTOR}" --verify-root; then
exit 1
fi
counter=2
while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
PLAN_ID="${BASE_ID}-${counter}"
@@ -393,7 +408,13 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
# Reuse the selector's contained, atomic pointer replacement. Direct shell
# redirection would truncate a pre-existing hardlink and could overwrite a
# different file that shares the same inode.
if ! sh "${PLAN_SELECTOR}" "${PLAN_ID}" >/dev/null; then
echo "Error: could not safely update ${PLAN_ROOT}/.active_plan." >&2
exit 1
fi
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
@@ -407,9 +407,6 @@ def get_session_candidates(
return 'claude', []
PLANNING_LIKE_SQL = ('%task_plan.md', '%findings.md', '%progress.md')
def get_opencode_db_path() -> Optional[Path]:
"""Resolve OpenCode SQLite path. Same on all OS per xdg-basedir."""
xdg = os.environ.get('XDG_DATA_HOME')
@@ -576,28 +573,42 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
update_time = None
update_idx = -1
for idx, (sid, _) in enumerate(previous_sessions):
params = (sid,) + PLANNING_LIKE_SQL
cur.execute(
"""
SELECT time_created FROM part
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
IN ('task_plan.md', 'findings.md', 'progress.md')
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/task_plan.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/findings.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/progress.md'
)
ORDER BY time_created DESC
LIMIT 1
ORDER BY time_created DESC, id DESC
""",
params,
(sid,),
)
row = cur.fetchone()
if row:
update_sid = sid
update_time = row[0]
update_idx = idx
# Iterate lazily: write parts carry whole file bodies, and fetchall
# would materialize every planning write of the session before the
# first validated row ends the loop.
for candidate_time, data_str in cur:
data = json_loads(data_str)
if not isinstance(data, dict):
continue
state = data.get('state')
input_ = state.get('input') if isinstance(state, dict) else None
file_path = input_.get('filePath') if isinstance(input_, dict) else None
if planning_file_from_path(file_path):
update_sid = sid
update_time = candidate_time
update_idx = idx
break
if update_sid:
break
if not update_sid:
@@ -685,12 +696,17 @@ def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
"""Return a planning filename only when it is the path's exact basename.
A suffix check treats lookalikes such as ``draft_task_plan.md`` as real
planning updates and can anchor catchup at unrelated transcript content.
Normalize separators so the same boundary rule works for Unix and Windows
session records.
"""
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
return basename if basename in PLANNING_FILES else None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
+290 -16
View File
@@ -1,27 +1,269 @@
# planning-with-files: set or display the active plan pointer (PowerShell).
# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[string]$PlanId = ""
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$PlanRoot = Join-Path (Get-Location) ".planning"
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
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)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
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.
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
(Test-WithinRoot $ActiveFile)
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
if (Test-Path $ActiveFile) {
$current = (Get-Content $ActiveFile -Raw -Encoding UTF8).Trim()
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ($current -ne "" -and (Test-Path $planDir)) {
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} elseif ($current -ne "") {
Write-Output "Active plan pointer: $current (directory not found - stale pointer)"
} else {
Write-Output "No active plan set."
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
@@ -29,21 +271,53 @@ if ($PlanId -eq "") {
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path $PlanDir)) {
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
if (-not (Test-Path $PlanRoot)) {
New-Item -ItemType Directory -Path $PlanRoot -Force | Out-Null
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($ActiveFile, $PlanId, $utf8NoBom)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file lives beside the pointer, keeping replacement on the same filesystem.
$tempFile = Join-Path $PlanRoot ('.active_plan.' + [guid]::NewGuid().ToString('N') + '.tmp')
$createdTemp = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$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)
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
exit 1
} finally {
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
+351 -38
View File
@@ -1,50 +1,363 @@
#!/bin/sh
# planning-with-files: set or display the active plan pointer.
#
# Usage:
# set-active-plan.sh <plan_id> — pin .planning/.active_plan to plan_id
# set-active-plan.sh — print the current active plan (if any)
#
# The active plan is stored in .planning/.active_plan and is read by
# resolve-plan-dir.sh when no $PLAN_ID env var is set.
set -e
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|--verify-root|PLAN_ID]
# Operates on the current project; listing never binds a host or injects data.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
PWF_ROOT_PIN=""
# No args → show current active plan
if [ "${1:-}" = "" ]; then
if [ -f "${ACTIVE_FILE}" ]; then
plan_id="$(tr -d '\r\n' < "${ACTIVE_FILE}")"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ]; then
echo "Active plan: ${plan_id}"
echo "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
echo "Active plan pointer: ${plan_id} (directory not found — stale pointer)"
else
echo "No active plan set."
fi
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Prints the canonical absolute path on success; prints nothing and returns 1
# on a full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
canonicalize() {
target="$1"
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
fi
return 1
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
echo "No active plan set."
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
cand_real="$(canonicalize "${check_target}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""
}
{
line = $0
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && primary == "" && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
primary = line
}
}
END {
finish()
printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && [ -r "${_plan_file}" ] || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.'
fi
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list|--verify-root|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--verify-root checks the planning root and pointer without listing or selecting.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
echo "Error: plan directory not found: ${PLAN_DIR}" >&2
echo "Run: init-session.sh \"${PLAN_ID}\" to create it, or check .planning/ for available plans." >&2
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
printf "%s\n" "${PLAN_ID}" > "${ACTIVE_FILE}"
echo "Active plan set to: ${PLAN_ID}"
echo "Path: ${PLAN_DIR}"
echo ""
echo "To pin this terminal session only:"
echo " export PLAN_ID=${PLAN_ID}"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.17.2",
"version": "3.19.0",
"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",
+2 -2
View File
@@ -37,10 +37,10 @@ if [ -f "$PLAN_FILE" ]; then
if [ -n "$PWF_PYTHON" ] && [ -f "$PWF_PYTHON" ] && [ -f "${HOOK_DIR}/context_frame.py" ]; then
if [ -n "$PLAN_DIR" ]; then ATTEST_FILE="${PLAN_DIR}/.attestation"; else ATTEST_FILE=".plan-attestation"; fi
if [ -n "$PLAN_DIR" ]; then MODE_FILE="${PLAN_DIR}/.mode"; else MODE_FILE=".mode"; fi
PWF_MODE=$("$PWF_PYTHON" -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import context_frame as c; raw=c.read_optional_regular_bytes(Path(sys.argv[2]), max_source_bytes=256); tokens=[] if raw is None else raw.decode("ascii", errors="strict").split(); allowed={"autonomous", "gate", "inject-smart"}; print("unsafe" if any(t not in allowed for t in tokens) else ("gated" if "gate" in tokens else ("autonomous" if "autonomous" in tokens else "legacy")))' "$HOOK_DIR" "$MODE_FILE" 2>/dev/null) || PWF_MODE="unsafe"
PWF_MODE=$("$PWF_PYTHON" -I -X utf8 -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import context_frame as c; raw=c.read_optional_regular_bytes(Path(sys.argv[2]), max_source_bytes=256); tokens=[] if raw is None else raw.decode("ascii", errors="strict").split(); allowed={"autonomous", "gate", "inject-smart"}; print("unsafe" if any(t not in allowed for t in tokens) else ("gated" if "gate" in tokens else ("autonomous" if "autonomous" in tokens else "legacy")))' "$HOOK_DIR" "$MODE_FILE" 2>/dev/null) || PWF_MODE="unsafe"
case "$PWF_MODE" in
autonomous|gated) echo '{"decision": "allow"}'; exit 0 ;;
legacy) "$PWF_PYTHON" "${HOOK_DIR}/context_frame.py" plan "$PLAN_FILE" --head 30 --attestation "$ATTEST_FILE" --mode "$MODE_FILE" >&2 ;;
legacy) "$PWF_PYTHON" -I -X utf8 "${HOOK_DIR}/context_frame.py" plan "$PLAN_FILE" --head 30 --attestation "$ATTEST_FILE" --mode "$MODE_FILE" >&2 ;;
*) : ;;
esac
fi
+1 -1
View File
@@ -12,7 +12,7 @@ SKILL_DIR="$CODEX_ROOT/skills/planning-with-files"
PYTHON_BIN="${PYTHON_BIN:-$(command -v python3 || command -v python)}"
if [ -n "$PYTHON_BIN" ] && [ -f "$SKILL_DIR/scripts/session-catchup.py" ]; then
"$PYTHON_BIN" "$SKILL_DIR/scripts/session-catchup.py" --no-history "$(pwd)"
"$PYTHON_BIN" -I -X utf8 "$SKILL_DIR/scripts/session-catchup.py" --no-history "$(pwd)"
fi
sh "$SCRIPT_DIR/user-prompt-submit.sh"
+2 -3
View File
@@ -23,8 +23,8 @@ fi
# Codex supports a native Stop continuation decision. Delegate the decision to
# the existing v3 gate oracle so Codex and skill-frontmatter installs share the
# same opt-in mode, in_progress, recursion, cap, and stall guards. Outside a
# gated block the oracle is advisory, and the legacy message below remains the
# public output for backward compatibility.
# gated block the oracle is advisory. Incomplete plans retain their notice;
# completed plans need no followup message.
CHECK_COMPLETE="${HOOK_DIR}/../skills/planning-with-files/scripts/check-complete.sh"
if [ "${1:-}" != "--stop-hook-active" ] && [ -f "${CHECK_COMPLETE}" ]; then
GATE_OUTPUT="$(sh "${CHECK_COMPLETE}" --gate "${PLAN_FILE}")"
@@ -59,7 +59,6 @@ if [ "$TOTAL" -eq 0 ]; then
fi
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
echo "{\"followup_message\": \"[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting.\"}"
exit 0
fi
+5 -5
View File
@@ -23,7 +23,7 @@ validate_python_candidate() {
case "$_tp_lower" in
*/microsoft/windowsapps/*) return 1 ;;
esac
"$_tp_candidate" -c 'import sys' >/dev/null 2>&1 || return 1
"$_tp_candidate" -I -X utf8 -c 'import sys' >/dev/null 2>&1 || return 1
printf '%s\n' "$_tp_candidate"
}
@@ -61,7 +61,7 @@ if [ -n "${PWF_PLAN_ROOT:-}" ]; then
esac
PIN_PYTHON="$(trusted_python explicit 2>/dev/null)" || PIN_PYTHON=""
[ -n "$PIN_PYTHON" ] || { echo "[planning-with-files] PWF_PLAN_ROOT could not be validated; nothing injected."; exit 0; }
PIN_REAL=$("$PIN_PYTHON" -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import codex_hook_adapter as a; root=a.effective_plan_root(Path.cwd()); print(root or "")' "$HOOK_DIR" 2>/dev/null) || PIN_REAL=""
PIN_REAL=$("$PIN_PYTHON" -I -X utf8 -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import codex_hook_adapter as a; root=a.effective_plan_root(Path.cwd()); print(root or "")' "$HOOK_DIR" 2>/dev/null) || PIN_REAL=""
[ -n "$PIN_REAL" ] || { echo "[planning-with-files] PWF_PLAN_ROOT must stay within the current workspace; nothing injected."; exit 0; }
if [ -n "$PIN_REAL" ] && [ -d "$PIN_REAL" ]; then
PWF_PLAN_ROOT="$PIN_REAL"
@@ -145,7 +145,7 @@ else
if [ -z "$PWF_PYTHON" ]; then
PWF_SESSION_ADMISSION="refused"
else
PWF_SESSION_ADMISSION=$("$PWF_PYTHON" -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import codex_hook_adapter as a; root=a.effective_plan_root(Path.cwd());
PWF_SESSION_ADMISSION=$("$PWF_PYTHON" -I -X utf8 -c 'import sys; from pathlib import Path; sys.path.insert(0, sys.argv[1]); import codex_hook_adapter as a; root=a.effective_plan_root(Path.cwd());
if root is None: print("refused")
else:
try: (root / ".planning" / "sessions").lstat(); armed=True
@@ -253,13 +253,13 @@ if [ -f "$PLAN_FILE" ]; then
if [ -z "$PWF_PYTHON" ] || [ ! -f "${HOOK_DIR}/context_frame.py" ]; then exit 0; fi
if [ -n "$PLAN_DIR" ]; then ATTEST_FILE="${PLAN_DIR}/.attestation"; else ATTEST_FILE="${PLAN_PREFIX}.plan-attestation"; fi
if [ -n "$PLAN_DIR" ]; then MODE_FILE="${PLAN_DIR}/.mode"; else MODE_FILE="${PLAN_PREFIX}.mode"; fi
PLAN_CONTEXT=$("$PWF_PYTHON" "${HOOK_DIR}/context_frame.py" plan "$PLAN_FILE" --head 50 --attestation "$ATTEST_FILE" --mode "$MODE_FILE" 2>&1)
PLAN_CONTEXT=$("$PWF_PYTHON" -I -X utf8 "${HOOK_DIR}/context_frame.py" plan "$PLAN_FILE" --head 50 --attestation "$ATTEST_FILE" --mode "$MODE_FILE" 2>&1)
if [ $? -ne 0 ]; then printf '%s\n' "$PLAN_CONTEXT"; exit 0; fi
echo "[planning-with-files] ACTIVE PLAN — current state:"
printf '%s\n' "$PLAN_CONTEXT"
echo ""
if [ -f "$PROGRESS_FILE" ]; then
PROGRESS_CONTEXT=$("$PWF_PYTHON" "${HOOK_DIR}/context_frame.py" progress "$PROGRESS_FILE" --tail 20 2>&1)
PROGRESS_CONTEXT=$("$PWF_PYTHON" -I -X utf8 "${HOOK_DIR}/context_frame.py" progress "$PROGRESS_FILE" --tail 20 2>&1)
[ $? -eq 0 ] && printf '%s\n' "$PROGRESS_CONTEXT"
fi
echo ""
+7 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.2"
version: "3.19.0"
---
@@ -212,6 +212,12 @@ Helper scripts for automation:
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history
### List saved plans
To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
## Advanced Topics
- **Manus Principles:** See [references/reference.md](references/reference.md)
@@ -10,7 +10,8 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall -> allow stop)
# When all hold, emits a single-line block-decision JSON on stdout and exits 0.
# Otherwise advisory output and exit 0. Without -Gate, byte-equivalent to v2.43.
# Otherwise reports incomplete plans and exits 0; completed plans stay silent
# with -Gate, including legacy plans without .mode. Explicit reports are unchanged.
#
# Stdin: read only when input is redirected ([Console]::IsInputRedirected), so an
# interactive console never blocks. Hook-piped JSON is EOF-terminated.
@@ -85,9 +86,10 @@ if ($TOTAL -eq 0) {
exit 0
}
# advisory_report: the v2.43 status echo.
# Keep explicit reports, but omit routine success from automatic gate checks.
function Write-AdvisoryReport {
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
if ($Gate) { return }
Write-Host ('[planning-with-files] ALL PHASES COMPLETE (' + $COMPLETE + '/' + $TOTAL + '). If the user has additional work, add new phases to task_plan.md before starting.')
} else {
Write-Host ('[planning-with-files] Task in progress (' + $COMPLETE + '/' + $TOTAL + ' phases complete). Update progress.md before stopping.')
@@ -21,8 +21,9 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall → allow stop)
# When all hold, it emits a single-line block-decision JSON on stdout and
# exits 0. Otherwise it falls back to advisory output and exits 0.
# Without --gate, or in non-gated mode, behavior is byte-equivalent to v2.43.
# exits 0. Otherwise it reports incomplete plans and exits 0; completed
# plans stay silent in --gate mode, including legacy plans without .mode.
# Without --gate, the explicit advisory report is unchanged.
#
# Stdin handling: the Claude Code Stop hook pipes a JSON payload on stdin. To
# avoid hanging when nothing is piped, stdin is read ONLY when fd 0 is not a
@@ -119,9 +120,11 @@ if [ "$TOTAL" -eq 0 ]; then
exit 0
fi
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
# Explicit status reports retain completion text. Automatic gate checks have
# nothing to report on success; keep evaluating all gate guards before here.
advisory_report() {
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
[ "$GATE" -eq 1 ] && return 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete). Update progress.md before stopping."
@@ -1,5 +1,6 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
# .\init-session.ps1 -PlanDir # isolated plan with generated slug
# .\init-session.ps1 -Autonomous # v3 autonomous mode (opt-in)
# .\init-session.ps1 -Gated # v3 gated mode (opt-in, implies autonomous)
# Templates: default, analytics
@@ -12,6 +13,7 @@
param(
[string]$ProjectName = "project",
[string]$Template = "default",
[switch]$PlanDir,
[switch]$Autonomous,
[switch]$Gated
)
@@ -38,7 +40,45 @@ function Get-Nonce {
($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
function Get-PlanSlug([string]$Name) {
# -creplace: the case-insensitive -replace lets letters that .NET folds to
# ASCII (a dotted capital I, the Kelvin sign) survive into the plan id.
$slug = $Name.ToLowerInvariant() -creplace '[^a-z0-9]', '-'
$slug = $slug -creplace '-{2,}', '-'
$slug = $slug.Trim('-')
if ($slug.Length -gt 40) {
$slug = $slug.Substring(0, 40).TrimEnd('-')
}
# The resolvers and the selector only accept ASCII plan ids.
if ($slug -cnotmatch '^[a-z0-9-]*$') {
return ""
}
return $slug
}
function Get-ShortId {
return ([Guid]::NewGuid().ToString('N')).Substring(0, 8)
}
function Get-InheritedMode([string]$CurrentMode) {
$RootModePath = Join-Path (Get-Location).Path ".mode"
if (-not (Test-Path -LiteralPath $RootModePath)) {
return $CurrentMode
}
if ($CurrentMode -eq "gated") {
return $CurrentMode
}
$RootMode = Get-Content -LiteralPath $RootModePath -Raw -ErrorAction SilentlyContinue
# Case-sensitive like inherit_root_mode in init-session.sh and the injector.
if ($RootMode -cmatch 'gate') {
return "gated"
}
if ($RootMode -cmatch 'autonomous') {
return "autonomous"
}
return $CurrentMode
}
# Validate template
if ($Template -ne "default" -and $Template -ne "analytics") {
@@ -46,11 +86,98 @@ if ($Template -ne "default" -and $Template -ne "analytics") {
$Template = "default"
}
# Match init-session.sh: zero args (or an empty name) preserve legacy root
# mode. A positional project name or -PlanDir creates an isolated
# .planning/<date>-<slug>/ plan.
$NamedPlan = $PSBoundParameters.ContainsKey("ProjectName") -and -not [string]::IsNullOrEmpty($ProjectName)
$UsePlanDir = $PlanDir -or $NamedPlan
if ($UsePlanDir) {
$PlanningRoot = Join-Path (Get-Location).Path ".planning"
# Match init-session.sh: set-active-plan.ps1 owns every write to the
# shared pointer, so a named plan cannot be created without it.
$PlanSelector = Join-Path $ScriptDir "set-active-plan.ps1"
if (-not (Test-Path -LiteralPath $PlanSelector -PathType Leaf)) {
Write-Error "Error: set-active-plan.ps1 is required to create a named plan safely."
exit 1
}
New-Item -ItemType Directory -Path $PlanningRoot -Force | Out-Null
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. A
# script that returns without exit leaves $LASTEXITCODE alone, so reset
# it first and treat a thrown error as a failure too.
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) {
Write-Error "Error: the planning directory or the active plan pointer is outside the project or cannot be verified."
exit 1
}
if ($NamedPlan) {
$Slug = Get-PlanSlug $ProjectName
} else {
$Slug = ""
$ProjectName = "untitled"
}
if ([string]::IsNullOrEmpty($Slug)) {
$Slug = "untitled-$(Get-ShortId)"
}
$BaseId = "$DATE-$Slug"
$PlanId = $BaseId
$Counter = 2
while (Test-Path -LiteralPath (Join-Path $PlanningRoot $PlanId)) {
$PlanId = "$BaseId-$Counter"
$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
}
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
}
$TaskPlanPath = Join-Path $TargetDir "task_plan.md"
$FindingsPath = Join-Path $TargetDir "findings.md"
$ProgressPath = Join-Path $TargetDir "progress.md"
if ($UsePlanDir) {
$TaskPlanDisplay = $TaskPlanPath
$FindingsDisplay = $FindingsPath
$ProgressDisplay = $ProgressPath
} else {
$TaskPlanDisplay = "task_plan.md"
$FindingsDisplay = "findings.md"
$ProgressDisplay = "progress.md"
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item $AnalyticsPlan "task_plan.md"
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
} else {
@"
# Task Plan: [Brief Description]
@@ -99,18 +226,18 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
}
Write-Host "Created task_plan.md"
Write-Host "Created $TaskPlanDisplay"
} else {
Write-Host "task_plan.md already exists, skipping"
Write-Host "$TaskPlanDisplay already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item $AnalyticsFindings "findings.md"
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
} else {
@"
# Findings & Decisions
@@ -131,15 +258,15 @@ if (-not (Test-Path "findings.md")) {
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
}
Write-Host "Created findings.md"
Write-Host "Created $FindingsDisplay"
} else {
Write-Host "findings.md already exists, skipping"
Write-Host "$FindingsDisplay already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
if (-not (Test-Path -LiteralPath $ProgressPath)) {
if ($Template -eq "analytics") {
@"
# Progress Log
@@ -160,7 +287,7 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
} else {
@"
# Progress Log
@@ -181,23 +308,28 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
}
Write-Host "Created progress.md"
Write-Host "Created $ProgressDisplay"
} else {
Write-Host "progress.md already exists, skipping"
Write-Host "$ProgressDisplay already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
if ($UsePlanDir) {
Write-Host "Active plan recorded: $(Join-Path $PlanningRoot '.active_plan')"
Write-Host "Pin this terminal to the plan for parallel sessions:"
Write-Host " `$env:PLAN_ID='$PlanId'"
} else {
Write-Host "Files: task_plan.md, findings.md, progress.md"
}
# v3 opt-in mode side effects. No-op when -Autonomous/-Gated were not passed, so
# the default path stays byte-equivalent to v2.43.0. PS1 init writes in CWD, so
# dotfiles live in CWD and attest-plan.ps1 falls back to the legacy
# .plan-attestation at the project root.
# the default path stays byte-equivalent to v2.43.0. Dotfiles live beside the
# selected plan; root mode therefore retains the legacy project-root behavior.
if ($Mode -ne "") {
$PlanDirPwf = (Get-Location).Path
$PlanDirPwf = $TargetDir
# (a) reset gate block counter, drop stale gate ledger.
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii
@@ -216,13 +348,42 @@ if ($Mode -ne "") {
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
$PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
if ((Test-Path -LiteralPath $AttestPs1) -and (Test-Path -LiteralPath $PlanFilePwf)) {
if (Test-Path -LiteralPath $PlanFilePwf) {
$HadPlanId = Test-Path Env:PLAN_ID
$PreviousPlanId = $env:PLAN_ID
try {
& $AttestPs1 *> $null
if ($UsePlanDir) {
$env:PLAN_ID = $PlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
$IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
if ($IsWindowsHost) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
}
} else {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
}
}
} catch {
# attestation failure must not abort init; the mode marker still stands.
} finally {
if ($HadPlanId) {
$env:PLAN_ID = $PreviousPlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
}
}
@@ -83,7 +83,8 @@ done
DATE=$(date +%Y-%m-%d)
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# CDPATH must not redirect the cd that locates the sibling scripts.
SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
TEMPLATE_DIR="$SKILL_ROOT/templates"
@@ -382,6 +383,20 @@ if [ "$SLUG_MODE" -eq 1 ]; then
BASE_ID="${DATE}-${SLUG}"
PLAN_ID="$BASE_ID"
PLAN_ROOT="${PWD}/.planning"
PLAN_SELECTOR="${SCRIPT_DIR}/set-active-plan.sh"
if [ ! -f "${PLAN_SELECTOR}" ]; then
echo "Error: set-active-plan.sh is required to create a named plan safely." >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. The
# selector's check is constant time; --list would parse every plan.
if ! sh "${PLAN_SELECTOR}" --verify-root; then
exit 1
fi
counter=2
while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
PLAN_ID="${BASE_ID}-${counter}"
@@ -393,7 +408,13 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
# Reuse the selector's contained, atomic pointer replacement. Direct shell
# redirection would truncate a pre-existing hardlink and could overwrite a
# different file that shares the same inode.
if ! sh "${PLAN_SELECTOR}" "${PLAN_ID}" >/dev/null; then
echo "Error: could not safely update ${PLAN_ROOT}/.active_plan." >&2
exit 1
fi
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
@@ -407,9 +407,6 @@ def get_session_candidates(
return 'claude', []
PLANNING_LIKE_SQL = ('%task_plan.md', '%findings.md', '%progress.md')
def get_opencode_db_path() -> Optional[Path]:
"""Resolve OpenCode SQLite path. Same on all OS per xdg-basedir."""
xdg = os.environ.get('XDG_DATA_HOME')
@@ -576,28 +573,42 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
update_time = None
update_idx = -1
for idx, (sid, _) in enumerate(previous_sessions):
params = (sid,) + PLANNING_LIKE_SQL
cur.execute(
"""
SELECT time_created FROM part
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
IN ('task_plan.md', 'findings.md', 'progress.md')
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/task_plan.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/findings.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/progress.md'
)
ORDER BY time_created DESC
LIMIT 1
ORDER BY time_created DESC, id DESC
""",
params,
(sid,),
)
row = cur.fetchone()
if row:
update_sid = sid
update_time = row[0]
update_idx = idx
# Iterate lazily: write parts carry whole file bodies, and fetchall
# would materialize every planning write of the session before the
# first validated row ends the loop.
for candidate_time, data_str in cur:
data = json_loads(data_str)
if not isinstance(data, dict):
continue
state = data.get('state')
input_ = state.get('input') if isinstance(state, dict) else None
file_path = input_.get('filePath') if isinstance(input_, dict) else None
if planning_file_from_path(file_path):
update_sid = sid
update_time = candidate_time
update_idx = idx
break
if update_sid:
break
if not update_sid:
@@ -685,12 +696,17 @@ def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
"""Return a planning filename only when it is the path's exact basename.
A suffix check treats lookalikes such as ``draft_task_plan.md`` as real
planning updates and can anchor catchup at unrelated transcript content.
Normalize separators so the same boundary rule works for Unix and Windows
session records.
"""
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
return basename if basename in PLANNING_FILES else None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
+290 -16
View File
@@ -1,27 +1,269 @@
# planning-with-files: set or display the active plan pointer (PowerShell).
# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[string]$PlanId = ""
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$PlanRoot = Join-Path (Get-Location) ".planning"
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
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)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
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.
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
(Test-WithinRoot $ActiveFile)
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
if (Test-Path $ActiveFile) {
$current = (Get-Content $ActiveFile -Raw -Encoding UTF8).Trim()
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ($current -ne "" -and (Test-Path $planDir)) {
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} elseif ($current -ne "") {
Write-Output "Active plan pointer: $current (directory not found - stale pointer)"
} else {
Write-Output "No active plan set."
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
@@ -29,21 +271,53 @@ if ($PlanId -eq "") {
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path $PlanDir)) {
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
if (-not (Test-Path $PlanRoot)) {
New-Item -ItemType Directory -Path $PlanRoot -Force | Out-Null
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($ActiveFile, $PlanId, $utf8NoBom)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file lives beside the pointer, keeping replacement on the same filesystem.
$tempFile = Join-Path $PlanRoot ('.active_plan.' + [guid]::NewGuid().ToString('N') + '.tmp')
$createdTemp = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$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)
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
exit 1
} finally {
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
+351 -38
View File
@@ -1,50 +1,363 @@
#!/bin/sh
# planning-with-files: set or display the active plan pointer.
#
# Usage:
# set-active-plan.sh <plan_id> — pin .planning/.active_plan to plan_id
# set-active-plan.sh — print the current active plan (if any)
#
# The active plan is stored in .planning/.active_plan and is read by
# resolve-plan-dir.sh when no $PLAN_ID env var is set.
set -e
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|--verify-root|PLAN_ID]
# Operates on the current project; listing never binds a host or injects data.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
PWF_ROOT_PIN=""
# No args → show current active plan
if [ "${1:-}" = "" ]; then
if [ -f "${ACTIVE_FILE}" ]; then
plan_id="$(tr -d '\r\n' < "${ACTIVE_FILE}")"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ]; then
echo "Active plan: ${plan_id}"
echo "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
echo "Active plan pointer: ${plan_id} (directory not found — stale pointer)"
else
echo "No active plan set."
fi
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Prints the canonical absolute path on success; prints nothing and returns 1
# on a full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
canonicalize() {
target="$1"
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
fi
return 1
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
echo "No active plan set."
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
cand_real="$(canonicalize "${check_target}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""
}
{
line = $0
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && primary == "" && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
primary = line
}
}
END {
finish()
printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && [ -r "${_plan_file}" ] || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.'
fi
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list|--verify-root|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--verify-root checks the planning root and pointer without listing or selecting.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
echo "Error: plan directory not found: ${PLAN_DIR}" >&2
echo "Run: init-session.sh \"${PLAN_ID}\" to create it, or check .planning/ for available plans." >&2
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
printf "%s\n" "${PLAN_ID}" > "${ACTIVE_FILE}"
echo "Active plan set to: ${PLAN_ID}"
echo "Path: ${PLAN_DIR}"
echo ""
echo "To pin this terminal session only:"
echo " export PLAN_ID=${PLAN_ID}"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
+19 -15
View File
@@ -181,32 +181,36 @@ 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/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`, checks `.planning/.active_plan`, then newest plan dir by mtime, then falls back to project root (legacy). Used internally by hooks.
- `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. OpenCode uses its read-only SQLite store.
- `scripts/attest-plan.sh` (and `.ps1`) — Lock the current `task_plan.md` content with a SHA-256 attestation (v2.37.0). Hooks then refuse to inject plan content if the file diverges from the attested hash. Use `--show` to print the stored hash, `--clear` to remove the attestation.
### List saved plans
To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
### Parallel task workflow
When working on multiple tasks in the same repo simultaneously:
For concurrent tasks, initialize a named plan and pin each host before starting it. Set `SKILL_DIR` to the installed skill directory in each terminal and keep your current directory at the project root:
```bash
# Start task A
.init-session.sh "Backend Refactor"
# → .planning/2026-01-10-backend-refactor/task_plan.md
# Terminal A: use the exact PLAN_ID printed by initialization.
sh "$SKILL_DIR/scripts/init-session.sh" "Backend Refactor"
export PLAN_ID=2026-09-13-backend-refactor
# Start the first agent from this terminal after setting PLAN_ID.
# Start task B in a second terminal
.init-session.sh "Incident Investigation"
# → .planning/2026-01-10-incident-investigation/task_plan.md
# Switch active plan
.set-active-plan.sh 2026-01-10-backend-refactor
# Or pin a terminal to a specific plan
export PLAN_ID=2026-01-10-backend-refactor
# Terminal B: use the different PLAN_ID printed for this task.
sh "$SKILL_DIR/scripts/init-session.sh" "Incident Investigation"
export PLAN_ID=2026-09-13-incident-investigation
# Start the second agent from this terminal after setting PLAN_ID.
```
Each session reads from its own isolated plan directory. Hooks resolve the correct plan automatically.
The IDs are examples; use the IDs printed by your initialization commands. In PowerShell, set `$env:PLAN_ID` before starting the host. Setting it inside an already-running agent's tool subprocess does not change the parent host's environment. Use separate worktrees if the host cannot be pinned per task.
Use `set-active-plan` for sequential switching of the shared default pointer. Concurrent sessions need their own `PLAN_ID` even when the listing shows `[active]`.
## Advanced Topics
@@ -10,7 +10,8 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall -> allow stop)
# When all hold, emits a single-line block-decision JSON on stdout and exits 0.
# Otherwise advisory output and exit 0. Without -Gate, byte-equivalent to v2.43.
# Otherwise reports incomplete plans and exits 0; completed plans stay silent
# with -Gate, including legacy plans without .mode. Explicit reports are unchanged.
#
# Stdin: read only when input is redirected ([Console]::IsInputRedirected), so an
# interactive console never blocks. Hook-piped JSON is EOF-terminated.
@@ -85,9 +86,10 @@ if ($TOTAL -eq 0) {
exit 0
}
# advisory_report: the v2.43 status echo.
# Keep explicit reports, but omit routine success from automatic gate checks.
function Write-AdvisoryReport {
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
if ($Gate) { return }
Write-Host ('[planning-with-files] ALL PHASES COMPLETE (' + $COMPLETE + '/' + $TOTAL + '). If the user has additional work, add new phases to task_plan.md before starting.')
} else {
Write-Host ('[planning-with-files] Task in progress (' + $COMPLETE + '/' + $TOTAL + ' phases complete). Update progress.md before stopping.')
@@ -21,8 +21,9 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall → allow stop)
# When all hold, it emits a single-line block-decision JSON on stdout and
# exits 0. Otherwise it falls back to advisory output and exits 0.
# Without --gate, or in non-gated mode, behavior is byte-equivalent to v2.43.
# exits 0. Otherwise it reports incomplete plans and exits 0; completed
# plans stay silent in --gate mode, including legacy plans without .mode.
# Without --gate, the explicit advisory report is unchanged.
#
# Stdin handling: the Claude Code Stop hook pipes a JSON payload on stdin. To
# avoid hanging when nothing is piped, stdin is read ONLY when fd 0 is not a
@@ -119,9 +120,11 @@ if [ "$TOTAL" -eq 0 ]; then
exit 0
fi
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
# Explicit status reports retain completion text. Automatic gate checks have
# nothing to report on success; keep evaluating all gate guards before here.
advisory_report() {
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
[ "$GATE" -eq 1 ] && return 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete). Update progress.md before stopping."
@@ -1,5 +1,6 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
# .\init-session.ps1 -PlanDir # isolated plan with generated slug
# .\init-session.ps1 -Autonomous # v3 autonomous mode (opt-in)
# .\init-session.ps1 -Gated # v3 gated mode (opt-in, implies autonomous)
# Templates: default, analytics
@@ -12,6 +13,7 @@
param(
[string]$ProjectName = "project",
[string]$Template = "default",
[switch]$PlanDir,
[switch]$Autonomous,
[switch]$Gated
)
@@ -38,7 +40,45 @@ function Get-Nonce {
($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
function Get-PlanSlug([string]$Name) {
# -creplace: the case-insensitive -replace lets letters that .NET folds to
# ASCII (a dotted capital I, the Kelvin sign) survive into the plan id.
$slug = $Name.ToLowerInvariant() -creplace '[^a-z0-9]', '-'
$slug = $slug -creplace '-{2,}', '-'
$slug = $slug.Trim('-')
if ($slug.Length -gt 40) {
$slug = $slug.Substring(0, 40).TrimEnd('-')
}
# The resolvers and the selector only accept ASCII plan ids.
if ($slug -cnotmatch '^[a-z0-9-]*$') {
return ""
}
return $slug
}
function Get-ShortId {
return ([Guid]::NewGuid().ToString('N')).Substring(0, 8)
}
function Get-InheritedMode([string]$CurrentMode) {
$RootModePath = Join-Path (Get-Location).Path ".mode"
if (-not (Test-Path -LiteralPath $RootModePath)) {
return $CurrentMode
}
if ($CurrentMode -eq "gated") {
return $CurrentMode
}
$RootMode = Get-Content -LiteralPath $RootModePath -Raw -ErrorAction SilentlyContinue
# Case-sensitive like inherit_root_mode in init-session.sh and the injector.
if ($RootMode -cmatch 'gate') {
return "gated"
}
if ($RootMode -cmatch 'autonomous') {
return "autonomous"
}
return $CurrentMode
}
# Validate template
if ($Template -ne "default" -and $Template -ne "analytics") {
@@ -46,11 +86,98 @@ if ($Template -ne "default" -and $Template -ne "analytics") {
$Template = "default"
}
# Match init-session.sh: zero args (or an empty name) preserve legacy root
# mode. A positional project name or -PlanDir creates an isolated
# .planning/<date>-<slug>/ plan.
$NamedPlan = $PSBoundParameters.ContainsKey("ProjectName") -and -not [string]::IsNullOrEmpty($ProjectName)
$UsePlanDir = $PlanDir -or $NamedPlan
if ($UsePlanDir) {
$PlanningRoot = Join-Path (Get-Location).Path ".planning"
# Match init-session.sh: set-active-plan.ps1 owns every write to the
# shared pointer, so a named plan cannot be created without it.
$PlanSelector = Join-Path $ScriptDir "set-active-plan.ps1"
if (-not (Test-Path -LiteralPath $PlanSelector -PathType Leaf)) {
Write-Error "Error: set-active-plan.ps1 is required to create a named plan safely."
exit 1
}
New-Item -ItemType Directory -Path $PlanningRoot -Force | Out-Null
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. A
# script that returns without exit leaves $LASTEXITCODE alone, so reset
# it first and treat a thrown error as a failure too.
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) {
Write-Error "Error: the planning directory or the active plan pointer is outside the project or cannot be verified."
exit 1
}
if ($NamedPlan) {
$Slug = Get-PlanSlug $ProjectName
} else {
$Slug = ""
$ProjectName = "untitled"
}
if ([string]::IsNullOrEmpty($Slug)) {
$Slug = "untitled-$(Get-ShortId)"
}
$BaseId = "$DATE-$Slug"
$PlanId = $BaseId
$Counter = 2
while (Test-Path -LiteralPath (Join-Path $PlanningRoot $PlanId)) {
$PlanId = "$BaseId-$Counter"
$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
}
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
}
$TaskPlanPath = Join-Path $TargetDir "task_plan.md"
$FindingsPath = Join-Path $TargetDir "findings.md"
$ProgressPath = Join-Path $TargetDir "progress.md"
if ($UsePlanDir) {
$TaskPlanDisplay = $TaskPlanPath
$FindingsDisplay = $FindingsPath
$ProgressDisplay = $ProgressPath
} else {
$TaskPlanDisplay = "task_plan.md"
$FindingsDisplay = "findings.md"
$ProgressDisplay = "progress.md"
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item $AnalyticsPlan "task_plan.md"
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
} else {
@"
# Task Plan: [Brief Description]
@@ -99,18 +226,18 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
}
Write-Host "Created task_plan.md"
Write-Host "Created $TaskPlanDisplay"
} else {
Write-Host "task_plan.md already exists, skipping"
Write-Host "$TaskPlanDisplay already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item $AnalyticsFindings "findings.md"
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
} else {
@"
# Findings & Decisions
@@ -131,15 +258,15 @@ if (-not (Test-Path "findings.md")) {
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
}
Write-Host "Created findings.md"
Write-Host "Created $FindingsDisplay"
} else {
Write-Host "findings.md already exists, skipping"
Write-Host "$FindingsDisplay already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
if (-not (Test-Path -LiteralPath $ProgressPath)) {
if ($Template -eq "analytics") {
@"
# Progress Log
@@ -160,7 +287,7 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
} else {
@"
# Progress Log
@@ -181,23 +308,28 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
}
Write-Host "Created progress.md"
Write-Host "Created $ProgressDisplay"
} else {
Write-Host "progress.md already exists, skipping"
Write-Host "$ProgressDisplay already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
if ($UsePlanDir) {
Write-Host "Active plan recorded: $(Join-Path $PlanningRoot '.active_plan')"
Write-Host "Pin this terminal to the plan for parallel sessions:"
Write-Host " `$env:PLAN_ID='$PlanId'"
} else {
Write-Host "Files: task_plan.md, findings.md, progress.md"
}
# v3 opt-in mode side effects. No-op when -Autonomous/-Gated were not passed, so
# the default path stays byte-equivalent to v2.43.0. PS1 init writes in CWD, so
# dotfiles live in CWD and attest-plan.ps1 falls back to the legacy
# .plan-attestation at the project root.
# the default path stays byte-equivalent to v2.43.0. Dotfiles live beside the
# selected plan; root mode therefore retains the legacy project-root behavior.
if ($Mode -ne "") {
$PlanDirPwf = (Get-Location).Path
$PlanDirPwf = $TargetDir
# (a) reset gate block counter, drop stale gate ledger.
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii
@@ -216,13 +348,42 @@ if ($Mode -ne "") {
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
$PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
if ((Test-Path -LiteralPath $AttestPs1) -and (Test-Path -LiteralPath $PlanFilePwf)) {
if (Test-Path -LiteralPath $PlanFilePwf) {
$HadPlanId = Test-Path Env:PLAN_ID
$PreviousPlanId = $env:PLAN_ID
try {
& $AttestPs1 *> $null
if ($UsePlanDir) {
$env:PLAN_ID = $PlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
$IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
if ($IsWindowsHost) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
}
} else {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
}
}
} catch {
# attestation failure must not abort init; the mode marker still stands.
} finally {
if ($HadPlanId) {
$env:PLAN_ID = $PreviousPlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
}
}
@@ -83,7 +83,8 @@ done
DATE=$(date +%Y-%m-%d)
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# CDPATH must not redirect the cd that locates the sibling scripts.
SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
TEMPLATE_DIR="$SKILL_ROOT/templates"
@@ -382,6 +383,20 @@ if [ "$SLUG_MODE" -eq 1 ]; then
BASE_ID="${DATE}-${SLUG}"
PLAN_ID="$BASE_ID"
PLAN_ROOT="${PWD}/.planning"
PLAN_SELECTOR="${SCRIPT_DIR}/set-active-plan.sh"
if [ ! -f "${PLAN_SELECTOR}" ]; then
echo "Error: set-active-plan.sh is required to create a named plan safely." >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. The
# selector's check is constant time; --list would parse every plan.
if ! sh "${PLAN_SELECTOR}" --verify-root; then
exit 1
fi
counter=2
while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
PLAN_ID="${BASE_ID}-${counter}"
@@ -393,7 +408,13 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
# Reuse the selector's contained, atomic pointer replacement. Direct shell
# redirection would truncate a pre-existing hardlink and could overwrite a
# different file that shares the same inode.
if ! sh "${PLAN_SELECTOR}" "${PLAN_ID}" >/dev/null; then
echo "Error: could not safely update ${PLAN_ROOT}/.active_plan." >&2
exit 1
fi
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
@@ -407,9 +407,6 @@ def get_session_candidates(
return 'claude', []
PLANNING_LIKE_SQL = ('%task_plan.md', '%findings.md', '%progress.md')
def get_opencode_db_path() -> Optional[Path]:
"""Resolve OpenCode SQLite path. Same on all OS per xdg-basedir."""
xdg = os.environ.get('XDG_DATA_HOME')
@@ -576,28 +573,42 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
update_time = None
update_idx = -1
for idx, (sid, _) in enumerate(previous_sessions):
params = (sid,) + PLANNING_LIKE_SQL
cur.execute(
"""
SELECT time_created FROM part
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
IN ('task_plan.md', 'findings.md', 'progress.md')
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/task_plan.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/findings.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/progress.md'
)
ORDER BY time_created DESC
LIMIT 1
ORDER BY time_created DESC, id DESC
""",
params,
(sid,),
)
row = cur.fetchone()
if row:
update_sid = sid
update_time = row[0]
update_idx = idx
# Iterate lazily: write parts carry whole file bodies, and fetchall
# would materialize every planning write of the session before the
# first validated row ends the loop.
for candidate_time, data_str in cur:
data = json_loads(data_str)
if not isinstance(data, dict):
continue
state = data.get('state')
input_ = state.get('input') if isinstance(state, dict) else None
file_path = input_.get('filePath') if isinstance(input_, dict) else None
if planning_file_from_path(file_path):
update_sid = sid
update_time = candidate_time
update_idx = idx
break
if update_sid:
break
if not update_sid:
@@ -685,12 +696,17 @@ def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
"""Return a planning filename only when it is the path's exact basename.
A suffix check treats lookalikes such as ``draft_task_plan.md`` as real
planning updates and can anchor catchup at unrelated transcript content.
Normalize separators so the same boundary rule works for Unix and Windows
session records.
"""
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
return basename if basename in PLANNING_FILES else None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
+290 -16
View File
@@ -1,27 +1,269 @@
# planning-with-files: set or display the active plan pointer (PowerShell).
# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[string]$PlanId = ""
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$PlanRoot = Join-Path (Get-Location) ".planning"
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
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)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
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.
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
(Test-WithinRoot $ActiveFile)
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
if (Test-Path $ActiveFile) {
$current = (Get-Content $ActiveFile -Raw -Encoding UTF8).Trim()
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ($current -ne "" -and (Test-Path $planDir)) {
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} elseif ($current -ne "") {
Write-Output "Active plan pointer: $current (directory not found - stale pointer)"
} else {
Write-Output "No active plan set."
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
@@ -29,21 +271,53 @@ if ($PlanId -eq "") {
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path $PlanDir)) {
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
if (-not (Test-Path $PlanRoot)) {
New-Item -ItemType Directory -Path $PlanRoot -Force | Out-Null
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($ActiveFile, $PlanId, $utf8NoBom)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file lives beside the pointer, keeping replacement on the same filesystem.
$tempFile = Join-Path $PlanRoot ('.active_plan.' + [guid]::NewGuid().ToString('N') + '.tmp')
$createdTemp = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$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)
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
exit 1
} finally {
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
+351 -38
View File
@@ -1,50 +1,363 @@
#!/bin/sh
# planning-with-files: set or display the active plan pointer.
#
# Usage:
# set-active-plan.sh <plan_id> — pin .planning/.active_plan to plan_id
# set-active-plan.sh — print the current active plan (if any)
#
# The active plan is stored in .planning/.active_plan and is read by
# resolve-plan-dir.sh when no $PLAN_ID env var is set.
set -e
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|--verify-root|PLAN_ID]
# Operates on the current project; listing never binds a host or injects data.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
PWF_ROOT_PIN=""
# No args → show current active plan
if [ "${1:-}" = "" ]; then
if [ -f "${ACTIVE_FILE}" ]; then
plan_id="$(tr -d '\r\n' < "${ACTIVE_FILE}")"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ]; then
echo "Active plan: ${plan_id}"
echo "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
echo "Active plan pointer: ${plan_id} (directory not found — stale pointer)"
else
echo "No active plan set."
fi
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Prints the canonical absolute path on success; prints nothing and returns 1
# on a full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
canonicalize() {
target="$1"
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
fi
return 1
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
echo "No active plan set."
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
cand_real="$(canonicalize "${check_target}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""
}
{
line = $0
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && primary == "" && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
primary = line
}
}
END {
finish()
printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && [ -r "${_plan_file}" ] || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.'
fi
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list|--verify-root|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--verify-root checks the planning root and pointer without listing or selecting.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
echo "Error: plan directory not found: ${PLAN_DIR}" >&2
echo "Run: init-session.sh \"${PLAN_ID}\" to create it, or check .planning/ for available plans." >&2
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
printf "%s\n" "${PLAN_ID}" > "${ACTIVE_FILE}"
echo "Active plan set to: ${PLAN_ID}"
echo "Path: ${PLAN_DIR}"
echo ""
echo "To pin this terminal session only:"
echo " export PLAN_ID=${PLAN_ID}"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
+7 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.2"
version: "3.19.0"
---
@@ -212,6 +212,12 @@ Helper scripts for automation:
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history
### List saved plans
To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
@@ -10,7 +10,8 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall -> allow stop)
# When all hold, emits a single-line block-decision JSON on stdout and exits 0.
# Otherwise advisory output and exit 0. Without -Gate, byte-equivalent to v2.43.
# Otherwise reports incomplete plans and exits 0; completed plans stay silent
# with -Gate, including legacy plans without .mode. Explicit reports are unchanged.
#
# Stdin: read only when input is redirected ([Console]::IsInputRedirected), so an
# interactive console never blocks. Hook-piped JSON is EOF-terminated.
@@ -85,9 +86,10 @@ if ($TOTAL -eq 0) {
exit 0
}
# advisory_report: the v2.43 status echo.
# Keep explicit reports, but omit routine success from automatic gate checks.
function Write-AdvisoryReport {
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
if ($Gate) { return }
Write-Host ('[planning-with-files] ALL PHASES COMPLETE (' + $COMPLETE + '/' + $TOTAL + '). If the user has additional work, add new phases to task_plan.md before starting.')
} else {
Write-Host ('[planning-with-files] Task in progress (' + $COMPLETE + '/' + $TOTAL + ' phases complete). Update progress.md before stopping.')
@@ -21,8 +21,9 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall → allow stop)
# When all hold, it emits a single-line block-decision JSON on stdout and
# exits 0. Otherwise it falls back to advisory output and exits 0.
# Without --gate, or in non-gated mode, behavior is byte-equivalent to v2.43.
# exits 0. Otherwise it reports incomplete plans and exits 0; completed
# plans stay silent in --gate mode, including legacy plans without .mode.
# Without --gate, the explicit advisory report is unchanged.
#
# Stdin handling: the Claude Code Stop hook pipes a JSON payload on stdin. To
# avoid hanging when nothing is piped, stdin is read ONLY when fd 0 is not a
@@ -119,9 +120,11 @@ if [ "$TOTAL" -eq 0 ]; then
exit 0
fi
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
# Explicit status reports retain completion text. Automatic gate checks have
# nothing to report on success; keep evaluating all gate guards before here.
advisory_report() {
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
[ "$GATE" -eq 1 ] && return 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete). Update progress.md before stopping."
@@ -1,5 +1,6 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
# .\init-session.ps1 -PlanDir # isolated plan with generated slug
# .\init-session.ps1 -Autonomous # v3 autonomous mode (opt-in)
# .\init-session.ps1 -Gated # v3 gated mode (opt-in, implies autonomous)
# Templates: default, analytics
@@ -12,6 +13,7 @@
param(
[string]$ProjectName = "project",
[string]$Template = "default",
[switch]$PlanDir,
[switch]$Autonomous,
[switch]$Gated
)
@@ -38,7 +40,45 @@ function Get-Nonce {
($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
function Get-PlanSlug([string]$Name) {
# -creplace: the case-insensitive -replace lets letters that .NET folds to
# ASCII (a dotted capital I, the Kelvin sign) survive into the plan id.
$slug = $Name.ToLowerInvariant() -creplace '[^a-z0-9]', '-'
$slug = $slug -creplace '-{2,}', '-'
$slug = $slug.Trim('-')
if ($slug.Length -gt 40) {
$slug = $slug.Substring(0, 40).TrimEnd('-')
}
# The resolvers and the selector only accept ASCII plan ids.
if ($slug -cnotmatch '^[a-z0-9-]*$') {
return ""
}
return $slug
}
function Get-ShortId {
return ([Guid]::NewGuid().ToString('N')).Substring(0, 8)
}
function Get-InheritedMode([string]$CurrentMode) {
$RootModePath = Join-Path (Get-Location).Path ".mode"
if (-not (Test-Path -LiteralPath $RootModePath)) {
return $CurrentMode
}
if ($CurrentMode -eq "gated") {
return $CurrentMode
}
$RootMode = Get-Content -LiteralPath $RootModePath -Raw -ErrorAction SilentlyContinue
# Case-sensitive like inherit_root_mode in init-session.sh and the injector.
if ($RootMode -cmatch 'gate') {
return "gated"
}
if ($RootMode -cmatch 'autonomous') {
return "autonomous"
}
return $CurrentMode
}
# Validate template
if ($Template -ne "default" -and $Template -ne "analytics") {
@@ -46,11 +86,98 @@ if ($Template -ne "default" -and $Template -ne "analytics") {
$Template = "default"
}
# Match init-session.sh: zero args (or an empty name) preserve legacy root
# mode. A positional project name or -PlanDir creates an isolated
# .planning/<date>-<slug>/ plan.
$NamedPlan = $PSBoundParameters.ContainsKey("ProjectName") -and -not [string]::IsNullOrEmpty($ProjectName)
$UsePlanDir = $PlanDir -or $NamedPlan
if ($UsePlanDir) {
$PlanningRoot = Join-Path (Get-Location).Path ".planning"
# Match init-session.sh: set-active-plan.ps1 owns every write to the
# shared pointer, so a named plan cannot be created without it.
$PlanSelector = Join-Path $ScriptDir "set-active-plan.ps1"
if (-not (Test-Path -LiteralPath $PlanSelector -PathType Leaf)) {
Write-Error "Error: set-active-plan.ps1 is required to create a named plan safely."
exit 1
}
New-Item -ItemType Directory -Path $PlanningRoot -Force | Out-Null
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. A
# script that returns without exit leaves $LASTEXITCODE alone, so reset
# it first and treat a thrown error as a failure too.
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) {
Write-Error "Error: the planning directory or the active plan pointer is outside the project or cannot be verified."
exit 1
}
if ($NamedPlan) {
$Slug = Get-PlanSlug $ProjectName
} else {
$Slug = ""
$ProjectName = "untitled"
}
if ([string]::IsNullOrEmpty($Slug)) {
$Slug = "untitled-$(Get-ShortId)"
}
$BaseId = "$DATE-$Slug"
$PlanId = $BaseId
$Counter = 2
while (Test-Path -LiteralPath (Join-Path $PlanningRoot $PlanId)) {
$PlanId = "$BaseId-$Counter"
$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
}
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
}
$TaskPlanPath = Join-Path $TargetDir "task_plan.md"
$FindingsPath = Join-Path $TargetDir "findings.md"
$ProgressPath = Join-Path $TargetDir "progress.md"
if ($UsePlanDir) {
$TaskPlanDisplay = $TaskPlanPath
$FindingsDisplay = $FindingsPath
$ProgressDisplay = $ProgressPath
} else {
$TaskPlanDisplay = "task_plan.md"
$FindingsDisplay = "findings.md"
$ProgressDisplay = "progress.md"
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item $AnalyticsPlan "task_plan.md"
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
} else {
@"
# Task Plan: [Brief Description]
@@ -99,18 +226,18 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
}
Write-Host "Created task_plan.md"
Write-Host "Created $TaskPlanDisplay"
} else {
Write-Host "task_plan.md already exists, skipping"
Write-Host "$TaskPlanDisplay already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item $AnalyticsFindings "findings.md"
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
} else {
@"
# Findings & Decisions
@@ -131,15 +258,15 @@ if (-not (Test-Path "findings.md")) {
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
}
Write-Host "Created findings.md"
Write-Host "Created $FindingsDisplay"
} else {
Write-Host "findings.md already exists, skipping"
Write-Host "$FindingsDisplay already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
if (-not (Test-Path -LiteralPath $ProgressPath)) {
if ($Template -eq "analytics") {
@"
# Progress Log
@@ -160,7 +287,7 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
} else {
@"
# Progress Log
@@ -181,23 +308,28 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
}
Write-Host "Created progress.md"
Write-Host "Created $ProgressDisplay"
} else {
Write-Host "progress.md already exists, skipping"
Write-Host "$ProgressDisplay already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
if ($UsePlanDir) {
Write-Host "Active plan recorded: $(Join-Path $PlanningRoot '.active_plan')"
Write-Host "Pin this terminal to the plan for parallel sessions:"
Write-Host " `$env:PLAN_ID='$PlanId'"
} else {
Write-Host "Files: task_plan.md, findings.md, progress.md"
}
# v3 opt-in mode side effects. No-op when -Autonomous/-Gated were not passed, so
# the default path stays byte-equivalent to v2.43.0. PS1 init writes in CWD, so
# dotfiles live in CWD and attest-plan.ps1 falls back to the legacy
# .plan-attestation at the project root.
# the default path stays byte-equivalent to v2.43.0. Dotfiles live beside the
# selected plan; root mode therefore retains the legacy project-root behavior.
if ($Mode -ne "") {
$PlanDirPwf = (Get-Location).Path
$PlanDirPwf = $TargetDir
# (a) reset gate block counter, drop stale gate ledger.
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii
@@ -216,13 +348,42 @@ if ($Mode -ne "") {
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
$PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
if ((Test-Path -LiteralPath $AttestPs1) -and (Test-Path -LiteralPath $PlanFilePwf)) {
if (Test-Path -LiteralPath $PlanFilePwf) {
$HadPlanId = Test-Path Env:PLAN_ID
$PreviousPlanId = $env:PLAN_ID
try {
& $AttestPs1 *> $null
if ($UsePlanDir) {
$env:PLAN_ID = $PlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
$IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
if ($IsWindowsHost) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
}
} else {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
}
}
} catch {
# attestation failure must not abort init; the mode marker still stands.
} finally {
if ($HadPlanId) {
$env:PLAN_ID = $PreviousPlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
}
}
@@ -83,7 +83,8 @@ done
DATE=$(date +%Y-%m-%d)
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# CDPATH must not redirect the cd that locates the sibling scripts.
SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
TEMPLATE_DIR="$SKILL_ROOT/templates"
@@ -382,6 +383,20 @@ if [ "$SLUG_MODE" -eq 1 ]; then
BASE_ID="${DATE}-${SLUG}"
PLAN_ID="$BASE_ID"
PLAN_ROOT="${PWD}/.planning"
PLAN_SELECTOR="${SCRIPT_DIR}/set-active-plan.sh"
if [ ! -f "${PLAN_SELECTOR}" ]; then
echo "Error: set-active-plan.sh is required to create a named plan safely." >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. The
# selector's check is constant time; --list would parse every plan.
if ! sh "${PLAN_SELECTOR}" --verify-root; then
exit 1
fi
counter=2
while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
PLAN_ID="${BASE_ID}-${counter}"
@@ -393,7 +408,13 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
# Reuse the selector's contained, atomic pointer replacement. Direct shell
# redirection would truncate a pre-existing hardlink and could overwrite a
# different file that shares the same inode.
if ! sh "${PLAN_SELECTOR}" "${PLAN_ID}" >/dev/null; then
echo "Error: could not safely update ${PLAN_ROOT}/.active_plan." >&2
exit 1
fi
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
@@ -407,9 +407,6 @@ def get_session_candidates(
return 'claude', []
PLANNING_LIKE_SQL = ('%task_plan.md', '%findings.md', '%progress.md')
def get_opencode_db_path() -> Optional[Path]:
"""Resolve OpenCode SQLite path. Same on all OS per xdg-basedir."""
xdg = os.environ.get('XDG_DATA_HOME')
@@ -576,28 +573,42 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
update_time = None
update_idx = -1
for idx, (sid, _) in enumerate(previous_sessions):
params = (sid,) + PLANNING_LIKE_SQL
cur.execute(
"""
SELECT time_created FROM part
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
IN ('task_plan.md', 'findings.md', 'progress.md')
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/task_plan.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/findings.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/progress.md'
)
ORDER BY time_created DESC
LIMIT 1
ORDER BY time_created DESC, id DESC
""",
params,
(sid,),
)
row = cur.fetchone()
if row:
update_sid = sid
update_time = row[0]
update_idx = idx
# Iterate lazily: write parts carry whole file bodies, and fetchall
# would materialize every planning write of the session before the
# first validated row ends the loop.
for candidate_time, data_str in cur:
data = json_loads(data_str)
if not isinstance(data, dict):
continue
state = data.get('state')
input_ = state.get('input') if isinstance(state, dict) else None
file_path = input_.get('filePath') if isinstance(input_, dict) else None
if planning_file_from_path(file_path):
update_sid = sid
update_time = candidate_time
update_idx = idx
break
if update_sid:
break
if not update_sid:
@@ -685,12 +696,17 @@ def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
"""Return a planning filename only when it is the path's exact basename.
A suffix check treats lookalikes such as ``draft_task_plan.md`` as real
planning updates and can anchor catchup at unrelated transcript content.
Normalize separators so the same boundary rule works for Unix and Windows
session records.
"""
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
return basename if basename in PLANNING_FILES else None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
+290 -16
View File
@@ -1,27 +1,269 @@
# planning-with-files: set or display the active plan pointer (PowerShell).
# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[string]$PlanId = ""
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$PlanRoot = Join-Path (Get-Location) ".planning"
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
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)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
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.
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
(Test-WithinRoot $ActiveFile)
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
if (Test-Path $ActiveFile) {
$current = (Get-Content $ActiveFile -Raw -Encoding UTF8).Trim()
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ($current -ne "" -and (Test-Path $planDir)) {
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} elseif ($current -ne "") {
Write-Output "Active plan pointer: $current (directory not found - stale pointer)"
} else {
Write-Output "No active plan set."
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
@@ -29,21 +271,53 @@ if ($PlanId -eq "") {
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path $PlanDir)) {
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
if (-not (Test-Path $PlanRoot)) {
New-Item -ItemType Directory -Path $PlanRoot -Force | Out-Null
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($ActiveFile, $PlanId, $utf8NoBom)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file lives beside the pointer, keeping replacement on the same filesystem.
$tempFile = Join-Path $PlanRoot ('.active_plan.' + [guid]::NewGuid().ToString('N') + '.tmp')
$createdTemp = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$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)
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
exit 1
} finally {
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
+351 -38
View File
@@ -1,50 +1,363 @@
#!/bin/sh
# planning-with-files: set or display the active plan pointer.
#
# Usage:
# set-active-plan.sh <plan_id> — pin .planning/.active_plan to plan_id
# set-active-plan.sh — print the current active plan (if any)
#
# The active plan is stored in .planning/.active_plan and is read by
# resolve-plan-dir.sh when no $PLAN_ID env var is set.
set -e
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|--verify-root|PLAN_ID]
# Operates on the current project; listing never binds a host or injects data.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
PWF_ROOT_PIN=""
# No args → show current active plan
if [ "${1:-}" = "" ]; then
if [ -f "${ACTIVE_FILE}" ]; then
plan_id="$(tr -d '\r\n' < "${ACTIVE_FILE}")"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ]; then
echo "Active plan: ${plan_id}"
echo "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
echo "Active plan pointer: ${plan_id} (directory not found — stale pointer)"
else
echo "No active plan set."
fi
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Prints the canonical absolute path on success; prints nothing and returns 1
# on a full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
canonicalize() {
target="$1"
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
fi
return 1
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
echo "No active plan set."
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
cand_real="$(canonicalize "${check_target}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""
}
{
line = $0
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && primary == "" && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
primary = line
}
}
END {
finish()
printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && [ -r "${_plan_file}" ] || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.'
fi
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list|--verify-root|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--verify-root checks the planning root and pointer without listing or selecting.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
echo "Error: plan directory not found: ${PLAN_DIR}" >&2
echo "Run: init-session.sh \"${PLAN_ID}\" to create it, or check .planning/ for available plans." >&2
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
printf "%s\n" "${PLAN_ID}" > "${ACTIVE_FILE}"
echo "Active plan set to: ${PLAN_ID}"
echo "Path: ${PLAN_DIR}"
echo ""
echo "To pin this terminal session only:"
echo " export PLAN_ID=${PLAN_ID}"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
+7 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.17.2"
version: "3.19.0"
---
# Planning with Files
@@ -205,6 +205,12 @@ Helper scripts for automation:
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history
### List saved plans
To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
## Advanced Topics
- **Manus Principles:** See [references.md](./references.md)
@@ -10,7 +10,8 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall -> allow stop)
# When all hold, emits a single-line block-decision JSON on stdout and exits 0.
# Otherwise advisory output and exit 0. Without -Gate, byte-equivalent to v2.43.
# Otherwise reports incomplete plans and exits 0; completed plans stay silent
# with -Gate, including legacy plans without .mode. Explicit reports are unchanged.
#
# Stdin: read only when input is redirected ([Console]::IsInputRedirected), so an
# interactive console never blocks. Hook-piped JSON is EOF-terminated.
@@ -85,9 +86,10 @@ if ($TOTAL -eq 0) {
exit 0
}
# advisory_report: the v2.43 status echo.
# Keep explicit reports, but omit routine success from automatic gate checks.
function Write-AdvisoryReport {
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
if ($Gate) { return }
Write-Host ('[planning-with-files] ALL PHASES COMPLETE (' + $COMPLETE + '/' + $TOTAL + '). If the user has additional work, add new phases to task_plan.md before starting.')
} else {
Write-Host ('[planning-with-files] Task in progress (' + $COMPLETE + '/' + $TOTAL + ' phases complete). Update progress.md before stopping.')
@@ -21,8 +21,9 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall → allow stop)
# When all hold, it emits a single-line block-decision JSON on stdout and
# exits 0. Otherwise it falls back to advisory output and exits 0.
# Without --gate, or in non-gated mode, behavior is byte-equivalent to v2.43.
# exits 0. Otherwise it reports incomplete plans and exits 0; completed
# plans stay silent in --gate mode, including legacy plans without .mode.
# Without --gate, the explicit advisory report is unchanged.
#
# Stdin handling: the Claude Code Stop hook pipes a JSON payload on stdin. To
# avoid hanging when nothing is piped, stdin is read ONLY when fd 0 is not a
@@ -119,9 +120,11 @@ if [ "$TOTAL" -eq 0 ]; then
exit 0
fi
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
# Explicit status reports retain completion text. Automatic gate checks have
# nothing to report on success; keep evaluating all gate guards before here.
advisory_report() {
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
[ "$GATE" -eq 1 ] && return 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete). Update progress.md before stopping."
@@ -1,5 +1,6 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
# .\init-session.ps1 -PlanDir # isolated plan with generated slug
# .\init-session.ps1 -Autonomous # v3 autonomous mode (opt-in)
# .\init-session.ps1 -Gated # v3 gated mode (opt-in, implies autonomous)
# Templates: default, analytics
@@ -12,6 +13,7 @@
param(
[string]$ProjectName = "project",
[string]$Template = "default",
[switch]$PlanDir,
[switch]$Autonomous,
[switch]$Gated
)
@@ -38,7 +40,45 @@ function Get-Nonce {
($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
function Get-PlanSlug([string]$Name) {
# -creplace: the case-insensitive -replace lets letters that .NET folds to
# ASCII (a dotted capital I, the Kelvin sign) survive into the plan id.
$slug = $Name.ToLowerInvariant() -creplace '[^a-z0-9]', '-'
$slug = $slug -creplace '-{2,}', '-'
$slug = $slug.Trim('-')
if ($slug.Length -gt 40) {
$slug = $slug.Substring(0, 40).TrimEnd('-')
}
# The resolvers and the selector only accept ASCII plan ids.
if ($slug -cnotmatch '^[a-z0-9-]*$') {
return ""
}
return $slug
}
function Get-ShortId {
return ([Guid]::NewGuid().ToString('N')).Substring(0, 8)
}
function Get-InheritedMode([string]$CurrentMode) {
$RootModePath = Join-Path (Get-Location).Path ".mode"
if (-not (Test-Path -LiteralPath $RootModePath)) {
return $CurrentMode
}
if ($CurrentMode -eq "gated") {
return $CurrentMode
}
$RootMode = Get-Content -LiteralPath $RootModePath -Raw -ErrorAction SilentlyContinue
# Case-sensitive like inherit_root_mode in init-session.sh and the injector.
if ($RootMode -cmatch 'gate') {
return "gated"
}
if ($RootMode -cmatch 'autonomous') {
return "autonomous"
}
return $CurrentMode
}
# Validate template
if ($Template -ne "default" -and $Template -ne "analytics") {
@@ -46,11 +86,98 @@ if ($Template -ne "default" -and $Template -ne "analytics") {
$Template = "default"
}
# Match init-session.sh: zero args (or an empty name) preserve legacy root
# mode. A positional project name or -PlanDir creates an isolated
# .planning/<date>-<slug>/ plan.
$NamedPlan = $PSBoundParameters.ContainsKey("ProjectName") -and -not [string]::IsNullOrEmpty($ProjectName)
$UsePlanDir = $PlanDir -or $NamedPlan
if ($UsePlanDir) {
$PlanningRoot = Join-Path (Get-Location).Path ".planning"
# Match init-session.sh: set-active-plan.ps1 owns every write to the
# shared pointer, so a named plan cannot be created without it.
$PlanSelector = Join-Path $ScriptDir "set-active-plan.ps1"
if (-not (Test-Path -LiteralPath $PlanSelector -PathType Leaf)) {
Write-Error "Error: set-active-plan.ps1 is required to create a named plan safely."
exit 1
}
New-Item -ItemType Directory -Path $PlanningRoot -Force | Out-Null
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. A
# script that returns without exit leaves $LASTEXITCODE alone, so reset
# it first and treat a thrown error as a failure too.
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) {
Write-Error "Error: the planning directory or the active plan pointer is outside the project or cannot be verified."
exit 1
}
if ($NamedPlan) {
$Slug = Get-PlanSlug $ProjectName
} else {
$Slug = ""
$ProjectName = "untitled"
}
if ([string]::IsNullOrEmpty($Slug)) {
$Slug = "untitled-$(Get-ShortId)"
}
$BaseId = "$DATE-$Slug"
$PlanId = $BaseId
$Counter = 2
while (Test-Path -LiteralPath (Join-Path $PlanningRoot $PlanId)) {
$PlanId = "$BaseId-$Counter"
$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
}
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
}
$TaskPlanPath = Join-Path $TargetDir "task_plan.md"
$FindingsPath = Join-Path $TargetDir "findings.md"
$ProgressPath = Join-Path $TargetDir "progress.md"
if ($UsePlanDir) {
$TaskPlanDisplay = $TaskPlanPath
$FindingsDisplay = $FindingsPath
$ProgressDisplay = $ProgressPath
} else {
$TaskPlanDisplay = "task_plan.md"
$FindingsDisplay = "findings.md"
$ProgressDisplay = "progress.md"
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item $AnalyticsPlan "task_plan.md"
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
} else {
@"
# Task Plan: [Brief Description]
@@ -99,18 +226,18 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
}
Write-Host "Created task_plan.md"
Write-Host "Created $TaskPlanDisplay"
} else {
Write-Host "task_plan.md already exists, skipping"
Write-Host "$TaskPlanDisplay already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item $AnalyticsFindings "findings.md"
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
} else {
@"
# Findings & Decisions
@@ -131,15 +258,15 @@ if (-not (Test-Path "findings.md")) {
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
}
Write-Host "Created findings.md"
Write-Host "Created $FindingsDisplay"
} else {
Write-Host "findings.md already exists, skipping"
Write-Host "$FindingsDisplay already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
if (-not (Test-Path -LiteralPath $ProgressPath)) {
if ($Template -eq "analytics") {
@"
# Progress Log
@@ -160,7 +287,7 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
} else {
@"
# Progress Log
@@ -181,23 +308,28 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
}
Write-Host "Created progress.md"
Write-Host "Created $ProgressDisplay"
} else {
Write-Host "progress.md already exists, skipping"
Write-Host "$ProgressDisplay already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
if ($UsePlanDir) {
Write-Host "Active plan recorded: $(Join-Path $PlanningRoot '.active_plan')"
Write-Host "Pin this terminal to the plan for parallel sessions:"
Write-Host " `$env:PLAN_ID='$PlanId'"
} else {
Write-Host "Files: task_plan.md, findings.md, progress.md"
}
# v3 opt-in mode side effects. No-op when -Autonomous/-Gated were not passed, so
# the default path stays byte-equivalent to v2.43.0. PS1 init writes in CWD, so
# dotfiles live in CWD and attest-plan.ps1 falls back to the legacy
# .plan-attestation at the project root.
# the default path stays byte-equivalent to v2.43.0. Dotfiles live beside the
# selected plan; root mode therefore retains the legacy project-root behavior.
if ($Mode -ne "") {
$PlanDirPwf = (Get-Location).Path
$PlanDirPwf = $TargetDir
# (a) reset gate block counter, drop stale gate ledger.
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii
@@ -216,13 +348,42 @@ if ($Mode -ne "") {
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
$PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
if ((Test-Path -LiteralPath $AttestPs1) -and (Test-Path -LiteralPath $PlanFilePwf)) {
if (Test-Path -LiteralPath $PlanFilePwf) {
$HadPlanId = Test-Path Env:PLAN_ID
$PreviousPlanId = $env:PLAN_ID
try {
& $AttestPs1 *> $null
if ($UsePlanDir) {
$env:PLAN_ID = $PlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
$IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
if ($IsWindowsHost) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
}
} else {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
}
}
} catch {
# attestation failure must not abort init; the mode marker still stands.
} finally {
if ($HadPlanId) {
$env:PLAN_ID = $PreviousPlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
}
}
@@ -83,7 +83,8 @@ done
DATE=$(date +%Y-%m-%d)
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# CDPATH must not redirect the cd that locates the sibling scripts.
SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
TEMPLATE_DIR="$SKILL_ROOT/templates"
@@ -382,6 +383,20 @@ if [ "$SLUG_MODE" -eq 1 ]; then
BASE_ID="${DATE}-${SLUG}"
PLAN_ID="$BASE_ID"
PLAN_ROOT="${PWD}/.planning"
PLAN_SELECTOR="${SCRIPT_DIR}/set-active-plan.sh"
if [ ! -f "${PLAN_SELECTOR}" ]; then
echo "Error: set-active-plan.sh is required to create a named plan safely." >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. The
# selector's check is constant time; --list would parse every plan.
if ! sh "${PLAN_SELECTOR}" --verify-root; then
exit 1
fi
counter=2
while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
PLAN_ID="${BASE_ID}-${counter}"
@@ -393,7 +408,13 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
# Reuse the selector's contained, atomic pointer replacement. Direct shell
# redirection would truncate a pre-existing hardlink and could overwrite a
# different file that shares the same inode.
if ! sh "${PLAN_SELECTOR}" "${PLAN_ID}" >/dev/null; then
echo "Error: could not safely update ${PLAN_ROOT}/.active_plan." >&2
exit 1
fi
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
@@ -407,9 +407,6 @@ def get_session_candidates(
return 'claude', []
PLANNING_LIKE_SQL = ('%task_plan.md', '%findings.md', '%progress.md')
def get_opencode_db_path() -> Optional[Path]:
"""Resolve OpenCode SQLite path. Same on all OS per xdg-basedir."""
xdg = os.environ.get('XDG_DATA_HOME')
@@ -576,28 +573,42 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
update_time = None
update_idx = -1
for idx, (sid, _) in enumerate(previous_sessions):
params = (sid,) + PLANNING_LIKE_SQL
cur.execute(
"""
SELECT time_created FROM part
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
IN ('task_plan.md', 'findings.md', 'progress.md')
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/task_plan.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/findings.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/progress.md'
)
ORDER BY time_created DESC
LIMIT 1
ORDER BY time_created DESC, id DESC
""",
params,
(sid,),
)
row = cur.fetchone()
if row:
update_sid = sid
update_time = row[0]
update_idx = idx
# Iterate lazily: write parts carry whole file bodies, and fetchall
# would materialize every planning write of the session before the
# first validated row ends the loop.
for candidate_time, data_str in cur:
data = json_loads(data_str)
if not isinstance(data, dict):
continue
state = data.get('state')
input_ = state.get('input') if isinstance(state, dict) else None
file_path = input_.get('filePath') if isinstance(input_, dict) else None
if planning_file_from_path(file_path):
update_sid = sid
update_time = candidate_time
update_idx = idx
break
if update_sid:
break
if not update_sid:
@@ -685,12 +696,17 @@ def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
"""Return a planning filename only when it is the path's exact basename.
A suffix check treats lookalikes such as ``draft_task_plan.md`` as real
planning updates and can anchor catchup at unrelated transcript content.
Normalize separators so the same boundary rule works for Unix and Windows
session records.
"""
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
return basename if basename in PLANNING_FILES else None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
+290 -16
View File
@@ -1,27 +1,269 @@
# planning-with-files: set or display the active plan pointer (PowerShell).
# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[string]$PlanId = ""
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$PlanRoot = Join-Path (Get-Location) ".planning"
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
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)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
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.
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
(Test-WithinRoot $ActiveFile)
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
if (Test-Path $ActiveFile) {
$current = (Get-Content $ActiveFile -Raw -Encoding UTF8).Trim()
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ($current -ne "" -and (Test-Path $planDir)) {
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} elseif ($current -ne "") {
Write-Output "Active plan pointer: $current (directory not found - stale pointer)"
} else {
Write-Output "No active plan set."
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
@@ -29,21 +271,53 @@ if ($PlanId -eq "") {
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path $PlanDir)) {
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
if (-not (Test-Path $PlanRoot)) {
New-Item -ItemType Directory -Path $PlanRoot -Force | Out-Null
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($ActiveFile, $PlanId, $utf8NoBom)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file lives beside the pointer, keeping replacement on the same filesystem.
$tempFile = Join-Path $PlanRoot ('.active_plan.' + [guid]::NewGuid().ToString('N') + '.tmp')
$createdTemp = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$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)
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
exit 1
} finally {
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
+351 -38
View File
@@ -1,50 +1,363 @@
#!/bin/sh
# planning-with-files: set or display the active plan pointer.
#
# Usage:
# set-active-plan.sh <plan_id> — pin .planning/.active_plan to plan_id
# set-active-plan.sh — print the current active plan (if any)
#
# The active plan is stored in .planning/.active_plan and is read by
# resolve-plan-dir.sh when no $PLAN_ID env var is set.
set -e
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|--verify-root|PLAN_ID]
# Operates on the current project; listing never binds a host or injects data.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
PWF_ROOT_PIN=""
# No args → show current active plan
if [ "${1:-}" = "" ]; then
if [ -f "${ACTIVE_FILE}" ]; then
plan_id="$(tr -d '\r\n' < "${ACTIVE_FILE}")"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ]; then
echo "Active plan: ${plan_id}"
echo "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
echo "Active plan pointer: ${plan_id} (directory not found — stale pointer)"
else
echo "No active plan set."
fi
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Prints the canonical absolute path on success; prints nothing and returns 1
# on a full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
canonicalize() {
target="$1"
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
fi
return 1
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
echo "No active plan set."
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
cand_real="$(canonicalize "${check_target}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""
}
{
line = $0
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && primary == "" && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
primary = line
}
}
END {
finish()
printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && [ -r "${_plan_file}" ] || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.'
fi
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list|--verify-root|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--verify-root checks the planning root and pointer without listing or selecting.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
echo "Error: plan directory not found: ${PLAN_DIR}" >&2
echo "Run: init-session.sh \"${PLAN_ID}\" to create it, or check .planning/ for available plans." >&2
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
printf "%s\n" "${PLAN_ID}" > "${ACTIVE_FILE}"
echo "Active plan set to: ${PLAN_ID}"
echo "Path: ${PLAN_DIR}"
echo ""
echo "To pin this terminal session only:"
echo " export PLAN_ID=${PLAN_ID}"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
+1 -1
View File
@@ -18,7 +18,7 @@ CURRENT_PHASE=$(grep -m1 "^## Current Phase" "$PLAN_FILE" 2>/dev/null || grep -m
if [ -n "$CURRENT_PHASE" ]; then
PYTHON=$(command -v python3 || command -v python)
ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "[planning-with-files] Current: $CURRENT_PHASE" 2>/dev/null || echo "\"\"")
ESCAPED=$($PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "[planning-with-files] Current: $CURRENT_PHASE" 2>/dev/null || echo "\"\"")
printf '%s\n' "{\"additionalContext\":$ESCAPED}"
else
echo '{}'
+1 -1
View File
@@ -21,7 +21,7 @@ fi
PYTHON=$(command -v python3 || command -v python)
if [ -n "$PYTHON" ]; then
ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$CONTEXT" 2>/dev/null)
ESCAPED=$($PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$CONTEXT" 2>/dev/null)
if [ -n "$ESCAPED" ] && [ "$ESCAPED" != "\"\"" ]; then
printf '%s\n' "{\"systemMessage\":$ESCAPED}"
exit 0
+1 -1
View File
@@ -18,7 +18,7 @@ if [ -f "$SCRIPT_DIR/check-complete.sh" ]; then
RESULT=$(sh "$SCRIPT_DIR/check-complete.sh" 2>/dev/null || true)
if [ -n "$RESULT" ]; then
PYTHON=$(command -v python3 || command -v python)
ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$RESULT" 2>/dev/null || echo "\"\"")
ESCAPED=$($PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$RESULT" 2>/dev/null || echo "\"\"")
printf '%s\n' "{\"systemMessage\":$ESCAPED}"
exit 0
fi
+2 -2
View File
@@ -19,11 +19,11 @@ fi
PYTHON=$(command -v python3 || command -v python)
CATCHUP=""
if [ -n "$PYTHON" ] && [ -f "$SCRIPT_DIR/session-catchup.py" ]; then
CATCHUP=$($PYTHON "$SCRIPT_DIR/session-catchup.py" --no-history "$(pwd)" 2>/dev/null || true)
CATCHUP=$($PYTHON -I -X utf8 "$SCRIPT_DIR/session-catchup.py" --no-history "$(pwd)" 2>/dev/null || true)
fi
if [ -n "$CATCHUP" ]; then
ESCAPED=$($PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$CATCHUP" 2>/dev/null || echo "\"[planning-with-files] Session recovery data available. Read task_plan.md, progress.md, and findings.md.\"")
ESCAPED=$($PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" <<< "$CATCHUP" 2>/dev/null || echo "\"[planning-with-files] Session recovery data available. Read task_plan.md, progress.md, and findings.md.\"")
printf '%s\n' "{\"hookSpecificOutput\":{\"additionalContext\":$ESCAPED}}"
else
echo '{"hookSpecificOutput":{"additionalContext":"[planning-with-files] Active plan detected. Read task_plan.md, progress.md, and findings.md before proceeding."}}'
+19 -15
View File
@@ -182,32 +182,36 @@ 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/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`, checks `.planning/.active_plan`, then newest plan dir by mtime, then falls back to project root (legacy). Used internally by hooks.
- `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. OpenCode uses its read-only SQLite store.
- `scripts/attest-plan.sh` (and `.ps1`) — Lock the current `task_plan.md` content with a SHA-256 attestation (v2.37.0). Use `--show` to print the stored hash, `--clear` to remove the attestation.
### List saved plans
To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
### Parallel task workflow
When working on multiple tasks in the same repo simultaneously:
For concurrent tasks, initialize a named plan and pin each host before starting it. Set `SKILL_DIR` to the installed skill directory in each terminal and keep your current directory at the project root:
```bash
# Start task A
./scripts/init-session.sh "Backend Refactor"
# → .planning/2026-01-10-backend-refactor/task_plan.md
# Terminal A: use the exact PLAN_ID printed by initialization.
sh "$SKILL_DIR/scripts/init-session.sh" "Backend Refactor"
export PLAN_ID=2026-09-13-backend-refactor
# Start the first agent from this terminal after setting PLAN_ID.
# Start task B in a second terminal
./scripts/init-session.sh "Incident Investigation"
# → .planning/2026-01-10-incident-investigation/task_plan.md
# Switch active plan
./scripts/set-active-plan.sh 2026-01-10-backend-refactor
# Or pin a terminal to a specific plan
export PLAN_ID=2026-01-10-backend-refactor
# Terminal B: use the different PLAN_ID printed for this task.
sh "$SKILL_DIR/scripts/init-session.sh" "Incident Investigation"
export PLAN_ID=2026-09-13-incident-investigation
# Start the second agent from this terminal after setting PLAN_ID.
```
Each session reads from its own isolated plan directory.
The IDs are examples; use the IDs printed by your initialization commands. In PowerShell, set `$env:PLAN_ID` before starting the host. Setting it inside an already-running agent's tool subprocess does not change the parent host's environment. Use separate worktrees if the host cannot be pinned per task.
Use `set-active-plan` for sequential switching of the shared default pointer. Concurrent sessions need their own `PLAN_ID` even when the listing shows `[active]`.
## Advanced Topics
@@ -10,7 +10,8 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall -> allow stop)
# When all hold, emits a single-line block-decision JSON on stdout and exits 0.
# Otherwise advisory output and exit 0. Without -Gate, byte-equivalent to v2.43.
# Otherwise reports incomplete plans and exits 0; completed plans stay silent
# with -Gate, including legacy plans without .mode. Explicit reports are unchanged.
#
# Stdin: read only when input is redirected ([Console]::IsInputRedirected), so an
# interactive console never blocks. Hook-piped JSON is EOF-terminated.
@@ -85,9 +86,10 @@ if ($TOTAL -eq 0) {
exit 0
}
# advisory_report: the v2.43 status echo.
# Keep explicit reports, but omit routine success from automatic gate checks.
function Write-AdvisoryReport {
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
if ($Gate) { return }
Write-Host ('[planning-with-files] ALL PHASES COMPLETE (' + $COMPLETE + '/' + $TOTAL + '). If the user has additional work, add new phases to task_plan.md before starting.')
} else {
Write-Host ('[planning-with-files] Task in progress (' + $COMPLETE + '/' + $TOTAL + ' phases complete). Update progress.md before stopping.')
@@ -21,8 +21,9 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall → allow stop)
# When all hold, it emits a single-line block-decision JSON on stdout and
# exits 0. Otherwise it falls back to advisory output and exits 0.
# Without --gate, or in non-gated mode, behavior is byte-equivalent to v2.43.
# exits 0. Otherwise it reports incomplete plans and exits 0; completed
# plans stay silent in --gate mode, including legacy plans without .mode.
# Without --gate, the explicit advisory report is unchanged.
#
# Stdin handling: the Claude Code Stop hook pipes a JSON payload on stdin. To
# avoid hanging when nothing is piped, stdin is read ONLY when fd 0 is not a
@@ -119,9 +120,11 @@ if [ "$TOTAL" -eq 0 ]; then
exit 0
fi
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
# Explicit status reports retain completion text. Automatic gate checks have
# nothing to report on success; keep evaluating all gate guards before here.
advisory_report() {
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
[ "$GATE" -eq 1 ] && return 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete). Update progress.md before stopping."
@@ -1,5 +1,6 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
# .\init-session.ps1 -PlanDir # isolated plan with generated slug
# .\init-session.ps1 -Autonomous # v3 autonomous mode (opt-in)
# .\init-session.ps1 -Gated # v3 gated mode (opt-in, implies autonomous)
# Templates: default, analytics
@@ -12,6 +13,7 @@
param(
[string]$ProjectName = "project",
[string]$Template = "default",
[switch]$PlanDir,
[switch]$Autonomous,
[switch]$Gated
)
@@ -38,7 +40,45 @@ function Get-Nonce {
($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
function Get-PlanSlug([string]$Name) {
# -creplace: the case-insensitive -replace lets letters that .NET folds to
# ASCII (a dotted capital I, the Kelvin sign) survive into the plan id.
$slug = $Name.ToLowerInvariant() -creplace '[^a-z0-9]', '-'
$slug = $slug -creplace '-{2,}', '-'
$slug = $slug.Trim('-')
if ($slug.Length -gt 40) {
$slug = $slug.Substring(0, 40).TrimEnd('-')
}
# The resolvers and the selector only accept ASCII plan ids.
if ($slug -cnotmatch '^[a-z0-9-]*$') {
return ""
}
return $slug
}
function Get-ShortId {
return ([Guid]::NewGuid().ToString('N')).Substring(0, 8)
}
function Get-InheritedMode([string]$CurrentMode) {
$RootModePath = Join-Path (Get-Location).Path ".mode"
if (-not (Test-Path -LiteralPath $RootModePath)) {
return $CurrentMode
}
if ($CurrentMode -eq "gated") {
return $CurrentMode
}
$RootMode = Get-Content -LiteralPath $RootModePath -Raw -ErrorAction SilentlyContinue
# Case-sensitive like inherit_root_mode in init-session.sh and the injector.
if ($RootMode -cmatch 'gate') {
return "gated"
}
if ($RootMode -cmatch 'autonomous') {
return "autonomous"
}
return $CurrentMode
}
# Validate template
if ($Template -ne "default" -and $Template -ne "analytics") {
@@ -46,11 +86,98 @@ if ($Template -ne "default" -and $Template -ne "analytics") {
$Template = "default"
}
# Match init-session.sh: zero args (or an empty name) preserve legacy root
# mode. A positional project name or -PlanDir creates an isolated
# .planning/<date>-<slug>/ plan.
$NamedPlan = $PSBoundParameters.ContainsKey("ProjectName") -and -not [string]::IsNullOrEmpty($ProjectName)
$UsePlanDir = $PlanDir -or $NamedPlan
if ($UsePlanDir) {
$PlanningRoot = Join-Path (Get-Location).Path ".planning"
# Match init-session.sh: set-active-plan.ps1 owns every write to the
# shared pointer, so a named plan cannot be created without it.
$PlanSelector = Join-Path $ScriptDir "set-active-plan.ps1"
if (-not (Test-Path -LiteralPath $PlanSelector -PathType Leaf)) {
Write-Error "Error: set-active-plan.ps1 is required to create a named plan safely."
exit 1
}
New-Item -ItemType Directory -Path $PlanningRoot -Force | Out-Null
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. A
# script that returns without exit leaves $LASTEXITCODE alone, so reset
# it first and treat a thrown error as a failure too.
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) {
Write-Error "Error: the planning directory or the active plan pointer is outside the project or cannot be verified."
exit 1
}
if ($NamedPlan) {
$Slug = Get-PlanSlug $ProjectName
} else {
$Slug = ""
$ProjectName = "untitled"
}
if ([string]::IsNullOrEmpty($Slug)) {
$Slug = "untitled-$(Get-ShortId)"
}
$BaseId = "$DATE-$Slug"
$PlanId = $BaseId
$Counter = 2
while (Test-Path -LiteralPath (Join-Path $PlanningRoot $PlanId)) {
$PlanId = "$BaseId-$Counter"
$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
}
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
}
$TaskPlanPath = Join-Path $TargetDir "task_plan.md"
$FindingsPath = Join-Path $TargetDir "findings.md"
$ProgressPath = Join-Path $TargetDir "progress.md"
if ($UsePlanDir) {
$TaskPlanDisplay = $TaskPlanPath
$FindingsDisplay = $FindingsPath
$ProgressDisplay = $ProgressPath
} else {
$TaskPlanDisplay = "task_plan.md"
$FindingsDisplay = "findings.md"
$ProgressDisplay = "progress.md"
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item $AnalyticsPlan "task_plan.md"
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
} else {
@"
# Task Plan: [Brief Description]
@@ -99,18 +226,18 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
}
Write-Host "Created task_plan.md"
Write-Host "Created $TaskPlanDisplay"
} else {
Write-Host "task_plan.md already exists, skipping"
Write-Host "$TaskPlanDisplay already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item $AnalyticsFindings "findings.md"
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
} else {
@"
# Findings & Decisions
@@ -131,15 +258,15 @@ if (-not (Test-Path "findings.md")) {
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
}
Write-Host "Created findings.md"
Write-Host "Created $FindingsDisplay"
} else {
Write-Host "findings.md already exists, skipping"
Write-Host "$FindingsDisplay already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
if (-not (Test-Path -LiteralPath $ProgressPath)) {
if ($Template -eq "analytics") {
@"
# Progress Log
@@ -160,7 +287,7 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
} else {
@"
# Progress Log
@@ -181,23 +308,28 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
}
Write-Host "Created progress.md"
Write-Host "Created $ProgressDisplay"
} else {
Write-Host "progress.md already exists, skipping"
Write-Host "$ProgressDisplay already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
if ($UsePlanDir) {
Write-Host "Active plan recorded: $(Join-Path $PlanningRoot '.active_plan')"
Write-Host "Pin this terminal to the plan for parallel sessions:"
Write-Host " `$env:PLAN_ID='$PlanId'"
} else {
Write-Host "Files: task_plan.md, findings.md, progress.md"
}
# v3 opt-in mode side effects. No-op when -Autonomous/-Gated were not passed, so
# the default path stays byte-equivalent to v2.43.0. PS1 init writes in CWD, so
# dotfiles live in CWD and attest-plan.ps1 falls back to the legacy
# .plan-attestation at the project root.
# the default path stays byte-equivalent to v2.43.0. Dotfiles live beside the
# selected plan; root mode therefore retains the legacy project-root behavior.
if ($Mode -ne "") {
$PlanDirPwf = (Get-Location).Path
$PlanDirPwf = $TargetDir
# (a) reset gate block counter, drop stale gate ledger.
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii
@@ -216,13 +348,42 @@ if ($Mode -ne "") {
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
$PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
if ((Test-Path -LiteralPath $AttestPs1) -and (Test-Path -LiteralPath $PlanFilePwf)) {
if (Test-Path -LiteralPath $PlanFilePwf) {
$HadPlanId = Test-Path Env:PLAN_ID
$PreviousPlanId = $env:PLAN_ID
try {
& $AttestPs1 *> $null
if ($UsePlanDir) {
$env:PLAN_ID = $PlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
$IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
if ($IsWindowsHost) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
}
} else {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
}
}
} catch {
# attestation failure must not abort init; the mode marker still stands.
} finally {
if ($HadPlanId) {
$env:PLAN_ID = $PreviousPlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
}
}
@@ -83,7 +83,8 @@ done
DATE=$(date +%Y-%m-%d)
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# CDPATH must not redirect the cd that locates the sibling scripts.
SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
TEMPLATE_DIR="$SKILL_ROOT/templates"
@@ -382,6 +383,20 @@ if [ "$SLUG_MODE" -eq 1 ]; then
BASE_ID="${DATE}-${SLUG}"
PLAN_ID="$BASE_ID"
PLAN_ROOT="${PWD}/.planning"
PLAN_SELECTOR="${SCRIPT_DIR}/set-active-plan.sh"
if [ ! -f "${PLAN_SELECTOR}" ]; then
echo "Error: set-active-plan.sh is required to create a named plan safely." >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. The
# selector's check is constant time; --list would parse every plan.
if ! sh "${PLAN_SELECTOR}" --verify-root; then
exit 1
fi
counter=2
while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
PLAN_ID="${BASE_ID}-${counter}"
@@ -393,7 +408,13 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
# Reuse the selector's contained, atomic pointer replacement. Direct shell
# redirection would truncate a pre-existing hardlink and could overwrite a
# different file that shares the same inode.
if ! sh "${PLAN_SELECTOR}" "${PLAN_ID}" >/dev/null; then
echo "Error: could not safely update ${PLAN_ROOT}/.active_plan." >&2
exit 1
fi
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
@@ -407,9 +407,6 @@ def get_session_candidates(
return 'claude', []
PLANNING_LIKE_SQL = ('%task_plan.md', '%findings.md', '%progress.md')
def get_opencode_db_path() -> Optional[Path]:
"""Resolve OpenCode SQLite path. Same on all OS per xdg-basedir."""
xdg = os.environ.get('XDG_DATA_HOME')
@@ -576,28 +573,42 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
update_time = None
update_idx = -1
for idx, (sid, _) in enumerate(previous_sessions):
params = (sid,) + PLANNING_LIKE_SQL
cur.execute(
"""
SELECT time_created FROM part
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
IN ('task_plan.md', 'findings.md', 'progress.md')
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/task_plan.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/findings.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/progress.md'
)
ORDER BY time_created DESC
LIMIT 1
ORDER BY time_created DESC, id DESC
""",
params,
(sid,),
)
row = cur.fetchone()
if row:
update_sid = sid
update_time = row[0]
update_idx = idx
# Iterate lazily: write parts carry whole file bodies, and fetchall
# would materialize every planning write of the session before the
# first validated row ends the loop.
for candidate_time, data_str in cur:
data = json_loads(data_str)
if not isinstance(data, dict):
continue
state = data.get('state')
input_ = state.get('input') if isinstance(state, dict) else None
file_path = input_.get('filePath') if isinstance(input_, dict) else None
if planning_file_from_path(file_path):
update_sid = sid
update_time = candidate_time
update_idx = idx
break
if update_sid:
break
if not update_sid:
@@ -685,12 +696,17 @@ def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
"""Return a planning filename only when it is the path's exact basename.
A suffix check treats lookalikes such as ``draft_task_plan.md`` as real
planning updates and can anchor catchup at unrelated transcript content.
Normalize separators so the same boundary rule works for Unix and Windows
session records.
"""
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
return basename if basename in PLANNING_FILES else None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
+290 -16
View File
@@ -1,27 +1,269 @@
# planning-with-files: set or display the active plan pointer (PowerShell).
# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[string]$PlanId = ""
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$PlanRoot = Join-Path (Get-Location) ".planning"
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
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)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
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.
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
(Test-WithinRoot $ActiveFile)
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
if (Test-Path $ActiveFile) {
$current = (Get-Content $ActiveFile -Raw -Encoding UTF8).Trim()
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ($current -ne "" -and (Test-Path $planDir)) {
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} elseif ($current -ne "") {
Write-Output "Active plan pointer: $current (directory not found - stale pointer)"
} else {
Write-Output "No active plan set."
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
@@ -29,21 +271,53 @@ if ($PlanId -eq "") {
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path $PlanDir)) {
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
if (-not (Test-Path $PlanRoot)) {
New-Item -ItemType Directory -Path $PlanRoot -Force | Out-Null
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($ActiveFile, $PlanId, $utf8NoBom)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file lives beside the pointer, keeping replacement on the same filesystem.
$tempFile = Join-Path $PlanRoot ('.active_plan.' + [guid]::NewGuid().ToString('N') + '.tmp')
$createdTemp = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$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)
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
exit 1
} finally {
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
+351 -38
View File
@@ -1,50 +1,363 @@
#!/bin/sh
# planning-with-files: set or display the active plan pointer.
#
# Usage:
# set-active-plan.sh <plan_id> — pin .planning/.active_plan to plan_id
# set-active-plan.sh — print the current active plan (if any)
#
# The active plan is stored in .planning/.active_plan and is read by
# resolve-plan-dir.sh when no $PLAN_ID env var is set.
set -e
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|--verify-root|PLAN_ID]
# Operates on the current project; listing never binds a host or injects data.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
PWF_ROOT_PIN=""
# No args → show current active plan
if [ "${1:-}" = "" ]; then
if [ -f "${ACTIVE_FILE}" ]; then
plan_id="$(tr -d '\r\n' < "${ACTIVE_FILE}")"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ]; then
echo "Active plan: ${plan_id}"
echo "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
echo "Active plan pointer: ${plan_id} (directory not found — stale pointer)"
else
echo "No active plan set."
fi
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Prints the canonical absolute path on success; prints nothing and returns 1
# on a full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
canonicalize() {
target="$1"
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
fi
return 1
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
echo "No active plan set."
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
cand_real="$(canonicalize "${check_target}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""
}
{
line = $0
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && primary == "" && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
primary = line
}
}
END {
finish()
printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && [ -r "${_plan_file}" ] || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.'
fi
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list|--verify-root|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--verify-root checks the planning root and pointer without listing or selecting.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
echo "Error: plan directory not found: ${PLAN_DIR}" >&2
echo "Run: init-session.sh \"${PLAN_ID}\" to create it, or check .planning/ for available plans." >&2
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
printf "%s\n" "${PLAN_ID}" > "${ACTIVE_FILE}"
echo "Active plan set to: ${PLAN_ID}"
echo "Path: ${PLAN_DIR}"
echo ""
echo "To pin this terminal session only:"
echo " export PLAN_ID=${PLAN_ID}"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
+2 -2
View File
@@ -21,7 +21,7 @@ for _p in /usr/bin/python3 /usr/local/bin/python3 /opt/homebrew/bin/python3; do
[ -x "$_p" ] && { PYTHON="$_p"; break; }
done
[ -z "$PYTHON" ] && PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
ERROR_MSG=$(printf '%s\n' "$INPUT" | $PYTHON -c "
ERROR_MSG=$(printf '%s\n' "$INPUT" | $PYTHON -I -X utf8 -c "
import sys, json
try:
data = json.load(sys.stdin)
@@ -33,7 +33,7 @@ except:
if [ -n "$ERROR_MSG" ]; then
CONTEXT="[planning-with-files] Error detected: ${ERROR_MSG}. Log this error in task_plan.md under Errors Encountered with the attempt number and resolution."
ESCAPED=$(printf '%s\n' "$CONTEXT" | $PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
ESCAPED=$(printf '%s\n' "$CONTEXT" | $PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"ErrorOccurred\",\"additionalContext\":$ESCAPED}}"
else
echo '{}'
+1 -1
View File
@@ -31,7 +31,7 @@ for _p in /usr/bin/python3 /usr/local/bin/python3 /opt/homebrew/bin/python3; do
[ -x "$_p" ] && { PYTHON="$_p"; break; }
done
[ -z "$PYTHON" ] && PYTHON=$(command -v python3 2>/dev/null || command -v python 2>/dev/null)
ESCAPED=$(echo "$CONTEXT" | $PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
ESCAPED=$(echo "$CONTEXT" | $PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"allow\",\"additionalContext\":$ESCAPED}}"
exit 0
+2 -2
View File
@@ -21,7 +21,7 @@ if [ -f "$PLAN_FILE" ]; then
# Plan exists: keep catchup zero-history, then read the plan header.
CATCHUP=""
if [ -n "$PYTHON" ] && [ -f "$SKILL_DIR/scripts/session-catchup.py" ]; then
CATCHUP=$($PYTHON "$SKILL_DIR/scripts/session-catchup.py" --no-history "$(pwd)" 2>/dev/null | head -100)
CATCHUP=$($PYTHON -I -X utf8 "$SKILL_DIR/scripts/session-catchup.py" --no-history "$(pwd)" 2>/dev/null | head -100)
fi
if [ -n "$CATCHUP" ]; then
@@ -43,7 +43,7 @@ if [ -z "$CONTEXT" ]; then
fi
# Escape context for JSON
ESCAPED=$(echo "$CONTEXT" | $PYTHON -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
ESCAPED=$(echo "$CONTEXT" | $PYTHON -I -X utf8 -c "import sys,json; print(json.dumps(sys.stdin.read(), ensure_ascii=False))" 2>/dev/null || echo "\"\"")
printf '%s\n' "{\"hookSpecificOutput\":{\"hookEventName\":\"SessionStart\",\"additionalContext\":$ESCAPED}}"
exit 0
+4 -2
View File
@@ -29,7 +29,9 @@ jobs:
# on ubuntu so GNU-only regressions fail there too.
os: [ubuntu-latest, windows-latest, macos-latest]
runs-on: ${{ matrix.os }}
timeout-minutes: 15
# Windows runs the full suite through Git Bash and native PowerShell.
# Successful runs already approach 15 minutes; allow runner variance.
timeout-minutes: ${{ matrix.os == 'windows-latest' && 30 || 15 }}
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
@@ -45,7 +47,7 @@ jobs:
# sh.exe on windows-latest).
run: python -c "import shutil, sys; sys.exit(0 if shutil.which('sh') else 1)"
- name: Run pytest
run: python -m pytest tests/ -q
run: python -m pytest tests/ -q --durations=20
vitest:
name: vitest (Pi extension)
+9 -1
View File
@@ -2,7 +2,7 @@
name: planning-with-files
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
metadata:
version: "3.17.2"
version: "3.19.0"
hermes:
tags: [planning, long-running-tasks, context-engineering, workflow]
---
@@ -208,6 +208,14 @@ Helper scripts bundled with this Hermes skill:
The adapter plugin does not need any other script: plan resolution, injection, attestation checks, the completion gate and the `/pwf` initialization run in Python inside the plugin. The full canonical script surface (attestation helper, ledger, phase status, plan-doctor) ships with the canonical skill for hosts that dispatch shell hooks.
### List saved plans
To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
If your Hermes hub installation omits `.ps1` files, use `--list` with a POSIX shell or obtain the helper from the repository's `.hermes/skills/planning-with-files/scripts/` directory. The Hermes adapter itself does not depend on this helper.
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
@@ -27,6 +27,14 @@ from typing import List, Dict, Optional, Tuple
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def planning_file_from_path(path_value: object) -> Optional[str]:
"""Return a planning filename only when it is the path's exact basename."""
if not isinstance(path_value, str):
return None
basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
return basename if basename in PLANNING_FILES else None
def detect_ide() -> str:
"""
Detect which IDE is being used based on environment and file structure.
@@ -369,11 +377,10 @@ def scan_for_planning_update(session_file: Path) -> Tuple[int, Optional[str]]:
continue
file_path = item.get('input', {}).get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = line_num
last_update_file = pf
break
planning_file = planning_file_from_path(file_path)
if planning_file:
last_update_line = line_num
last_update_file = planning_file
except json.JSONDecodeError:
continue
except Exception:
@@ -0,0 +1,325 @@
# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
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)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
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.
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
(Test-WithinRoot $ActiveFile)
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} else {
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
}
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file lives beside the pointer, keeping replacement on the same filesystem.
$tempFile = Join-Path $PlanRoot ('.active_plan.' + [guid]::NewGuid().ToString('N') + '.tmp')
$createdTemp = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$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)
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
exit 1
} finally {
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
Write-Output "To pin this terminal session only:"
Write-Output "`$env:PLAN_ID = '$PlanId'"
@@ -0,0 +1,363 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|--verify-root|PLAN_ID]
# Operates on the current project; listing never binds a host or injects data.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
PWF_ROOT_PIN=""
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Prints the canonical absolute path on success; prints nothing and returns 1
# on a full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
canonicalize() {
target="$1"
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
fi
return 1
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
cand_real="$(canonicalize "${check_target}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""
}
{
line = $0
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && primary == "" && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
primary = line
}
}
END {
finish()
printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && [ -r "${_plan_file}" ] || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.'
fi
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list|--verify-root|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--verify-root checks the planning root and pointer without listing or selecting.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
@@ -187,6 +187,8 @@ AFTER 3 FAILURES: Escalate to User
## Scripts
Kiro keeps its plan in `.kiro/plan/`. The canonical `set-active-plan` listing helper reads named plans under `.planning/` and does not list or switch this Kiro plan.
Helper scripts (under `assets/scripts/`):
- `assets/scripts/bootstrap.sh` — Idempotent workspace bootstrap. Creates `.kiro/plan/` and `.kiro/steering/planning-context.md`.
@@ -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.17.2"
version: "3.19.0"
---
@@ -212,6 +212,12 @@ Helper scripts for automation:
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history
### List saved plans
To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
## Advanced Topics
- **Manus Principles:** See [references/reference.md](references/reference.md)
@@ -22,6 +22,14 @@ from typing import List, Dict, Optional, Tuple
PLANNING_FILES = ['task_plan.md', 'progress.md', 'findings.md']
def planning_file_from_path(path_value: object) -> Optional[str]:
"""Return a planning filename only when it is the path's exact basename."""
if not isinstance(path_value, str):
return None
basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
return basename if basename in PLANNING_FILES else None
def normalize_project_path(project_path: str) -> str:
"""Absolute, platform-native spelling of a project path.
@@ -306,10 +314,10 @@ def find_last_planning_update(messages: List[Dict]) -> Tuple[int, Optional[str]]
if tool_name in ('Write', 'Edit'):
file_path = tool_input.get('file_path', '')
for pf in PLANNING_FILES:
if file_path.endswith(pf):
last_update_line = msg['_line_num']
last_update_file = pf
planning_file = planning_file_from_path(file_path)
if planning_file:
last_update_line = msg['_line_num']
last_update_file = planning_file
return last_update_line, last_update_file
@@ -0,0 +1,325 @@
# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
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)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
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.
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
(Test-WithinRoot $ActiveFile)
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} else {
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
}
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file lives beside the pointer, keeping replacement on the same filesystem.
$tempFile = Join-Path $PlanRoot ('.active_plan.' + [guid]::NewGuid().ToString('N') + '.tmp')
$createdTemp = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$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)
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
exit 1
} finally {
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
Write-Output "To pin this terminal session only:"
Write-Output "`$env:PLAN_ID = '$PlanId'"
@@ -0,0 +1,363 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|--verify-root|PLAN_ID]
# Operates on the current project; listing never binds a host or injects data.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
PWF_ROOT_PIN=""
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Prints the canonical absolute path on success; prints nothing and returns 1
# on a full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
canonicalize() {
target="$1"
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
fi
return 1
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
cand_real="$(canonicalize "${check_target}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""
}
{
line = $0
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && primary == "" && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
primary = line
}
}
END {
finish()
printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && [ -r "${_plan_file}" ] || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.'
fi
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list|--verify-root|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--verify-root checks the planning root and pointer without listing or selecting.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
@@ -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.17.2"
version: "3.19.0"
---
@@ -220,6 +220,12 @@ Helper scripts for automation:
- `scripts/check-complete.sh` — Verify all phases complete
- `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history
### List saved plans
To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
## Advanced Topics
- **Manus Principles:** See [reference.md](reference.md)
@@ -383,9 +383,6 @@ def get_session_candidates(
return 'claude', []
PLANNING_LIKE_SQL = ('%task_plan.md', '%findings.md', '%progress.md')
def get_opencode_db_path() -> Optional[Path]:
"""Resolve OpenCode SQLite path. Same on all OS per xdg-basedir."""
xdg = os.environ.get('XDG_DATA_HOME')
@@ -504,28 +501,42 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
update_time = None
update_idx = -1
for idx, (sid, _) in enumerate(previous_sessions):
params = (sid,) + PLANNING_LIKE_SQL
cur.execute(
"""
SELECT time_created FROM part
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
IN ('task_plan.md', 'findings.md', 'progress.md')
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/task_plan.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/findings.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/progress.md'
)
ORDER BY time_created DESC
LIMIT 1
ORDER BY time_created DESC, id DESC
""",
params,
(sid,),
)
row = cur.fetchone()
if row:
update_sid = sid
update_time = row[0]
update_idx = idx
# Iterate lazily: write parts carry whole file bodies, and fetchall
# would materialize every planning write of the session before the
# first validated row ends the loop.
for candidate_time, data_str in cur:
data = json_loads(data_str)
if not isinstance(data, dict):
continue
state = data.get('state')
input_ = state.get('input') if isinstance(state, dict) else None
file_path = input_.get('filePath') if isinstance(input_, dict) else None
if planning_file_from_path(file_path):
update_sid = sid
update_time = candidate_time
update_idx = idx
break
if update_sid:
break
if not update_sid:
@@ -613,12 +624,17 @@ def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
"""Return a planning filename only when it is the path's exact basename.
A suffix check treats lookalikes such as ``draft_task_plan.md`` as real
planning updates and can anchor catchup at unrelated transcript content.
Normalize separators so the same boundary rule works for Unix and Windows
session records.
"""
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
return basename if basename in PLANNING_FILES else None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
@@ -0,0 +1,325 @@
# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
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)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
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.
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
(Test-WithinRoot $ActiveFile)
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} else {
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
}
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file lives beside the pointer, keeping replacement on the same filesystem.
$tempFile = Join-Path $PlanRoot ('.active_plan.' + [guid]::NewGuid().ToString('N') + '.tmp')
$createdTemp = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$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)
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
exit 1
} finally {
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
Write-Output "To pin this terminal session only:"
Write-Output "`$env:PLAN_ID = '$PlanId'"
@@ -0,0 +1,363 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|--verify-root|PLAN_ID]
# Operates on the current project; listing never binds a host or injects data.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
PWF_ROOT_PIN=""
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Prints the canonical absolute path on success; prints nothing and returns 1
# on a full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
canonicalize() {
target="$1"
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
fi
return 1
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
cand_real="$(canonicalize "${check_target}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""
}
{
line = $0
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && primary == "" && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
primary = line
}
}
END {
finish()
printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && [ -r "${_plan_file}" ] || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.'
fi
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list|--verify-root|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--verify-root checks the planning root and pointer without listing or selecting.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
+7 -1
View File
@@ -228,6 +228,12 @@ Helper scripts for automation:
- `scripts/attest-plan.sh` (and `.ps1`) — Lock the current `task_plan.md` content with a SHA-256 attestation (v2.37.0). Hooks then refuse to inject plan content if the file diverges from the attested hash. Use `--show` to print the stored hash, `--clear` to remove the attestation. See `/plan-attest` command.
- `scripts/plan-doctor.sh` — One-pass self-check for the mechanisms that fail silently (v3.6.0): plan resolution, hook injection, canonicalizer path shape, attestation state, install surfaces, per-fire hook latency. Run it whenever hooks seem quiet or after installing on a new machine. See `/plan-doctor` command.
### List saved plans
To find a task before resuming it, run `sh "<skill-dir>/scripts/set-active-plan.sh" --list` or, in Windows PowerShell, `& "<skill-dir>/scripts/set-active-plan.ps1" -List`. Replace `<skill-dir>` with this installed skill directory and keep your current directory at the project root.
This read-only command lists named plans and phase progress under the current directory's `.planning/`. `[active]` marks the shared default pointer; it does not bind a session. Concurrent tasks still require each host's `PLAN_ID` or separate worktrees.
### Parallel task workflow
For independent tasks in the same repository, create a named plan for each and pin each agent host to its own plan:
@@ -360,7 +366,7 @@ The mode is set by writing a `.mode` file next to the plan (`.planning/<id>/.mod
### The legacy invariant (promise)
With no `.mode` file and no other v3 marker, the hooks produce byte-identical output to v2.43, including the raw `progress.md` tail and the `===BEGIN PLAN DATA===` / `===END PLAN DATA===` delimiters. Every v3 behavior is additive and opt-in. No existing workflow changes.
With no `.mode` file and no other v3 marker, plan injection preserves the v2.43 output, including the raw `progress.md` tail and the `===BEGIN PLAN DATA===` / `===END PLAN DATA===` delimiters. Autonomous and gated behavior remains opt-in. Since v3.18.3, completed plans are silent through the shared Stop gate and Codex Stop hook. Explicit `check-complete.sh` or `check-complete.ps1` calls without the gate flag still report completion; incomplete-plan notices and gate decisions are unchanged.
### What each mode does
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.17.2",
"version": "3.19.0",
"description": "Persistent project planning with selected context injection. Automatic recovery uses project files only; explicit catchup modes read same-project local session records for aggregate counts or bounded replay. The host-aware gate never runs Markdown-declared commands. No network upload path. Ships the skill plus a Pi Coding Agent extension.",
"keywords": [
"pi-package",
@@ -10,7 +10,8 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall -> allow stop)
# When all hold, emits a single-line block-decision JSON on stdout and exits 0.
# Otherwise advisory output and exit 0. Without -Gate, byte-equivalent to v2.43.
# Otherwise reports incomplete plans and exits 0; completed plans stay silent
# with -Gate, including legacy plans without .mode. Explicit reports are unchanged.
#
# Stdin: read only when input is redirected ([Console]::IsInputRedirected), so an
# interactive console never blocks. Hook-piped JSON is EOF-terminated.
@@ -85,9 +86,10 @@ if ($TOTAL -eq 0) {
exit 0
}
# advisory_report: the v2.43 status echo.
# Keep explicit reports, but omit routine success from automatic gate checks.
function Write-AdvisoryReport {
if ($COMPLETE -eq $TOTAL -and $TOTAL -gt 0) {
if ($Gate) { return }
Write-Host ('[planning-with-files] ALL PHASES COMPLETE (' + $COMPLETE + '/' + $TOTAL + '). If the user has additional work, add new phases to task_plan.md before starting.')
} else {
Write-Host ('[planning-with-files] Task in progress (' + $COMPLETE + '/' + $TOTAL + ' phases complete). Update progress.md before stopping.')
@@ -21,8 +21,9 @@
# 4. the block counter (<plan-dir>/.stop_blocks) is below cap (PWF_GATE_CAP, default 20)
# 5. the ledger advanced since the last block (stall → allow stop)
# When all hold, it emits a single-line block-decision JSON on stdout and
# exits 0. Otherwise it falls back to advisory output and exits 0.
# Without --gate, or in non-gated mode, behavior is byte-equivalent to v2.43.
# exits 0. Otherwise it reports incomplete plans and exits 0; completed
# plans stay silent in --gate mode, including legacy plans without .mode.
# Without --gate, the explicit advisory report is unchanged.
#
# Stdin handling: the Claude Code Stop hook pipes a JSON payload on stdin. To
# avoid hanging when nothing is piped, stdin is read ONLY when fd 0 is not a
@@ -119,9 +120,11 @@ if [ "$TOTAL" -eq 0 ]; then
exit 0
fi
# advisory_report: the v2.43 status echo. Always exit 0 after calling.
# Explicit status reports retain completion text. Automatic gate checks have
# nothing to report on success; keep evaluating all gate guards before here.
advisory_report() {
if [ "$COMPLETE" -eq "$TOTAL" ] && [ "$TOTAL" -gt 0 ]; then
[ "$GATE" -eq 1 ] && return 0
echo "[planning-with-files] ALL PHASES COMPLETE ($COMPLETE/$TOTAL). If the user has additional work, add new phases to task_plan.md before starting."
else
echo "[planning-with-files] Task in progress ($COMPLETE/$TOTAL phases complete). Update progress.md before stopping."
@@ -1,5 +1,6 @@
# Initialize planning files for a new session
# Usage: .\init-session.ps1 [-Template TYPE] [project-name]
# .\init-session.ps1 -PlanDir # isolated plan with generated slug
# .\init-session.ps1 -Autonomous # v3 autonomous mode (opt-in)
# .\init-session.ps1 -Gated # v3 gated mode (opt-in, implies autonomous)
# Templates: default, analytics
@@ -12,6 +13,7 @@
param(
[string]$ProjectName = "project",
[string]$Template = "default",
[switch]$PlanDir,
[switch]$Autonomous,
[switch]$Gated
)
@@ -38,7 +40,45 @@ function Get-Nonce {
($bytes | ForEach-Object { $_.ToString("x2") }) -join ""
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
function Get-PlanSlug([string]$Name) {
# -creplace: the case-insensitive -replace lets letters that .NET folds to
# ASCII (a dotted capital I, the Kelvin sign) survive into the plan id.
$slug = $Name.ToLowerInvariant() -creplace '[^a-z0-9]', '-'
$slug = $slug -creplace '-{2,}', '-'
$slug = $slug.Trim('-')
if ($slug.Length -gt 40) {
$slug = $slug.Substring(0, 40).TrimEnd('-')
}
# The resolvers and the selector only accept ASCII plan ids.
if ($slug -cnotmatch '^[a-z0-9-]*$') {
return ""
}
return $slug
}
function Get-ShortId {
return ([Guid]::NewGuid().ToString('N')).Substring(0, 8)
}
function Get-InheritedMode([string]$CurrentMode) {
$RootModePath = Join-Path (Get-Location).Path ".mode"
if (-not (Test-Path -LiteralPath $RootModePath)) {
return $CurrentMode
}
if ($CurrentMode -eq "gated") {
return $CurrentMode
}
$RootMode = Get-Content -LiteralPath $RootModePath -Raw -ErrorAction SilentlyContinue
# Case-sensitive like inherit_root_mode in init-session.sh and the injector.
if ($RootMode -cmatch 'gate') {
return "gated"
}
if ($RootMode -cmatch 'autonomous') {
return "autonomous"
}
return $CurrentMode
}
# Validate template
if ($Template -ne "default" -and $Template -ne "analytics") {
@@ -46,11 +86,98 @@ if ($Template -ne "default" -and $Template -ne "analytics") {
$Template = "default"
}
# Match init-session.sh: zero args (or an empty name) preserve legacy root
# mode. A positional project name or -PlanDir creates an isolated
# .planning/<date>-<slug>/ plan.
$NamedPlan = $PSBoundParameters.ContainsKey("ProjectName") -and -not [string]::IsNullOrEmpty($ProjectName)
$UsePlanDir = $PlanDir -or $NamedPlan
if ($UsePlanDir) {
$PlanningRoot = Join-Path (Get-Location).Path ".planning"
# Match init-session.sh: set-active-plan.ps1 owns every write to the
# shared pointer, so a named plan cannot be created without it.
$PlanSelector = Join-Path $ScriptDir "set-active-plan.ps1"
if (-not (Test-Path -LiteralPath $PlanSelector -PathType Leaf)) {
Write-Error "Error: set-active-plan.ps1 is required to create a named plan safely."
exit 1
}
New-Item -ItemType Directory -Path $PlanningRoot -Force | Out-Null
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. A
# script that returns without exit leaves $LASTEXITCODE alone, so reset
# it first and treat a thrown error as a failure too.
$global:LASTEXITCODE = 0
try {
& $PlanSelector -VerifyRoot *> $null
} catch {
$global:LASTEXITCODE = 1
}
if ($LASTEXITCODE -ne 0) {
Write-Error "Error: the planning directory or the active plan pointer is outside the project or cannot be verified."
exit 1
}
if ($NamedPlan) {
$Slug = Get-PlanSlug $ProjectName
} else {
$Slug = ""
$ProjectName = "untitled"
}
if ([string]::IsNullOrEmpty($Slug)) {
$Slug = "untitled-$(Get-ShortId)"
}
$BaseId = "$DATE-$Slug"
$PlanId = $BaseId
$Counter = 2
while (Test-Path -LiteralPath (Join-Path $PlanningRoot $PlanId)) {
$PlanId = "$BaseId-$Counter"
$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
}
$Mode = Get-InheritedMode $Mode
} else {
$TargetDir = (Get-Location).Path
}
$TaskPlanPath = Join-Path $TargetDir "task_plan.md"
$FindingsPath = Join-Path $TargetDir "findings.md"
$ProgressPath = Join-Path $TargetDir "progress.md"
if ($UsePlanDir) {
$TaskPlanDisplay = $TaskPlanPath
$FindingsDisplay = $FindingsPath
$ProgressDisplay = $ProgressPath
} else {
$TaskPlanDisplay = "task_plan.md"
$FindingsDisplay = "findings.md"
$ProgressDisplay = "progress.md"
}
Write-Host "Initializing planning files for: $ProjectName (template: $Template)"
if ($UsePlanDir) {
Write-Host "PLAN_ID=$PlanId"
}
# Create task_plan.md if it doesn't exist
if (-not (Test-Path "task_plan.md")) {
if (-not (Test-Path -LiteralPath $TaskPlanPath)) {
$AnalyticsPlan = Join-Path $TemplateDir "analytics_task_plan.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsPlan)) {
Copy-Item $AnalyticsPlan "task_plan.md"
Copy-Item -LiteralPath $AnalyticsPlan -Destination $TaskPlanPath
} else {
@"
# Task Plan: [Brief Description]
@@ -99,18 +226,18 @@ Phase 1
## Errors Encountered
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "task_plan.md" -Encoding UTF8
"@ | Out-File -LiteralPath $TaskPlanPath -Encoding UTF8
}
Write-Host "Created task_plan.md"
Write-Host "Created $TaskPlanDisplay"
} else {
Write-Host "task_plan.md already exists, skipping"
Write-Host "$TaskPlanDisplay already exists, skipping"
}
# Create findings.md if it doesn't exist
if (-not (Test-Path "findings.md")) {
if (-not (Test-Path -LiteralPath $FindingsPath)) {
$AnalyticsFindings = Join-Path $TemplateDir "analytics_findings.md"
if ($Template -eq "analytics" -and (Test-Path $AnalyticsFindings)) {
Copy-Item $AnalyticsFindings "findings.md"
Copy-Item -LiteralPath $AnalyticsFindings -Destination $FindingsPath
} else {
@"
# Findings & Decisions
@@ -131,15 +258,15 @@ if (-not (Test-Path "findings.md")) {
## Resources
-
"@ | Out-File -FilePath "findings.md" -Encoding UTF8
"@ | Out-File -LiteralPath $FindingsPath -Encoding UTF8
}
Write-Host "Created findings.md"
Write-Host "Created $FindingsDisplay"
} else {
Write-Host "findings.md already exists, skipping"
Write-Host "$FindingsDisplay already exists, skipping"
}
# Create progress.md if it doesn't exist
if (-not (Test-Path "progress.md")) {
if (-not (Test-Path -LiteralPath $ProgressPath)) {
if ($Template -eq "analytics") {
@"
# Progress Log
@@ -160,7 +287,7 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
} else {
@"
# Progress Log
@@ -181,23 +308,28 @@ if (-not (Test-Path "progress.md")) {
### Errors
| Error | Resolution |
|-------|------------|
"@ | Out-File -FilePath "progress.md" -Encoding UTF8
"@ | Out-File -LiteralPath $ProgressPath -Encoding UTF8
}
Write-Host "Created progress.md"
Write-Host "Created $ProgressDisplay"
} else {
Write-Host "progress.md already exists, skipping"
Write-Host "$ProgressDisplay already exists, skipping"
}
Write-Host ""
Write-Host "Planning files initialized!"
Write-Host "Files: task_plan.md, findings.md, progress.md"
if ($UsePlanDir) {
Write-Host "Active plan recorded: $(Join-Path $PlanningRoot '.active_plan')"
Write-Host "Pin this terminal to the plan for parallel sessions:"
Write-Host " `$env:PLAN_ID='$PlanId'"
} else {
Write-Host "Files: task_plan.md, findings.md, progress.md"
}
# v3 opt-in mode side effects. No-op when -Autonomous/-Gated were not passed, so
# the default path stays byte-equivalent to v2.43.0. PS1 init writes in CWD, so
# dotfiles live in CWD and attest-plan.ps1 falls back to the legacy
# .plan-attestation at the project root.
# the default path stays byte-equivalent to v2.43.0. Dotfiles live beside the
# selected plan; root mode therefore retains the legacy project-root behavior.
if ($Mode -ne "") {
$PlanDirPwf = (Get-Location).Path
$PlanDirPwf = $TargetDir
# (a) reset gate block counter, drop stale gate ledger.
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".stop_blocks") -Value "0" -Encoding ascii
@@ -216,13 +348,42 @@ if ($Mode -ne "") {
Set-Content -LiteralPath (Join-Path $PlanDirPwf ".mode") -Value $MarkerText -Encoding ascii
# (c) auto-attest (attestation default-on in v3 modes, security strand rec 1).
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
# attest-plan.ps1 intentionally refuses non-Windows hosts because its secure
# no-follow implementation uses Win32 handles. On Unix, use the POSIX
# attester instead. Bind slug mode to the plan we just created so an
# inherited PLAN_ID cannot redirect attestation to another plan.
$PlanFilePwf = Join-Path $PlanDirPwf "task_plan.md"
if ((Test-Path -LiteralPath $AttestPs1) -and (Test-Path -LiteralPath $PlanFilePwf)) {
if (Test-Path -LiteralPath $PlanFilePwf) {
$HadPlanId = Test-Path Env:PLAN_ID
$PreviousPlanId = $env:PLAN_ID
try {
& $AttestPs1 *> $null
if ($UsePlanDir) {
$env:PLAN_ID = $PlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
$IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
if ($IsWindowsHost) {
$AttestPs1 = Join-Path $ScriptDir "attest-plan.ps1"
if (Test-Path -LiteralPath $AttestPs1) {
& $AttestPs1 *> $null
}
} else {
$AttestSh = Join-Path $ScriptDir "attest-plan.sh"
$Sh = Get-Command sh -ErrorAction SilentlyContinue
if ($Sh -and (Test-Path -LiteralPath $AttestSh)) {
& $Sh.Path $AttestSh *> $null
}
}
} catch {
# attestation failure must not abort init; the mode marker still stands.
} finally {
if ($HadPlanId) {
$env:PLAN_ID = $PreviousPlanId
} else {
Remove-Item Env:PLAN_ID -ErrorAction SilentlyContinue
}
}
}
@@ -83,7 +83,8 @@ done
DATE=$(date +%Y-%m-%d)
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
# CDPATH must not redirect the cd that locates the sibling scripts.
SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)"
SKILL_ROOT="$(dirname "$SCRIPT_DIR")"
TEMPLATE_DIR="$SKILL_ROOT/templates"
@@ -382,6 +383,20 @@ if [ "$SLUG_MODE" -eq 1 ]; then
BASE_ID="${DATE}-${SLUG}"
PLAN_ID="$BASE_ID"
PLAN_ROOT="${PWD}/.planning"
PLAN_SELECTOR="${SCRIPT_DIR}/set-active-plan.sh"
if [ ! -f "${PLAN_SELECTOR}" ]; then
echo "Error: set-active-plan.sh is required to create a named plan safely." >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
# Verify the physical planning root and the existing pointer before
# creating anything below it. A symlink or junction that escapes the
# project must not redirect init writes, and a linked or non-regular
# pointer must be refused before a plan directory exists on disk. The
# selector's check is constant time; --list would parse every plan.
if ! sh "${PLAN_SELECTOR}" --verify-root; then
exit 1
fi
counter=2
while [ -d "${PLAN_ROOT}/${PLAN_ID}" ]; do
PLAN_ID="${BASE_ID}-${counter}"
@@ -393,7 +408,13 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "Initializing planning files for: ${PROJECT_NAME:-untitled} (template: $TEMPLATE)"
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
# Reuse the selector's contained, atomic pointer replacement. Direct shell
# redirection would truncate a pre-existing hardlink and could overwrite a
# different file that shares the same inode.
if ! sh "${PLAN_SELECTOR}" "${PLAN_ID}" >/dev/null; then
echo "Error: could not safely update ${PLAN_ROOT}/.active_plan." >&2
exit 1
fi
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
@@ -407,9 +407,6 @@ def get_session_candidates(
return 'claude', []
PLANNING_LIKE_SQL = ('%task_plan.md', '%findings.md', '%progress.md')
def get_opencode_db_path() -> Optional[Path]:
"""Resolve OpenCode SQLite path. Same on all OS per xdg-basedir."""
xdg = os.environ.get('XDG_DATA_HOME')
@@ -576,28 +573,42 @@ def opencode_catchup(project_path: str, mode: str = 'no-history') -> None:
update_time = None
update_idx = -1
for idx, (sid, _) in enumerate(previous_sessions):
params = (sid,) + PLANNING_LIKE_SQL
cur.execute(
"""
SELECT time_created FROM part
SELECT time_created, data FROM part
WHERE session_id = ?
AND json_extract(data, '$.type') = 'tool'
AND lower(json_extract(data, '$.tool')) IN ('write', 'edit', 'patch')
AND (
json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
OR json_extract(data, '$.state.input.filePath') LIKE ?
replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
IN ('task_plan.md', 'findings.md', 'progress.md')
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/task_plan.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/findings.md'
OR replace(json_extract(data, '$.state.input.filePath'), char(92), '/')
GLOB '*/progress.md'
)
ORDER BY time_created DESC
LIMIT 1
ORDER BY time_created DESC, id DESC
""",
params,
(sid,),
)
row = cur.fetchone()
if row:
update_sid = sid
update_time = row[0]
update_idx = idx
# Iterate lazily: write parts carry whole file bodies, and fetchall
# would materialize every planning write of the session before the
# first validated row ends the loop.
for candidate_time, data_str in cur:
data = json_loads(data_str)
if not isinstance(data, dict):
continue
state = data.get('state')
input_ = state.get('input') if isinstance(state, dict) else None
file_path = input_.get('filePath') if isinstance(input_, dict) else None
if planning_file_from_path(file_path):
update_sid = sid
update_time = candidate_time
update_idx = idx
break
if update_sid:
break
if not update_sid:
@@ -685,12 +696,17 @@ def parse_session_messages(session_file: Path) -> List[Dict[str, Any]]:
def planning_file_from_path(path_value: Any) -> Optional[str]:
"""Return a planning filename only when it is the path's exact basename.
A suffix check treats lookalikes such as ``draft_task_plan.md`` as real
planning updates and can anchor catchup at unrelated transcript content.
Normalize separators so the same boundary rule works for Unix and Windows
session records.
"""
if not isinstance(path_value, str):
return None
for pf in PLANNING_FILES:
if path_value.endswith(pf):
return pf
return None
basename = path_value.replace(chr(92), '/').rsplit('/', 1)[-1]
return basename if basename in PLANNING_FILES else None
def planning_file_from_paths(paths: Iterable[Any]) -> Optional[str]:
+290 -16
View File
@@ -1,27 +1,269 @@
# planning-with-files: set or display the active plan pointer (PowerShell).
# planning-with-files: set, display, or list the active plan pointer (PowerShell).
#
# Usage:
# .\set-active-plan.ps1 <plan_id> - pin .planning\.active_plan to plan_id
# .\set-active-plan.ps1 - print the current active plan (if any)
# .\set-active-plan.ps1 -List - list available named plans and phase counts
# .\set-active-plan.ps1 --list - equivalent to -List and -l
# .\set-active-plan.ps1 -VerifyRoot - check the planning root and pointer only
# .\set-active-plan.ps1 --verify-root - equivalent to -VerifyRoot
param(
[string]$PlanId = ""
[Parameter(Position = 0)]
[string]$PlanId = "",
[Alias('l', '-list')]
[switch]$List,
[Alias('verify-root')]
[switch]$VerifyRoot,
[Alias('h', '-help')]
[switch]$Help
)
$PlanRoot = Join-Path (Get-Location) ".planning"
$ProjectRoot = (Get-Location).Path
# Windows PowerShell 5.1 can silently change directories when -File inherits
# a cwd containing wildcard characters. Recover that physical cwd only for a
# direct invocation of this script; interactive Set-Location remains primary.
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)) {
$ProjectRoot = [Environment]::CurrentDirectory
}
break
}
}
}
$PlanRoot = Join-Path $ProjectRoot ".planning"
$ActiveFile = Join-Path $PlanRoot ".active_plan"
$script:IsWindowsHost = [Environment]::OSVersion.Platform -eq [PlatformID]::Win32NT
# Resolve-Path can retain a junction's spelling. Like resolve-plan-dir.ps1,
# open the actual filesystem object before checking the project boundary.
# The Windows handle supports both directories and task_plan.md files.
function Get-FinalPath {
param([string]$Path)
if (-not ("PwfPlanListingNative" -as [type])) {
Add-Type -ErrorAction Stop -TypeDefinition @'
using System;
using System.ComponentModel;
using System.Runtime.InteropServices;
using System.Text;
using Microsoft.Win32.SafeHandles;
public static class PwfPlanListingNative {
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern SafeFileHandle CreateFileW(
string name, uint access, uint share, IntPtr security,
uint creation, uint flags, IntPtr template);
[DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)]
private static extern uint GetFinalPathNameByHandleW(
SafeFileHandle handle, StringBuilder path, uint length, uint flags);
[DllImport("libc", SetLastError = true)]
private static extern IntPtr realpath(string path, IntPtr resolved);
[DllImport("libc")]
private static extern void free(IntPtr pointer);
public static string FinalPath(string path) {
if (Environment.OSVersion.Platform != PlatformID.Win32NT) {
IntPtr resolved = realpath(path, IntPtr.Zero);
if (resolved == IntPtr.Zero) throw new Win32Exception(Marshal.GetLastWin32Error());
try { return Marshal.PtrToStringAnsi(resolved); }
finally { free(resolved); }
}
// OPEN_EXISTING, FILE_SHARE_READ | WRITE | DELETE, BACKUP_SEMANTICS.
using (SafeFileHandle handle = CreateFileW(
path, 0, 7, IntPtr.Zero, 3, 0x02000000, IntPtr.Zero)) {
if (handle.IsInvalid) throw new Win32Exception(Marshal.GetLastWin32Error());
StringBuilder buffer = new StringBuilder(32768);
uint length = GetFinalPathNameByHandleW(handle, buffer, (uint)buffer.Capacity, 0);
if (length == 0 || length >= buffer.Capacity)
throw new Win32Exception(Marshal.GetLastWin32Error());
string result = buffer.ToString();
if (result.StartsWith(@"\\?\UNC\", StringComparison.OrdinalIgnoreCase))
return @"\\" + result.Substring(8);
if (result.StartsWith(@"\\?\", StringComparison.OrdinalIgnoreCase))
return result.Substring(4);
return result;
}
}
}
'@
}
return [PwfPlanListingNative]::FinalPath($Path)
}
function Test-WithinRoot {
param([string]$Path)
try {
$rootReal = (Get-FinalPath $ProjectRoot).TrimEnd('\', '/')
$pathReal = (Get-FinalPath $Path).TrimEnd('\', '/')
$comparison = [StringComparison]::Ordinal
if ($script:IsWindowsHost) { $comparison = [StringComparison]::OrdinalIgnoreCase }
return $pathReal.Equals($rootReal, $comparison) -or
$pathReal.StartsWith($rootReal + [IO.Path]::DirectorySeparatorChar, $comparison)
} catch {
return $false
}
}
function Test-ValidSlug {
param([string]$Name)
return $Name -cmatch '^[A-Za-z0-9_][A-Za-z0-9._-]*\z'
}
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.
return -not $item.PSIsContainer -and
($AllowLink -or (($item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0)) -and
(Test-WithinRoot $ActiveFile)
}
function Get-CurrentActivePlan {
if (-not (Test-SafeActiveFile -AllowLink)) { return "" }
try {
$current = ([string](Get-Content -LiteralPath $ActiveFile -Raw -Encoding UTF8 -ErrorAction Stop)).Trim([char[]]"`r`n")
if (Test-ValidSlug $current) { return $current }
} catch { }
return ""
}
function Add-PhaseStatus {
param([hashtable]$Counts, $Phase)
if ($null -eq $Phase) { return }
$status = $Phase.Inline
if ($Phase.Primary) { $status = $Phase.Primary }
if ($status) { $Counts[$status]++ }
}
function Get-PhaseStatus {
param([string]$PlanFile)
$counts = @{ total = 0; complete = 0; in_progress = 0; pending = 0 }
$phase = $null
$fence = ""
$fenceLength = 0
# The shipped translations keep status identifiers in English. Unicode
# escapes preserve Windows PowerShell 5.1 compatibility without a BOM.
$phaseLabel = '(?:Phase|Fase|\u0627\u0644\u0645\u0631\u062d\u0644\u0629|\u9636\u6bb5|\u968e\u6bb5)'
$statusLabel = '(?:Status:|Estado:|\u0627\u0644\u062d\u0627\u0644\u0629:|\u72b6\u6001\uff1a|\u72c0\u614b\uff1a)'
# Read once; an empty file is a valid plan with zero phases.
$content = [string](Get-Content -LiteralPath $PlanFile -Raw -Encoding UTF8 -ErrorAction Stop)
foreach ($line in ($content -split '\r?\n')) {
if ($fence) {
$closing = '^ {0,3}' + [regex]::Escape($fence) + '{' + $fenceLength + ',}[ \t]*$'
if ($line -match $closing) { $fence = "" }
continue
}
if ($line -match '^ {0,3}(`{3,}|~{3,})') {
$fence = $Matches[1].Substring(0, 1)
$fenceLength = $Matches[1].Length
continue
}
if ($line -cmatch ('^ {0,3}###[ \t]+' + $phaseLabel + '[ \t]+[0-9]+(?:[^0-9A-Za-z_]|$)')) {
Add-PhaseStatus $counts $phase
$phase = @{ Primary = ""; Inline = "" }
$counts.total++
if ($line -cmatch '\[(complete|in_progress|pending)\]') {
$phase.Inline = $Matches[1]
}
continue
}
if ($line -match '^ {0,3}#{1,3}(?:[ \t]+|$)') {
Add-PhaseStatus $counts $phase
$phase = $null
continue
}
if ($null -ne $phase -and -not $phase.Primary -and
$line -cmatch ('^ {0,3}(?:-[ \t]+)?\*\*' + $statusLabel + '\*\*[ \t]+(complete|in_progress|pending)(?:[ \t]|$)')) {
$phase.Primary = $Matches[1]
}
}
Add-PhaseStatus $counts $phase
return "$($counts.complete)/$($counts.total) complete, $($counts.in_progress) in_progress, $($counts.pending) pending"
}
function Show-PlanList {
if (-not (Test-Path -LiteralPath $PlanRoot -PathType Container)) {
Write-Output "No planning directory found."
return
}
if (-not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$active = Get-CurrentActivePlan
Write-Output "Available plans:"
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
try { $status = Get-PhaseStatus $planFile } catch { continue }
$marker = ""
if ($plan.Name -ceq $active) { $marker = " [active]" }
Write-Output "- $($plan.Name)$marker - $status"
$found = $true
}
if (-not $found) { Write-Output "No named plans found." }
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|-VerifyRoot|PLAN_ID]"
exit 0
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
if ($VerifyRoot) {
if ($List -or $PlanId) {
Write-Error "Error: verify the planning root in a separate call."
exit 1
}
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
$existingPointer = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($existingPointer -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
exit 0
}
if ($List -or $PlanId -eq "--list" -or $PlanId -eq "-l") {
if ($List -and $PlanId) {
Write-Error "Error: list plans or set PLAN_ID in separate calls."
exit 1
}
Show-PlanList
exit 0
}
if ($PlanId -eq "") {
if (Test-Path $ActiveFile) {
$current = (Get-Content $ActiveFile -Raw -Encoding UTF8).Trim()
$current = ""
if ((Test-Path -LiteralPath $PlanRoot -PathType Container) -and -not (Test-WithinRoot $PlanRoot)) {
Write-Error "Error: planning directory is outside the project or cannot be verified."
exit 1
}
if (Test-WithinRoot $PlanRoot) { $current = Get-CurrentActivePlan }
if ($current) {
$planDir = Join-Path $PlanRoot $current
if ($current -ne "" -and (Test-Path $planDir)) {
if ((Test-Path -LiteralPath $planDir -PathType Container) -and (Test-WithinRoot $planDir)) {
Write-Output "Active plan: $current"
Write-Output "Path: $planDir"
} elseif ($current -ne "") {
Write-Output "Active plan pointer: $current (directory not found - stale pointer)"
} else {
Write-Output "No active plan set."
Write-Output "Active plan pointer: $current (directory not found or outside project - stale pointer)"
}
} else {
Write-Output "No active plan set."
@@ -29,21 +271,53 @@ if ($PlanId -eq "") {
exit 0
}
if (-not (Test-ValidSlug $PlanId)) {
Write-Error "Error: invalid plan ID. Use letters, numbers, underscores, dots, or hyphens; start with a letter, number, or underscore."
exit 1
}
$PlanDir = Join-Path $PlanRoot $PlanId
if (-not (Test-Path $PlanDir)) {
if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Error: plan directory not found: $PlanDir"
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
if (-not (Test-Path $PlanRoot)) {
New-Item -ItemType Directory -Path $PlanRoot -Force | Out-Null
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
}
$activeItem = Get-Item -LiteralPath $ActiveFile -Force -ErrorAction SilentlyContinue
if ($activeItem -and -not (Test-SafeActiveFile)) {
Write-Error "Error: the active plan pointer must be a regular file within the project."
exit 1
}
$utf8NoBom = New-Object System.Text.UTF8Encoding($false)
[System.IO.File]::WriteAllText($ActiveFile, $PlanId, $utf8NoBom)
# Replace the directory entry instead of truncating an existing inode: a
# hardlinked pointer must not overwrite another file. The exclusive temporary
# file lives beside the pointer, keeping replacement on the same filesystem.
$tempFile = Join-Path $PlanRoot ('.active_plan.' + [guid]::NewGuid().ToString('N') + '.tmp')
$createdTemp = $false
try {
$stream = [IO.File]::Open($tempFile, [IO.FileMode]::CreateNew, [IO.FileAccess]::Write, [IO.FileShare]::None)
$createdTemp = $true
try {
$bytes = $utf8NoBom.GetBytes($PlanId)
$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)
}
} catch {
Write-Error "Error: could not set the active plan pointer: $($_.Exception.Message)"
exit 1
} finally {
if ($createdTemp -and (Test-Path -LiteralPath $tempFile)) {
Remove-Item -LiteralPath $tempFile -Force -ErrorAction SilentlyContinue
}
}
Write-Output "Active plan set to: $PlanId"
Write-Output "Path: $PlanDir"
Write-Output ""
+351 -38
View File
@@ -1,50 +1,363 @@
#!/bin/sh
# planning-with-files: set or display the active plan pointer.
#
# Usage:
# set-active-plan.sh <plan_id> — pin .planning/.active_plan to plan_id
# set-active-plan.sh — print the current active plan (if any)
#
# The active plan is stored in .planning/.active_plan and is read by
# resolve-plan-dir.sh when no $PLAN_ID env var is set.
set -e
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|--verify-root|PLAN_ID]
# Operates on the current project; listing never binds a host or injects data.
set -eu
PLAN_ROOT="${PWD}/.planning"
ACTIVE_FILE="${PLAN_ROOT}/.active_plan"
PWF_ROOT_PIN=""
# No args → show current active plan
if [ "${1:-}" = "" ]; then
if [ -f "${ACTIVE_FILE}" ]; then
plan_id="$(tr -d '\r\n' < "${ACTIVE_FILE}")"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ]; then
echo "Active plan: ${plan_id}"
echo "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
echo "Active plan pointer: ${plan_id} (directory not found — stale pointer)"
else
echo "No active plan set."
fi
# Use the resolver canonicalization policy without running plan selection.
slug_is_valid() {
case "$1" in
'') return 1 ;;
*[!A-Za-z0-9._-]*) return 1 ;;
[A-Za-z0-9_]*) return 0 ;;
esac
return 1
}
# Pure-sh backslash-to-forward-slash normalizer; result lands in $NORM_OUT.
# Windows-native coreutils builds (e.g. C:\Program Files\coreutils on PATH
# ahead of Git's usr/bin) canonicalize MSYS-style /c/... input to C:\-style
# backslash output. The containment prefix match below is written with forward
# slashes, so without this normalization every canonical pair mismatches and
# resolution silently fails. On POSIX systems paths contain no backslash and
# this is the identity. A literal backslash in a Unix filename normalizes to
# "/" and at worst fails containment — the safe direction. No subshell, no
# fork: plain parameter expansion in a loop.
norm_slashes() {
NORM_OUT=""
_ns_rest="$1"
while :; do
case "${_ns_rest}" in
*\\*)
NORM_OUT="${NORM_OUT}${_ns_rest%%\\*}/"
_ns_rest="${_ns_rest#*\\}"
;;
*)
NORM_OUT="${NORM_OUT}${_ns_rest}"
break
;;
esac
done
}
# Return true when a candidate path names the Microsoft Store WindowsApps
# directory. Store app aliases are not stable interpreter binaries and may
# present as executable while refusing script execution. Matching is
# case-insensitive and works before or after Windows slash normalization.
is_windowsapps_path() {
norm_slashes "$1"
case "${NORM_OUT}" in
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]|\
*/[Ww][Ii][Nn][Dd][Oo][Ww][Ss][Aa][Pp][Pp][Ss]/*) return 0 ;;
esac
return 1
}
# Select only an interpreter path the caller explicitly trusted.
# PWF_TRUSTED_PYTHON is preferred; PYTHON_BIN remains a compatibility alias.
# PATH discovery is intentionally forbidden because resolver hooks can run in
# repositories that control PATH. Windows-native absolute paths are converted
# with Git Bash's fixed system cygpath, never a PATH-selected shim.
trusted_python() {
for _tp_candidate in "${PWF_TRUSTED_PYTHON:-}" "${PYTHON_BIN:-}"; do
[ -n "${_tp_candidate}" ] || continue
case "${_tp_candidate}" in
\\\\*|//*) continue ;;
[A-Za-z]:[\\/]*)
is_windowsapps_path "${_tp_candidate}" && continue
_tp_cygpath="/usr/bin/cygpath.exe"
[ -f "${_tp_cygpath}" ] && [ -x "${_tp_cygpath}" ] || continue
_tp_candidate="$("${_tp_cygpath}" -u "${_tp_candidate}" 2>/dev/null)" \
|| continue
;;
/*) ;;
*) continue ;;
esac
is_windowsapps_path "${_tp_candidate}" && continue
[ -f "${_tp_candidate}" ] || continue
[ -x "${_tp_candidate}" ] || continue
printf "%s\n" "${_tp_candidate}"
return 0
done
return 1
}
# Portable path canonicalizer. realpath first (Linux, modern coreutils),
# then readlink -f (older GNU), then an explicitly trusted Python interpreter.
# Prints the canonical absolute path on success; prints nothing and returns 1
# on a full miss so containment fails closed. No Python spawn on the happy
# path: realpath/readlink cover Linux, WSL, Git-Bash, and modern macOS.
canonicalize() {
target="$1"
if command -v realpath >/dev/null 2>&1; then
out="$(realpath "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
if command -v readlink >/dev/null 2>&1; then
out="$(readlink -f "${target}" 2>/dev/null)" && [ -n "${out}" ] && {
printf "%s\n" "${out}"; return 0; }
fi
_canonical_python="$(trusted_python)" || _canonical_python=""
if [ -n "${_canonical_python}" ]; then
out="$("${_canonical_python}" -I -c "import os,sys;print(os.path.realpath(sys.argv[1]))" "${target}" 2>/dev/null)" \
&& [ -n "${out}" ] && { printf "%s\n" "${out}"; return 0; }
fi
return 1
}
# Containment guard (security A1.3): a resolved plan dir must canonicalize to a
# path under the project root (the CWD the script runs from). A symlink inside
# a valid slug dir pointing at /etc or outside the workspace would otherwise let
# the hooks hash and inject an arbitrary file. On any violation we return 1 so
# the caller treats the candidate as unresolved and falls back safely.
#
# The root canonicalizes via the relative token "." rather than the $PWD
# string. On some Windows/MSYS setups (8.3 short names, the /tmp mount alias)
# realpath("$PWD") and realpath(relative-candidate) resolve through different
# code paths and land on differently-spelled-but-equal targets, so the prefix
# match below fails and resolution silently goes dark. "." resolves through
# the same physical-cwd path candidates already use (same fix inject-plan.sh
# received earlier; the resolver kept the $PWD form until now). Both sides are
# backslash-normalized before comparison for Windows-native canonicalizers.
# The root is computed once per run: the newest-mtime scan calls this guard
# per plan dir, and each canonicalize costs a process spawn on Windows.
#
# With a PWF_PLAN_ROOT pin (issue #212) containment is checked against THAT
# root instead of the cwd: candidates arrive ${PWF_PLAN_ROOT}/-prefixed, so
# both sides canonicalize through the same path spelling. Unpinned keeps the
# relative "." root — byte-identical to the legacy check.
ROOT_REAL=""
ROOT_REAL_SET=0
is_within_root() {
candidate="$1"
if [ "${ROOT_REAL_SET}" = "0" ]; then
ROOT_REAL="$(canonicalize "${PWF_ROOT_PIN:-.}")" || ROOT_REAL=""
norm_slashes "${ROOT_REAL}"
ROOT_REAL="${NORM_OUT}"
ROOT_REAL_SET=1
fi
# Canonicalize the candidate through its cwd-RELATIVE form whenever it
# lives under ${PWD}. The candidate string is built from ${PWD} (an MSYS
# long-form spelling), while the root canonicalizes from "." (the process
# cwd, which a caller may have set with an 8.3 short-form string). A
# Windows-native realpath does not unify those spellings, so canonicalizing
# both sides from the same cwd base is the only spelling-stable comparison.
# The emitted result keeps the original absolute candidate — only the
# containment check uses the relative form.
# Pinned resolution skips the rewrite: candidate and root then share the
# ${PWF_PLAN_ROOT} spelling, so both canonicalize directly from it.
if [ -n "${PWF_ROOT_PIN}" ]; then
check_target="${candidate}"
else
echo "No active plan set."
case "${candidate}" in
"${PWD}"/*) check_target=".${candidate#"${PWD}"}" ;;
*) check_target="${candidate}" ;;
esac
fi
cand_real="$(canonicalize "${check_target}")" || cand_real=""
norm_slashes "${cand_real}"
cand_real="${NORM_OUT}"
if [ -z "${ROOT_REAL}" ] || [ -z "${cand_real}" ]; then
# Slug validation blocks textual traversal, but only successful
# canonicalization can rule out a symlink/junction escape.
return 1
fi
case "${cand_real}" in
"${ROOT_REAL}"|"${ROOT_REAL}"/*) return 0 ;;
*) return 1 ;;
esac
}
# Each phase contributes at most one status. An explicit Status line wins
# over an inline heading marker. Fenced examples and unrelated sections are
# not phases. Keep this parser aligned with the PowerShell helper.
phase_status() {
awk '
function finish() {
if (phase) {
status = primary != "" ? primary : inline_status
if (status == "complete") complete++
else if (status == "in_progress") in_progress++
else if (status == "pending") pending++
}
phase = 0; primary = ""; inline_status = ""
}
{
line = $0
sub(/\r$/, "", line)
trimmed = line
sub(/^ */, "", trimmed)
if (line ~ /^ ? ? ?```/ || line ~ /^ ? ? ?~~~/) {
marker = substr(trimmed, 1, 1)
run = 0
while (substr(trimmed, run + 1, 1) == marker) run++
if (fence == "") { fence = marker; fence_length = run }
else if (marker == fence && run >= fence_length && substr(trimmed, run + 1) ~ /^[ \t]*$/) fence = ""
next
}
if (fence != "") next
if (line ~ /^ ? ? ?###[ \t]+(Phase|Fase|المرحلة|阶段|階段)[ \t]+[0-9]+([^0-9A-Za-z_]|$)/) {
finish(); phase = 1; total++
if (match(line, /\[(complete|in_progress|pending)\]/))
inline_status = substr(line, RSTART + 1, RLENGTH - 2)
} else if (line ~ /^ ? ? ?(###|##|#)([ \t]|$)/) {
finish()
} else if (phase && primary == "" && line ~ /^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+(complete|in_progress|pending)([ \t]|$)/) {
sub(/^ ? ? ?(-[ \t]+)?\*\*(Status:|Estado:|الحالة:|状态:|狀態:)\*\*[ \t]+/, "", line)
sub(/[ \t].*$/, "", line)
primary = line
}
}
END {
finish()
printf "%d/%d complete, %d in_progress, %d pending", complete, total, in_progress, pending
}
' < "$1"
}
# A pre-existing pointer must be a contained regular file before it is
# replaced: a link would be followed or its shared inode overwritten.
pointer_is_unsafe() {
{ [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }
}
# Constant-time check for callers that are about to create a plan: the
# planning root, when present, must be inside the project, and an existing
# pointer must be replaceable. Nothing is read, listed, or written.
verify_root() {
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
return 1
fi
return 0
}
current_active() {
# An unreadable pointer is treated as unset; under set -e the read
# would otherwise abort listing.
if [ -f "${ACTIVE_FILE}" ] && [ -r "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
_current="$(tr '\r' '\n' < "${ACTIVE_FILE}")"
# Windows editors and older PowerShell defaults can leave a UTF-8 BOM.
# Treat it as an encoding marker, not part of the shared plan slug.
_utf8_bom="$(printf '\357\273\277')"
case "${_current}" in
"${_utf8_bom}"*) _current="${_current#"${_utf8_bom}"}" ;;
esac
slug_is_valid "${_current}" && printf '%s\n' "${_current}"
fi
return 0
}
list_plans() {
if [ ! -d "${PLAN_ROOT}" ]; then
printf '%s\n' 'No planning directory found.'
return 0
fi
if ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
return 1
fi
_active="$(current_active)"
_found=0
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
_plan_file="${_dir}/task_plan.md"
[ -f "${_plan_file}" ] && [ -r "${_plan_file}" ] || continue
is_within_root "${_plan_file}" || continue
_status="$(phase_status "${_plan_file}")" || continue
_marker=''
if [ "${_id}" = "${_active}" ]; then _marker=' [active]'; fi
printf '%s\n' "- ${_id}${_marker} - ${_status}"
_found=1
done
if [ "${_found}" -eq 0 ]; then
printf '%s\n' 'No named plans found.'
else
printf '%s\n' '[active] marks the shared default pointer. Set PLAN_ID to pin a session.'
fi
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans, verify the root, or set PLAN_ID in separate calls.' >&2
exit 1
fi
case "${1:-}" in
--list|-l) list_plans; exit $? ;;
--verify-root) verify_root; exit $? ;;
--help|-h)
printf '%s\n' 'Usage: set-active-plan.sh [--list|--verify-root|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.' \
'--verify-root checks the planning root and pointer without listing or selecting.'
exit 0 ;;
esac
if [ "${1:-}" = '' ]; then
if [ -d "${PLAN_ROOT}" ] && ! is_within_root "${PLAN_ROOT}"; then
printf '%s\n' 'Error: planning directory is outside the project or cannot be verified.' >&2
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
else
printf '%s\n' 'No active plan set.'
fi
exit 0
fi
PLAN_ID="$1"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
echo "Error: plan directory not found: ${PLAN_DIR}" >&2
echo "Run: init-session.sh \"${PLAN_ID}\" to create it, or check .planning/ for available plans." >&2
if ! slug_is_valid "${PLAN_ID}"; then
printf '%s\n' 'Error: invalid plan ID. Use a named directory under .planning.' >&2
exit 1
fi
mkdir -p "${PLAN_ROOT}"
printf "%s\n" "${PLAN_ID}" > "${ACTIVE_FILE}"
echo "Active plan set to: ${PLAN_ID}"
echo "Path: ${PLAN_DIR}"
echo ""
echo "To pin this terminal session only:"
echo " export PLAN_ID=${PLAN_ID}"
PLAN_DIR="${PLAN_ROOT}/${PLAN_ID}"
if [ ! -d "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory not found: ${PLAN_DIR}" \
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
fi
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
# Replace the pointer atomically instead of truncating a possible hardlink.
# mktemp creates a private, exclusive file beside the destination.
temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
printf '%s\n' 'Error: could not create the active plan pointer.' >&2
exit 1
}
trap 'rm -f "${temp_file}"' EXIT
trap 'exit 1' HUP INT TERM
printf '%s\n' "${PLAN_ID}" > "${temp_file}"
# mktemp creates the file 0600; the shared pointer must stay readable by
# every session, so apply the caller's umask instead (=rw without a who
# clause is umask-relative in POSIX chmod).
chmod =rw "${temp_file}" 2>/dev/null || true
if ! mv -f "${temp_file}" "${ACTIVE_FILE}"; then
printf '%s\n' 'Error: could not replace the active plan pointer.' >&2
exit 1
fi
trap - EXIT HUP INT TERM
printf '%s\n' "Active plan set to: ${PLAN_ID}" "Path: ${PLAN_DIR}" '' \
'To pin this terminal session only:' " export PLAN_ID=${PLAN_ID}"
+64
View File
@@ -4,6 +4,70 @@ All notable changes to this project will be documented in this file.
## [Unreleased]
## [3.19.0] - 2026-09-17
### Added
- Named-plan slug mode for `init-session.ps1`. A positional project name or `-PlanDir` creates an isolated `.planning/<date>-<slug>/` plan with collision suffixes, records the shared `.active_plan` pointer, inherits the root `.mode` policy floor, and keeps `-Template`, `-Autonomous` and `-Gated` working. Zero-argument root mode is unchanged. Attestation runs through `attest-plan.ps1` on Windows and `attest-plan.sh` elsewhere, bound to the plan that was just created; root mode ignores an inherited `PLAN_ID` while attesting (#247). Plan ids stay ASCII for names with letters that .NET folds to ASCII, plan files are written with literal paths so a project path containing `[` or `]` works under pwsh, root `.mode` inheritance is case-sensitive like the shell twin, and an empty name stays in root mode.
- `set-active-plan.sh --verify-root` and `set-active-plan.ps1 -VerifyRoot` check that the planning root is inside the project and that the shared pointer is a replaceable regular file, without listing or selecting. Both initializers run it before creating a named plan.
### Fixed
- Session catchup anchors only on exact planning filenames. A write to a lookalike such as `draft_task_plan.md` or `archive-progress.md` no longer counts as a planning update that moves the recovery window forward and hides later context. The OpenCode SQLite lookup is bounded to exact planning paths, revalidated after decoding, and iterated lazily so large write parts are not materialized. OpenCode path matching is now case-sensitive like the JSONL scanners. Applies to the canonical copies and to the Hermes, MastraCode and OpenCode adapters (#248).
- The same exact-basename rule now also covers the root `scripts/session-catchup.py` used by the Claude Code plugin and the five translated `skills/i18n` copies, which the sync tool does not maintain. A new test loads every shipped copy so the boundary cannot drift again in one of them.
### Changed
- A positional project name passed to `init-session.ps1` now creates a named plan under `.planning/` instead of writing the project root, matching `init-session.sh`. The Cursor native PowerShell hooks still read only the root `task_plan.md`, so Cursor users on Windows who want hook injection should keep using zero-argument root mode for now.
### Security
- `init-session.sh` no longer writes `.planning/.active_plan` with shell redirection in slug mode. It validates the physical planning root through `set-active-plan.sh --verify-root` before creating a plan beneath it and replaces the pointer through the selector's contained atomic update. A hardlinked pointer keeps its peer intact, a symlinked pointer is refused, and a planning root that resolves outside the project stops initialization (#249). The check runs in constant time through the selector's new verify mode before anything is created, so a refused pointer leaves no plan directory behind, the replaced pointer keeps a umask-derived mode instead of the 0600 that `mktemp` creates, and an unreadable pointer no longer aborts plan listing.
- `init-session.ps1` applies the same rule through `set-active-plan.ps1`: the planning root is verified before anything is created and the pointer is replaced atomically instead of written in place with `Set-Content`. A missing selector stops named-plan creation, matching the shell initializer.
### Thanks
- @ShaunLinTW, for the PowerShell slug-mode initializer, host-aware attestation, and the Windows PowerShell regression suite in #247.
- @kuei51307-hub, for the exact planning filename boundary across the catchup scanners in #248 and the safe active-pointer replacement in #249.
## [3.18.3] - 2026-09-16
### Fixed
- Completed plans no longer emit routine completion notices through the shared Stop gate or Codex Stop hook. Claude Code plugin and standalone skill hooks inherit this behavior from the canonical shell checker.
- Preserve completion reports from explicit checker commands without the gate flag. Incomplete-plan notices, gate decisions, recursion protection, block caps, stall diagnostics and plan selection safeguards are unchanged. Shell and PowerShell fixes are synchronized across maintained mirrors.
## [3.18.2] - 2026-09-16
### Fixed
- IDE sync verification now fails when an enabled mapping has no canonical source, reports every affected entry, and continues checking the remaining mappings. Verification remains read-only (#244).
### Security
- Run Python in isolated mode in the Codex, Gemini, and GitHub Copilot shell adapters. Project-local modules and Python environment overrides can no longer shadow standard-library imports in these calls. Explicit UTF-8 mode preserves Unicode project paths and error messages on Windows (#245).
### Thanks
- @kuei51307-hub, for missing-source detection and CLI regression coverage in #244.
- @ShaunLinTW, for isolating adapter Python calls and adding import-shadowing regression coverage in #245.
## [3.18.1] - 2026-09-15
### Fixed
- Accept a leading UTF-8 BOM in `.planning/.active_plan` when showing the current plan or listing saved plans. This restores the active marker for pointers written by Windows editors and PowerShell UTF-8 workflows. The fix ships across all canonical shell helper copies (#243).
### Thanks
- @kuei51307-hub, for the BOM compatibility fix and regression coverage in #243.
## [3.18.0] - 2026-09-13
### Added
- List saved named plans with `set-active-plan.sh --list` or PowerShell `set-active-plan.ps1 -List`. The output shows plan IDs, phase counts, and the shared default pointer without selecting a plan or attaching a session (#242).
- The canonical helpers and usage instructions ship across the supported IDE and language bundles, including OpenCode, Mastracode, and Hermes. Kiro's separate `.kiro/plan` layout is documented as outside this inventory.
### Fixed
- Count each phase once across mixed inline and explicit status formats, including the shipped translated templates. Ignore fenced examples, indented status examples, and unrelated sections.
- Support native PowerShell file invocation, empty files, and Windows PowerShell 5.1 startup from project paths containing brackets.
### Security
- Validate plan IDs and canonicalize the planning directory, listed directories, plan files, and pointer before reading. Symlink and junction paths outside the current project are rejected.
- Replace the shared pointer atomically, preserving external hardlinked files. A failed write returns an error without reporting that the plan was selected.
### Thanks
- @Dphoshoba, for the original implementation and plan-listing proposal in #242.
## [3.17.2] - 2026-09-09
### Fixed
+2 -2
View File
@@ -7,8 +7,8 @@ authors:
- family-names: Adi
given-names: Ahmad Othman Ammar
alias: OthmanAdi
version: "3.17.2"
date-released: "2026-09-09"
version: "3.19.0"
date-released: "2026-09-17"
license: MIT
url: "https://github.com/OthmanAdi/planning-with-files"
repository-code: "https://github.com/OthmanAdi/planning-with-files"
+9 -1
View File
@@ -32,7 +32,15 @@ Before opening a pull request, run the test suite:
python -m pytest tests/ -q
```
Two pre-existing Windows exec-bit test failures may appear on Windows. If those are the only failures, note that in your pull request description.
Investigate test failures and include any unresolved findings in your pull request description.
## CI completion rule
Maintainer delivery is complete only after all five `Tests` jobs succeed on the final commit pushed to `master`: pytest on Linux, Windows and macOS, plus the Pi extension and OpenCode plugin suites.
After the final push, verify the remote `master` commit and wait for its workflow to finish. Queued, running, cancelled, timed-out, failed or missing checks mean verification is unfinished. Continue investigating, fixing and rerunning until every job is green. Preserve test coverage and security checks; change runtime limits only when measured runtime justifies a bounded adjustment.
A passing candidate branch or an identical Git tree does not replace checks on the final pushed commit. Recheck remote `master` and its check results immediately before reporting completion. If the user explicitly stops the work or an external blocker prevents progress, record the unfinished checks and the blocker.
## Project layout
+15 -2
View File
@@ -106,6 +106,19 @@ These amazing people have contributed code, documentation, or significant improv
### Other Contributors
- **[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)
- 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.
- **[@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)
- 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.
- **[@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.
- **[@sunznx](https://github.com/sunznx)**, [Issue #240](https://github.com/OthmanAdi/planning-with-files/issues/240), [Issue #241](https://github.com/OthmanAdi/planning-with-files/issues/241)
- Reported and reproduced named-plan crossover between Codex sessions sharing a working directory after compaction.
- Reported the 13 duplicate Codex command skills, traced the legacy command fallback, and proposed the native manifest setting that disables it.
@@ -425,6 +438,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
---
**Total Contributors:** 59+ and growing!
**Total Contributors:** 62+ and growing!
*Last updated: 2026-09-09*
*Last updated: 2026-09-17*
+11 -2
View File
@@ -2,7 +2,9 @@
<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%">
</div>
<h1 align="center">Planning with Files</h1>
<h1 align="center">
Planning with Files&nbsp;&nbsp;&nbsp;<a href="https://trendshift.io/repositories/17191" title="Trendshift: #1 daily across all languages, January 6, 2026"><img src="https://trendshift.io/api/badge/trendshift/repositories/17191/daily" alt="Trendshift: #1 Repository of the Day across all languages" width="250" height="55" align="middle"></a>
</h1>
<p align="center">
<strong>The planning skill your agent cannot ignore.</strong><br>
@@ -354,6 +356,11 @@ One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from
| Version | Highlights |
|---------|------------|
| **v3.19.0** | Adds PowerShell named-plan slug mode (#247), anchors session catchup only on exact planning filenames across every shipped copy (#248), and replaces active-plan pointers through the selectors with planning-root containment in both initializers (#249). |
| **v3.18.3** | Silences completed-plan notices in shared Stop gates and Codex while preserving explicit reports and gate safeguards. |
| **v3.18.2** | Isolates Python in Codex, Gemini, and Copilot shell adapters and makes IDE sync verification fail on missing canonical sources (#244, #245). |
| **v3.18.1** | Fixes active-plan display and listing for UTF-8 BOM-prefixed pointers from Windows editors and PowerShell workflows across the canonical shell helpers (#243). |
| **v3.18.0** | Lists saved plans and phase counts with `--list` or PowerShell `-List` (#242). Supports the shipped translated templates, checks project containment, and delivers the canonical helpers across IDE bundles. |
| **v3.17.2** | Fixes #241: the native Codex manifest disables legacy command migration, removing 13 redundant `source-command-*` skills from plugin installs. The canonical planning skill, Codex hooks, and Claude commands remain available. |
| **v3.17.1** | Fixes #240: two named plans in the same project now require `PLAN_ID`, even without `.planning/sessions/`. A shared pointer or newest-plan guess cannot redirect a Codex session across compaction. Ambiguous hooks inject no plan and Stop does not gate against a guessed plan. |
| **v3.17.0** | **Every Claude Code hook fire forked about 130 processes, and under Git Bash on Windows that took 7 to 12 seconds against the 10 second hook timeout.** Claude Code discarded the plan context ("UserPromptSubmit hook timed out after 10s") and every Bash, Read, Grep and Edit call waited 5 more seconds in PreToolUse before it ran. Linux and macOS never showed it because a fork costs milliseconds there. The events now run in one Python process, `scripts/inject-plan.py`, a byte-identical twin of the shell chain proven by a parity suite on all three CI legs, with the shell chain kept as the reference and as the fallback for hosts without Python: 0.3 s per prompt and per tool call on the reporting machine. Hook interpreters now start in isolated mode, so a repository's own `secrets.py` or `hashlib.py` is never imported by a hook. `PWF_FAST_PATH=0` forces the shell chain. |
@@ -514,7 +521,7 @@ Hermes' own `skills-guard` scanner rates the Hermes bundle `SAFE`; the canonical
> **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.
- **Plan isolation per task.** `init-session.sh "<name>"` gives each parallel task its own `.planning/YYYY-MM-DD-<slug>/` directory; `PLAN_ID` pins a terminal to one of them, `set-active-plan.sh` switches the shared pointer.
- **Plan isolation per task.** `init-session.sh "<name>"` gives each parallel task its own `.planning/YYYY-MM-DD-<slug>/` directory; `PLAN_ID` pins a terminal to one of them, `set-active-plan.sh --list` shows available plans and phase counts, and `set-active-plan.sh <id>` switches the shared pointer.
- **Threads whose cwd is a shared parent.** `PWF_PLAN_ROOT=<absolute path>` binds an agent thread to the project that owns the plan; an ambiguous cwd, where a nested project carries its own planning state, injects nothing rather than guessing.
- **Session attachment.** An `.attached` marker authorizes context but does not select a task. In the Codex, Hermes, Pi, and standalone hook routes, armed isolation with multiple plans requires `PLAN_ID`; otherwise context is refused. A project-root pin alone cannot distinguish tasks within that root.
- **Parallel-write guard.** The next turn warns if checked items or completed phases decrease. This is an advisory check after the write, not a lock or merge mechanism. It does not detect every overwritten plan, `progress.md`, or `findings.md`.
@@ -523,6 +530,8 @@ Hermes' own `skills-guard` scanner rates the Hermes bundle `SAFE`; the canonical
The contract and the `.mode` tokens are specified in the skill itself ([SKILL.md, Autonomous and Gated Modes](skills/planning-with-files/SKILL.md#autonomous-and-gated-modes-v3)) and in [docs/long-running-agent-tasks.md](docs/long-running-agent-tasks.md).
To find a saved plan, run the installed `scripts/set-active-plan.sh --list` helper from your project directory, or `scripts/set-active-plan.ps1 -List` in PowerShell. It lists named plans under that project's `.planning/` directory, with phase counts for the shipped English and translated templates. `[active]` marks the shared default pointer. Listing does not select a plan or attach a session; use the displayed ID as `PLAN_ID` before starting a concurrent task. Kiro's separate `.kiro/plan` layout is not part of this inventory.
## How It Works
The agent stops at the first rung that applies:
+12
View File
@@ -77,6 +77,13 @@ Use slug-mode for parallel sessions:
./scripts/init-session.sh "Incident Investigation"
```
On Windows PowerShell, the equivalent named-plan flow is:
```powershell
.\scripts\init-session.ps1 "Backend Refactor"
.\scripts\init-session.ps1 "Incident Investigation"
```
Each slug gets its own isolated files:
```text
@@ -94,5 +101,10 @@ export PLAN_ID=2026-01-10-backend-refactor
sh scripts/attest-plan.sh
```
```powershell
$env:PLAN_ID = "2026-01-10-backend-refactor"
.\scripts\attest-plan.ps1
```
Slug-mode avoids same-file contention by giving each session its own
`task_plan.md` and `.attestation` file.
+2 -2
View File
@@ -172,11 +172,11 @@ Neither failure printed anything. A user running this on Windows would see no ca
Session init, phase-status counting, attestation lock/show/clear, tamper detection logic itself (once the injection guard reaches it), and parallel-plan directory resolution (`$PLAN_ID` env var, `.active_plan` file, newest-mtime fallback) all produced correct output in both Git Bash and PowerShell, including the v3 autonomous-mode chain (nonce-framed delimiters, unattested-plan refusal, per-tool-call injection suppression).
One asymmetry noted but not a bug: `init-session.ps1` has no slug mode (it always writes to the project root), only `init-session.sh` creates `.planning/<slug>/` directories. And there is no `inject-plan.ps1`; the injection and tamper-enforcement hook body is sh-only, so a pure-PowerShell host without Git Bash gets no plan injection or tamper enforcement at all.
At the time of this v3.2.0 evaluation, `init-session.ps1` had no slug mode (it always wrote to the project root), while `init-session.sh` created `.planning/<slug>/` directories. The canonical/shared English PowerShell initializer now supports the same named-plan and `-PlanDir` isolation flow, including active-plan selection and v3 mode inheritance. There is still no `inject-plan.ps1`; the injection and tamper-enforcement hook body is sh-only, so a pure-PowerShell host without Git Bash gets no plan injection or tamper enforcement at all.
### Fixed in v3.2.0
Both `session-catchup.py` and `inject-plan.sh` were fixed (see CHANGELOG). Re-running the same sequence after the fix confirmed session-catchup now produces a correct catchup report from real session logs, and plan injection now reaches the tamper-check branch under the same aliased-path conditions that previously went silent. The PowerShell-only injection gap and the `init-session.ps1` slug-mode asymmetry are open follow-ups, not addressed in this cycle.
Both `session-catchup.py` and `inject-plan.sh` were fixed (see CHANGELOG). Re-running the same sequence after the fix confirmed session-catchup now produces a correct catchup report from real session logs, and plan injection now reaches the tamper-check branch under the same aliased-path conditions that previously went silent. The PowerShell-only injection gap remains an open follow-up; the `init-session.ps1` slug-mode asymmetry described above was corrected later and is covered by Windows PowerShell regression tests.
### Current session-catchup boundary

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