Compare commits

...
12 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
130 changed files with 4956 additions and 772 deletions
+2 -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.18.2"
version: "3.19.0"
---
# Planning with Files
@@ -365,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]:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
+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.18.2"
"version": "3.19.0"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.18.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.18.2"
version: "3.19.0"
---
@@ -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]:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.18.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 -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
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.2"
version: "3.19.0"
---
@@ -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]:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
@@ -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]:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.2"
version: "3.19.0"
---
@@ -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]:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.18.2"
version: "3.19.0"
---
# Planning with Files
@@ -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]:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
@@ -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]:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
+1 -1
View File
@@ -2,7 +2,7 @@
name: planning-with-files
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
metadata:
version: "3.18.2"
version: "3.19.0"
hermes:
tags: [planning, long-running-tasks, context-engineering, workflow]
---
@@ -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:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
@@ -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.18.2"
version: "3.19.0"
---
@@ -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
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
@@ -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.18.2"
version: "3.19.0"
---
@@ -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]:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
+1 -1
View File
@@ -366,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.18.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]:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
+27
View File
@@ -4,6 +4,33 @@ 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
+2 -2
View File
@@ -7,8 +7,8 @@ authors:
- family-names: Adi
given-names: Ahmad Othman Ammar
alias: OthmanAdi
version: "3.18.2"
date-released: "2026-09-16"
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"
+6 -3
View File
@@ -106,12 +106,15 @@ 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)
- **[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)
- **[@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.
@@ -437,4 +440,4 @@ If you've contributed and don't see your name here, please open an issue! We wan
**Total Contributors:** 62+ and growing!
*Last updated: 2026-09-16*
*Last updated: 2026-09-17*
+2
View File
@@ -356,6 +356,8 @@ 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. |
+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
+14 -1
View File
@@ -68,7 +68,20 @@ If you have Git for Windows installed, run scripts in Git Bash:
wsl ./scripts/init-session.sh
```
### Option 3: Manual alternative
### Option 3: Native PowerShell
`init-session.ps1` is the PowerShell twin of the shell initializer. Since v3.19.0 it supports the same named-plan flow for parallel sessions:
```powershell
.\scripts\init-session.ps1 # legacy root mode: task_plan.md next to your code
.\scripts\init-session.ps1 "Backend Refactor" # named plan under .planning\<date>-backend-refactor\
.\scripts\init-session.ps1 -PlanDir # named plan with a generated untitled-<id> slug
.\scripts\set-active-plan.ps1 -List # list named plans and the shared pointer
```
A positional project name creates a named plan, matching `init-session.sh`. The Cursor native PowerShell hooks still read only the root `task_plan.md`, so use zero-argument root mode there if you rely on hook injection.
### Option 4: Manual alternative
Instead of running scripts, manually create the files:
+4 -2
View File
@@ -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.')
+6 -3
View File
@@ -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."
+185 -24
View File
@@ -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
}
}
}
+23 -2
View File
@@ -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 ""
+54 -19
View File
@@ -27,6 +27,20 @@ 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.
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
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.
@@ -340,11 +354,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:
@@ -437,7 +450,15 @@ def extract_messages_from_session(session_file: Path, after_line: int = -1) -> L
return result
PLANNING_LIKE = ('%task_plan.md', '%findings.md', '%progress.md')
def _load_opencode_part(data_str: object) -> Optional[Dict]:
"""Decode one OpenCode part record; malformed rows are skipped, not fatal."""
if not isinstance(data_str, str):
return None
try:
data = json.loads(data_str)
except (json.JSONDecodeError, TypeError, ValueError):
return None
return data if isinstance(data, dict) else None
def get_opencode_db_path() -> Optional[Path]:
@@ -570,28 +591,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
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 = _load_opencode_part(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:
+25 -1
View File
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
+36 -8
View File
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-ar/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.18.2"
version: "3.19.0"
---
# نظام تخطيط الملفات
@@ -412,12 +412,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]:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}
@@ -1,6 +1,6 @@
#!/bin/sh
# List saved named plans, show the shared pointer, or change that pointer.
# Usage: set-active-plan.sh [--list|-l|PLAN_ID]
# 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"
@@ -220,8 +220,32 @@ phase_status() {
' < "$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() {
if [ -f "${ACTIVE_FILE}" ] && is_within_root "${ACTIVE_FILE}"; then
# 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.
@@ -268,15 +292,17 @@ list_plans() {
}
if [ "$#" -gt 1 ]; then
printf '%s\n' 'Error: list plans or set PLAN_ID in separate calls.' >&2
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|PLAN_ID]' \
'Lists saved named plans in the current project without selecting a plan.'
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
@@ -311,9 +337,7 @@ 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
# A pre-existing pointer must itself be a contained regular file before writing.
if { [ -e "${ACTIVE_FILE}" ] || [ -L "${ACTIVE_FILE}" ]; } &&
{ [ -L "${ACTIVE_FILE}" ] || [ ! -f "${ACTIVE_FILE}" ] || ! is_within_root "${ACTIVE_FILE}"; }; then
if pointer_is_unsafe; then
printf '%s\n' 'Error: active plan pointer is not a safe file inside the project.' >&2
exit 1
fi
@@ -326,6 +350,10 @@ temp_file="$(mktemp "${PLAN_ROOT}/.active_plan.XXXXXX")" || {
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
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files-de/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.18.2"
version: "3.19.0"
---
# Dateiplanungssystem
@@ -414,12 +414,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]:
@@ -5,12 +5,16 @@
# .\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
)
@@ -213,7 +217,27 @@ function Show-PlanList {
}
if ($Help -or $PlanId -eq "--help" -or $PlanId -eq "-h") {
Write-Output "Usage: set-active-plan.ps1 [-List|-l|--list|PLAN_ID]"
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
}

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