Compare commits

..
9 Commits
Author SHA1 Message Date
OthmanAdi 57fe376da9 release: v3.20.3
A symlinked or junctioned directory under .planning/ is never a plan on
any route (#270, PR #271 by @ShaunLinTW plus three maintainer commits).

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

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

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

Tests: the sh/py parity suite gains the linked-directory fixture (the twin
contract), and test_unarmed_plan_ambiguity drives both resolvers and both
injectors over a real plan plus a junction or symlink (#270).
2026-09-19 10:43:59 +02:00
Shaun Lin 0bbc43cff3 fix: skip linked plan dirs in ambiguity counts 2026-09-19 10:36:51 +02:00
OthmanAdi f01a88a12b release: v3.20.2
Hermes plugin 0.2.2: the launch-directory notice for the Hermes 0.21.3
first-turn TERMINAL_CWD rewrite, the /pwf-status and /pwf diagnostics,
and PWF_PLAN_ROOT honored by the slash commands (#272).

Parity set bumped to 3.20.2 with scripts/bump-version.py. CHANGELOG,
CONTRIBUTORS.md (@ericshunhinglee-cloud), README releases row,
CITATION.cff date.
2026-09-19 09:59:30 +02:00
OthmanAdi 9a3843b31d docs(hermes): describe the Hermes 0.21.3 working-directory rewrite and the pin
Adds the section on the first-turn TERMINAL_CWD rewrite: the mechanism,
what was reproduced with the 0.21.0 source, what the plugin says since
v3.20.2, the PWF_PLAN_ROOT pin for project-scoped CLI sessions, the
shell-hook route as the unaffected alternative, and the home-directory
inverse risk (#272).
2026-09-19 09:57:44 +02:00
OthmanAdi 1528b31d7f fix(hermes): name the launch directory plan when the host re-homes the working directory
On Hermes 0.21.3 the first turn of a CLI session rewrites the
process-global TERMINAL_CWD to the home directory (agent/relay_runtime.py
imports gateway/run.py lazily, whose import-time bridge applies the
Path.home() fallback), so resolve_agent_cwd() names HOME, the hooks find
no plan there and inject nothing. The rewrite runs before the first
plugin hook, so the plugin cannot recover the root and does not guess.

pre_llm_call now injects one line naming the resolved directory, the
launch directory that holds a plan, and the PWF_PLAN_ROOT pin instead of
returning nothing. CLI only; silent for hermes -w worktree sessions
(TERMINAL_CWD at <repo>/.worktrees/<name> without a chdir is intended),
for a launch directory without planning state, and for a launch
directory whose session isolation refuses the session.

/pwf and /pwf-status honor PWF_PLAN_ROOT like the hooks and report a pin
that does not resolve instead of acting in the directory Hermes named.
/pwf-status prints the same line under "No planning files found", and
/pwf appends it when the plan it created went somewhere other than a
launch directory that already holds one.

Fixes #272. Upstream: NousResearch/hermes-agent#86411, #95577.
2026-09-19 09:57:38 +02:00
135 changed files with 1758 additions and 217 deletions
+1 -1
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.1"
version: "3.20.3"
---
# Planning with Files
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,23 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory carries and which are not links to sh.
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +175,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +195,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -198,7 +218,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +231,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
+1 -1
View File
@@ -10,7 +10,7 @@
"name": "planning-with-files",
"source": "./",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Installs across 60+ agents.",
"version": "3.20.1"
"version": "3.20.3"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.20.1",
"version": "3.20.3",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Works across 60+ agents and includes Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese.",
"author": {
"name": "OthmanAdi",
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"${CODEBUDDY_PLUGIN_ROOT}/scripts/skill-hook.sh\" \"$HOME/.codebuddy/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.1"
version: "3.20.3"
---
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,23 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory carries and which are not links to sh.
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +175,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +195,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -198,7 +218,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +231,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.20.1",
"version": "3.20.3",
"description": "Persistent project planning for Codex. Opt-in lifecycle hooks inject selected plan context; automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs Markdown-declared commands. No network upload path.",
"author": {
"name": "OthmanAdi",
+25
View File
@@ -90,6 +90,27 @@ def _is_reparse_or_link(path: Path) -> bool:
return bool(attrs & reparse)
_LINK_REPARSE_TAGS = (0xA000000C, 0xA0000003) # IO_REPARSE_TAG_SYMLINK, _MOUNT_POINT
def _is_linked_directory(path: Path) -> bool:
"""`[ -L ]` of the shell scripts: a symlink, or a junction on Windows.
Narrower than _is_reparse_or_link on purpose: OneDrive Files On-Demand
marks every synced directory as a reparse point, and those are plans.
"""
try:
info = path.lstat()
except OSError:
return False
if stat.S_ISLNK(info.st_mode):
return True
reparse = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
if getattr(info, "st_file_attributes", 0) & reparse:
return getattr(info, "st_reparse_tag", 0) in _LINK_REPARSE_TAGS
return False
def _is_trusted_darwin_system_alias(path: Path) -> bool:
"""Admit only macOS's fixed root aliases after verifying their targets."""
if sys.platform != "darwin":
@@ -243,6 +264,10 @@ def session_plan_requires_binding(root: Path) -> bool:
for child in planning_dir.iterdir():
if not _PLAN_SLUG.fullmatch(child.name) or not child.is_dir():
continue
# A linked plan directory is not selectable and never counts,
# matching `[ -L ]` in the shell counters (#270).
if _is_linked_directory(child):
continue
if (child / "task_plan.md").is_file():
candidates += 1
if candidates > 1:
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.1"
version: "3.20.3"
---
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,23 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory carries and which are not links to sh.
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +175,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +195,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -198,7 +218,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +231,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -139,6 +139,23 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory carries and which are not links to sh.
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +175,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +195,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -198,7 +218,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +231,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.1"
version: "3.20.3"
---
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,23 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory carries and which are not links to sh.
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +175,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +195,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -198,7 +218,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +231,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -188,8 +188,14 @@ describe("resolver", () => {
fs.writeFileSync(path.join(planning, ".active_plan"), "2026-09-02-evil\n")
expect(resolvePlan(root, {}, env).planDir).toBeNull()
expect(resolvePlan(root, {}, { ...env, PLAN_ID: "2026-09-02-evil" }).planDir).toBeNull()
// a linked plan directory never counts toward the several-plans rule (#270)
expect(countSelectablePlans(root)).toBe(0)
const real = path.join(planning, "2026-09-02-real")
fs.mkdirSync(real)
fs.writeFileSync(path.join(real, "task_plan.md"), "# REAL\n")
expect(countSelectablePlans(root)).toBe(1)
expect(resolvePlan(root, {}, env).planDir).toBe(real)
fs.rmSync(path.join(real, "task_plan.md"))
try {
fs.symlinkSync(path.join(outside, "task_plan.md"), path.join(real, "task_plan.md"), "file")
} catch {
@@ -205,6 +205,9 @@ export function countSelectablePlans(root: string): number {
}
for (const entry of entries) {
if (!slugIsValid(entry)) continue
// A linked plan directory is not selectable and never counts (#270),
// matching the shell counters, the Hermes plugin and resolvePlan below.
if (!isRealDir(path.join(planningRoot, entry))) continue
if (!isRegularFile(path.join(planningRoot, entry, "task_plan.md"))) continue
count += 1
if (count > 1) break
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.1"
version: "3.20.3"
---
# Planning with Files
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,23 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory carries and which are not links to sh.
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +175,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +195,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -198,7 +218,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +231,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -139,6 +139,23 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory carries and which are not links to sh.
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +175,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +195,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -198,7 +218,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +231,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -1,12 +1,21 @@
from __future__ import annotations
import importlib
import json
import os
import shlex
from pathlib import Path
from typing import Any
from .hooks import post_tool_call, pre_llm_call, pre_verify
from .paths import normalize_cwd, plugin_skill_dir
from .hooks import (
WORKTREES_DIR_NAME,
launch_dir_has_planning_state,
launch_dir_notice,
post_tool_call,
pre_llm_call,
pre_verify,
)
from .paths import effective_project_root, normalize_cwd, plan_root_is_pinned, plugin_skill_dir
from .tools import (
planning_with_files_check_complete,
planning_with_files_init,
@@ -14,10 +23,25 @@ from .tools import (
)
SLASH_COMMANDS = ("pwf", "pwf-status", "plan-status")
BROKEN_PIN_MESSAGE = (
"planning-with-files: PWF_PLAN_ROOT is set but does not resolve to an absolute, "
"existing directory; nothing done."
)
def _command_cwd() -> Path:
"""Project directory for a slash command: the Hermes session cwd, else the process cwd."""
def _command_cwd() -> Path | None:
"""Project directory for a slash command.
The PWF_PLAN_ROOT pin wins, exactly as it does for the hooks, and a broken
pin returns None instead of a fallback (issue #272: on Hermes 0.21.3 the
session cwd can name the home directory, and a pinned operator must not
get a plan created or reported there). Without a pin: the Hermes session
cwd, else the process cwd. A command handler receives only its arguments,
no platform or session, so the CLI-only launch-directory rule of the hooks
cannot be applied here; the pin is the documented answer for commands.
"""
if plan_root_is_pinned():
return effective_project_root(normalize_cwd())
try:
from agent.runtime_cwd import resolve_agent_cwd
@@ -81,6 +105,8 @@ def pwf_command(raw_args: str = "") -> str:
name_parts.append(token)
index += 1
project_dir = _command_cwd()
if project_dir is None:
return BROKEN_PIN_MESSAGE
result = json.loads(
planning_with_files_init(
template=template, cwd=str(project_dir), name=" ".join(name_parts), mode=mode
@@ -97,14 +123,61 @@ def pwf_command(raw_args: str = "") -> str:
if result.get("attestation"):
lines.append(f" attested: sha256 {result['attestation'][:12]}...")
lines.append(" next: read task_plan.md, findings.md and progress.md, then fill in the goal and phases.")
if not plan_root_is_pinned():
# Issue #272: the plan just went where Hermes pointed while the launch
# directory already holds one; say so instead of leaving two plans apart.
hint = _launch_dir_hint(project_dir)
if hint:
lines.append(hint)
return "\n".join(lines)
def status_command(raw_args: str = "") -> str:
"""/pwf-status and /plan-status: compact planning state for the current project."""
project_dir = _command_cwd()
if project_dir is None:
return BROKEN_PIN_MESSAGE
payload = json.loads(planning_with_files_status(cwd=str(project_dir)))
return _format_status(payload)
report = _format_status(payload)
if not payload.get("exists") and not plan_root_is_pinned():
hint = _launch_dir_hint(project_dir)
if hint:
report = "\n".join((report, hint))
return report
def _session_cwd_is_pinned() -> bool:
"""True when Hermes pinned this context's cwd per session (``agent.runtime_cwd._SESSION_CWD``).
A pinned context runs in a multi-session backend whose process cwd is the
backend's start directory, not a launch directory, so the hint would
compare the wrong things. Prompt turns on the TUI and Desktop carry the
pin; their plugin command dispatch does not, so this is a best-effort
exemption. Read-only inspection; any failure counts as not pinned.
"""
try:
value = importlib.import_module("agent.runtime_cwd")._SESSION_CWD.get()
except Exception: # noqa: BLE001 - a host without the pin keeps the hint
return False
return isinstance(value, str) and bool(value.strip())
def _launch_dir_hint(project_dir: Path) -> str:
"""Issue #272 diagnostic for the slash commands: name the launch directory's plan.
Read-only and platform-blind (a command handler has no platform), so it is
a hint under the report, never a refusal. Worktree sessions and sessions
whose cwd Hermes pinned per session are exempt.
"""
if WORKTREES_DIR_NAME in project_dir.parts or _session_cwd_is_pinned():
return ""
try:
launch = normalize_cwd(os.getcwd())
if not launch.is_dir() or launch == project_dir or not launch_dir_has_planning_state(launch):
return ""
except (OSError, RuntimeError, ValueError):
return ""
return launch_dir_notice(project_dir, launch)
def _register_commands(ctx: Any) -> None:
@@ -54,6 +54,66 @@ def _runtime_project_dir(kwargs: dict[str, Any]) -> Path | None:
return effective_project_root(project)
WORKTREES_DIR_NAME = ".worktrees" # hermes -w and /worktree new place trees at <repo>/.worktrees/<name>
def launch_dir_has_planning_state(launch: Path) -> bool:
"""True when the process launch directory holds a plan, or several plans.
A plan with a nested-root conflict still counts (``explicit=True`` skips
only that check), because the question here is whether the directory the
session was started in carries planning state at all.
"""
return (
resolve_plan(launch, explicit=True)[0] is not None
or multiple_plans_require_selector(launch)
)
def launch_dir_notice(project_dir: Path, launch: Path) -> str:
"""The once-per-turn line for issue #272; the resolved root and the launch directory differ."""
return (
f"[planning-with-files] Hermes resolved {project_dir} as the working directory, "
f"but the launch directory {launch} holds a plan. Nothing injected. "
f"Pin the thread with PWF_PLAN_ROOT={launch}."
)
def _launch_dir_notice(project_dir: Path, kwargs: dict[str, Any]) -> str | None:
"""Issue #272: the resolved root holds no plan while the launch directory does.
Hermes 0.21.3 rewrites the process-global TERMINAL_CWD during the first
turn of a CLI session (``agent/relay_runtime.py`` imports ``gateway/run.py``
lazily; its import-time bridge applies the ``Path.home()`` fallback), so
``resolve_agent_cwd`` names the home directory while ``os.getcwd()`` still
names the directory the session was started in (upstream hermes-agent
#86411 and #95577). The rewrite runs before the first hook, so the adapter
cannot recover the root on its own and never switches to the launch
directory: it says why nothing was injected and names the pin.
Silent by design: platforms other than the CLI (their process cwd is not a
launch directory), Hermes worktree sessions (``hermes -w`` points
TERMINAL_CWD at ``<repo>/.worktrees/<name>`` without a chdir, which is the
intended split), a launch directory without planning state, and a launch
directory whose session isolation refuses this session anyway.
"""
if str(kwargs.get("platform", "")).strip().lower() != "cli":
return None
if WORKTREES_DIR_NAME in project_dir.parts:
return None
try:
launch = normalize_cwd(os.getcwd())
if not launch.is_dir() or launch == project_dir:
return None
if _session_attachment(launch, _session_id(kwargs)) == ATTACH_DETACHED:
return None
if not launch_dir_has_planning_state(launch):
return None
except (OSError, RuntimeError, ValueError):
return None
return launch_dir_notice(project_dir, launch)
def _session_attachment(project_dir: Path, session_id: str) -> str:
"""Opt-in isolation state once a project creates its sessions directory."""
sessions_dir = project_dir / ".planning" / "sessions"
@@ -174,6 +234,10 @@ def pre_llm_call(**kwargs: Any) -> dict[str, str] | None:
return {"context": MULTIPLE_PLANS_NOTICE}
if conflicts:
return {"context": ambiguity_notice(conflicts)}
if not plan_root_is_pinned():
notice = _launch_dir_notice(project_dir, kwargs)
if notice:
return {"context": notice}
return None
user_message = str(kwargs.get("user_message", ""))
reminder_messages = pop_reminders(project_dir, session_id)
+4 -1
View File
@@ -290,7 +290,10 @@ def resolve_plan(
continues through .planning/.active_plan, the newest
.planning/<slug>/task_plan.md by modification time, then the legacy root
task_plan.md. Slugs are validated and the chosen directory must stay
inside .planning (no symlink or junction escape).
inside .planning (no symlink or junction escape). A linked plan directory
never counts and never resolves here; since v3.20.3 the shell family, the
Python twin, the Codex adapter and the OpenCode and DSH cores apply the
same rule (#270).
A cwd guess (pointer, newest, or legacy root) is refused when a direct
child of the root carries its own live plan (issue #212): the result is
@@ -1,5 +1,5 @@
name: planning-with-files
version: 0.2.1
version: 0.2.2
description: Hermes adapter for persistent project planning and selected context injection. Resolves root and .planning/<slug> plans, injects the attested plan each turn, reminds after writes, and registers /pwf and /pwf-status. Optional gated mode can request continuation only through the Hermes pre_verify hook, bounded by agent.max_verify_nudges; legacy plans stay advisory. Explicit catchup modes read same-project local session records for aggregate counts or bounded replay. No network upload path.
author: planning-with-files contributors
provides_tools:
+1 -1
View File
@@ -2,7 +2,7 @@
name: planning-with-files
description: "Persistent file-based planning for multi-step AI-agent work. Keeps task_plan.md, findings.md, and progress.md on disk; lifecycle hooks inject selected project planning context. Automatic recovery reads project planning files only. Explicit session-catchup.py --metadata reads same-project local agent session records and emits aggregate counts only; --replay may emit bounded nonce-framed excerpts. Optional gated mode can request continuation only when the host supports it and never runs commands declared in Markdown. The skill has no network upload path. Use for research or work needing 5+ tool calls."
metadata:
version: "3.20.1"
version: "3.20.3"
hermes:
tags: [planning, long-running-tasks, context-engineering, workflow]
---
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.mastracode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.1"
version: "3.20.3"
---
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
@@ -188,8 +188,14 @@ describe("resolver", () => {
fs.writeFileSync(path.join(planning, ".active_plan"), "2026-09-02-evil\n")
expect(resolvePlan(root, {}, env).planDir).toBeNull()
expect(resolvePlan(root, {}, { ...env, PLAN_ID: "2026-09-02-evil" }).planDir).toBeNull()
// a linked plan directory never counts toward the several-plans rule (#270)
expect(countSelectablePlans(root)).toBe(0)
const real = path.join(planning, "2026-09-02-real")
fs.mkdirSync(real)
fs.writeFileSync(path.join(real, "task_plan.md"), "# REAL\n")
expect(countSelectablePlans(root)).toBe(1)
expect(resolvePlan(root, {}, env).planDir).toBe(real)
fs.rmSync(path.join(real, "task_plan.md"))
try {
fs.symlinkSync(path.join(outside, "task_plan.md"), path.join(real, "task_plan.md"), "file")
} catch {
@@ -205,6 +205,9 @@ export function countSelectablePlans(root: string): number {
}
for (const entry of entries) {
if (!slugIsValid(entry)) continue
// A linked plan directory is not selectable and never counts (#270),
// matching the shell counters, the Hermes plugin and resolvePlan below.
if (!isRealDir(path.join(planningRoot, entry))) continue
if (!isRegularFile(path.join(planningRoot, entry, "task_plan.md"))) continue
count += 1
if (count > 1) break
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/skill-hook.sh\" \"${CLAUDE_SKILL_DIR}/scripts/skill-hook.sh\" \"$HOME/.config/opencode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.opencode/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/skill-hook.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/skill-hook.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --event=precompact; exit 0"
metadata:
version: "3.20.1"
version: "3.20.3"
---
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.20.1",
"version": "3.20.3",
"description": "Persistent project planning with selected context injection. Automatic recovery uses project files only; explicit catchup modes read same-project local session records for aggregate counts or bounded replay. The host-aware gate never runs Markdown-declared commands. No network upload path. Ships the skill plus a Pi Coding Agent extension.",
"keywords": [
"pi-package",
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,23 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory carries and which are not links to sh.
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +175,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +195,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -198,7 +218,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +231,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
+19
View File
@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
## [Unreleased]
## [3.20.3] - 2026-09-19
### Fixed
- A symlinked or junctioned directory under `.planning/` is never a plan, on every route that resolves plans. `inject-plan.sh` and `resolve-plan-dir.sh --check-ambiguity` counted a linked plan directory toward the several-plans rule while the Hermes plugin did not, so the shell route refused a tree that Hermes injected (#270). The counters now skip linked directories (PR #271). Skipping the link in the counter alone left the selection paths following it through containment: one real plan plus a newer linked one counted as one plan and the newest-mtime scan then selected the linked directory, the mtime guess the #240 rule exists to prevent. The shell family (`resolve-plan-dir.sh`, `inject-plan.sh`, `resolve-plan-dir.ps1`, the Python twin `inject-plan.py`) therefore refuses a linked plan directory in the `PLAN_ID`, `.active_plan` and newest-mtime branches as well; a `PLAN_ID` that names one fails closed with the existing "does not name a plan directory" notice, and a pointer that names one falls through like a stale pointer. The Codex adapter and the OpenCode and DeepSeek Harness plugin cores skip linked directories in their counters, which their selection already did. `set-active-plan.sh` and `set-active-plan.ps1` refuse to point the shared default at a linked directory and leave it out of `--list`. The link test is symlink or junction only (`[ -L ]`, `is_link`, `LinkType`), never the bare ReparsePoint attribute: OneDrive Files On-Demand marks every synced directory as a reparse point, and those stay plans. Untouched on purpose: the Pi extension keeps its armed-only containment rule, and the nested-root probes still count a linked nested plan as a conflict, which only ever refuses. Every shipped copy is synced; the sh/py parity suite, the cross-route ambiguity suite and the pointer tool suite carry the linked-directory fixture (junction on Windows, symlink elsewhere).
### Thanks
- @ShaunLinTW, for the shell counter change with the Hermes differential regression in #271.
## [3.20.2] - 2026-09-19
### Fixed
- Hermes plugin: on Hermes 0.21.3 the host rewrites the process-global `TERMINAL_CWD` to the home directory during the first turn of a CLI session (`agent/relay_runtime.py` imports `gateway/run.py` lazily, and that module's import-time bridge applies the `Path.home()` fallback for an empty or placeholder `terminal.cwd`), so `resolve_agent_cwd()` named the home directory, the hooks found no plan there and injected nothing, with no signal that the plan in the launch directory had been skipped. The rewrite runs before the first plugin hook, so the plugin cannot recover the root on its own and does not guess: when the resolved directory holds no plan and the launch directory of a CLI session does, `pre_llm_call` now injects one line naming both directories and the `PWF_PLAN_ROOT` pin instead of returning nothing, `/pwf-status` prints the same line under `No planning files found.`, `/pwf` appends it when the plan it created went somewhere other than a launch directory that already holds one, and `/pwf` and `/pwf-status` honor `PWF_PLAN_ROOT` like the hooks and report a pin that does not resolve instead of creating or reading a plan in the directory Hermes named. The line stays silent outside the CLI, in `hermes -w` worktree sessions (`TERMINAL_CWD` at `<repo>/.worktrees/<name>` without a chdir is the intended split), for a launch directory without planning state, and for a launch directory whose session isolation refuses the session. Upstream: NousResearch/hermes-agent#86411 and #95577 (#272).
### Changed
- `docs/hermes.md` documents the Hermes 0.21.3 working-directory rewrite, what was reproduced with the 0.21.0 source, the pin for project-scoped CLI sessions, and the shell-hook route as the unaffected alternative.
### Thanks
- @ericshunhinglee-cloud, for the report with the setter stack trace, the on-the-wire token evidence and the upstream cross-references in #272.
## [3.20.1] - 2026-09-18
### Fixed
+2 -2
View File
@@ -7,8 +7,8 @@ authors:
- family-names: Adi
given-names: Ahmad Othman Ammar
alias: OthmanAdi
version: "3.20.1"
date-released: "2026-09-18"
version: "3.20.3"
date-released: "2026-09-19"
license: MIT
url: "https://github.com/OthmanAdi/planning-with-files"
repository-code: "https://github.com/OthmanAdi/planning-with-files"
+7 -3
View File
@@ -106,10 +106,14 @@ These amazing people have contributed code, documentation, or significant improv
### Other Contributors
- **[Shaun Lin](https://github.com/ShaunLinTW)**, [PR #245](https://github.com/OthmanAdi/planning-with-files/pull/245), [PR #247](https://github.com/OthmanAdi/planning-with-files/pull/247), [PR #263](https://github.com/OthmanAdi/planning-with-files/pull/263)
- **[@ericshunhinglee-cloud](https://github.com/ericshunhinglee-cloud)**, [Issue #272](https://github.com/OthmanAdi/planning-with-files/issues/272)
- Reported and traced the Hermes 0.21.3 first-turn `TERMINAL_CWD` rewrite that made the Hermes plugin resolve the home directory as the project root, with a setter stack trace, on-the-wire token evidence and the upstream cross-references.
- **[Shaun Lin](https://github.com/ShaunLinTW)**, [PR #245](https://github.com/OthmanAdi/planning-with-files/pull/245), [PR #247](https://github.com/OthmanAdi/planning-with-files/pull/247), [PR #263](https://github.com/OthmanAdi/planning-with-files/pull/263), [PR #271](https://github.com/OthmanAdi/planning-with-files/pull/271)
- Isolated Python calls in the Codex, Gemini, and GitHub Copilot shell adapters and added regression coverage for project-local import shadowing.
- Added named-plan slug mode to the PowerShell initializer with root-mode policy inheritance, host-aware attestation, and Windows PowerShell regression coverage.
- Made the OpenCode session catchup adapter skip malformed part rows instead of raising, with regression coverage for the string-state and invalid-JSON shapes.
- Made the shell several-plans counters skip symlinked and junctioned plan directories so they match the Hermes plugin, with a differential regression including the ambiguity probe.
- **[@TayfurYldz](https://github.com/TayfurYldz)**, [PR #265](https://github.com/OthmanAdi/planning-with-files/pull/265), [PR #266](https://github.com/OthmanAdi/planning-with-files/pull/266)
- Bound `PWF_PLAN_ROOT` to the current project around the attestation call in both initializers so an inherited pin cannot redirect attestation, with shell and PowerShell regressions.
@@ -446,6 +450,6 @@ If you've contributed and don't see your name here, please open an issue! We wan
---
**Total Contributors:** 64+ and growing!
**Total Contributors:** 65+ and growing!
*Last updated: 2026-09-18*
*Last updated: 2026-09-19*
+2
View File
@@ -347,6 +347,8 @@ One hook fire measures 289ms wall-clock since the v3.6.0 optimization, down from
| Version | Highlights |
|---------|------------|
| **v3.20.3** | A symlinked or junctioned directory under `.planning/` is never a plan on any route: the shell counters skip it (PR #271 by @ShaunLinTW, #270), and the selection paths of the shell family plus the Codex, OpenCode and DSH counters refuse it too, so one real plan next to a linked one no longer becomes an mtime guess. |
| **v3.20.2** | Hermes plugin: Hermes 0.21.3 re-homes `TERMINAL_CWD` to the home directory on the first CLI turn, so the plan in the launch directory was skipped silently. The first turn now says why nothing was injected and names the `PWF_PLAN_ROOT` pin, `/pwf-status` and `/pwf` print the same diagnostic, and the slash commands honor the pin (#272, reported by @ericshunhinglee-cloud). |
| **v3.20.1** | Fixes four maintainer-filed issues from the v3.19.0 and v3.20.0 cycles: newline-safe shell slugs (#257, PR #266 by @TayfurYldz), attestation bound to the current project when `PWF_PLAN_ROOT` is inherited (#261, PR #265 by @TayfurYldz), malformed OpenCode part rows skipped by session catchup (#258, PR #263 by @ShaunLinTW), and the several-plans rule in the Hermes plugin (#264, PR #267 by @kuei51307-hub). |
| **v3.20.0** | **DeepSeek Harness becomes a first-class host** (closes #252, reported by @loarland): the native Cordis plugin `dsh-planning-with-files` injects the plan on every prompt and after compaction, reminds after writes, holds the turn boundary in gated mode, and registers `/pwf`, `/pwf-status` and the `pwf_*` tools; `dsh plugin --profile web add dsh-planning-with-files`. Cursor's native PowerShell hooks resolve named plans (PR #251 by @kuei51307-hub, item 9 of #250); the PowerShell resolver and attester run on Windows PowerShell 5.1 with a pin and in bracketed project paths; the OpenCode and DSH plugins require `PLAN_ID` for several named plans (the #240 rule); the README is shorter (one 3-file pattern block, a first-class hosts table, one commands collapsible). |
| **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). |
+16 -2
View File
@@ -1,6 +1,6 @@
# Hermes Agent Setup
planning-with-files treats [Hermes Agent](https://github.com/NousResearch/hermes-agent) by Nous Research as a first-class host: the Hermes CLI, the Hermes TUI and gateway sessions, and the Hermes Desktop app all run the same adapter. Everything on this page was verified against the Hermes v0.19.1 source and a live Hermes install on Windows; the POSIX paths follow Hermes' own defaults.
planning-with-files treats [Hermes Agent](https://github.com/NousResearch/hermes-agent) by Nous Research as a first-class host: the Hermes CLI, the Hermes TUI and gateway sessions, and the Hermes Desktop app all run the same adapter. Everything on this page was verified against the Hermes v0.19.1 source and a live Hermes install on Windows; the Hermes 0.21.3 working-directory rewrite described below was reproduced with the 0.21.0 source. The POSIX paths follow Hermes' own defaults.
The adapter has two parts:
@@ -76,6 +76,20 @@ Hermes Desktop runs the same backend (`hermes serve`) and therefore the same plu
- The hub does not deliver the PowerShell scripts; nothing in the adapter needs them.
- Short-name paths (`C:\Users\OASRVA~1\...`) in `HERMES_HOME` make `hermes skills install` fail its subpath check. Use the long form.
## Hermes 0.21.3: the working directory can move to the home directory on the first turn
Reported on Hermes 0.21.3 ([#272](https://github.com/OthmanAdi/planning-with-files/issues/272)): during the first turn of a CLI session, `agent/relay_runtime.py` imports `gateway/run.py` lazily, and that module's import-time bridge sets the process-global `TERMINAL_CWD` to the home directory when the variable is empty or a placeholder (`terminal.cwd: "."`). `agent.runtime_cwd.resolve_agent_cwd()`, the documented single source of truth the plugin reads, then names the home directory instead of the one the session was started in, while `os.getcwd()` still names the launch directory. The rewrite runs before the first plugin hook of the session, so no hook ever sees the launch directory. Hermes' own project-context discovery and its terminal tool follow the same rewritten value. Upstream reports: [hermes-agent#86411](https://github.com/NousResearch/hermes-agent/issues/86411) (an explicit `terminal.cwd` re-asserted mid-turn) and [hermes-agent#95577](https://github.com/NousResearch/hermes-agent/issues/95577) (one-shot sessions anchored at the home directory).
What was reproduced here: the bridge in the Hermes 0.21.0 source, driven with the real `resolve_agent_cwd()` and an empty `TERMINAL_CWD`, the state the report shows at the first turn on 0.21.3. What empties the variable on that install is not established: the upstream `cli.py` at the reported commit still exports `TERMINAL_CWD=os.getcwd()` for the local backend when `cli` is imported, and skips that export only when `_HERMES_GATEWAY=1` is inherited from the environment. With the variable exported, only an explicit `terminal.cwd` in `config.yaml` triggers the rewrite (#86411). The plugin keys off the observed condition, not off a version.
What the plugin does since v3.20.2:
- The failure is no longer silent. When the resolved directory holds no plan and the launch directory of a CLI session does, `pre_llm_call` injects one line instead of nothing: `[planning-with-files] Hermes resolved <dir> as the working directory, but the launch directory <project> holds a plan. Nothing injected. Pin the thread with PWF_PLAN_ROOT=<project>.` The plugin never switches to the launch directory on its own: Hermes' terminal and file tools follow the rewritten directory too, so which root the session should use is the operator's call. The line is CLI-only (other surfaces have no launch directory), and it stays silent for `hermes -w` worktree sessions (Hermes points `TERMINAL_CWD` at `<repo>/.worktrees/<name>` without a chdir, by design), for a launch directory without planning state, and for a launch directory whose session isolation refuses this session anyway.
- `/pwf-status` prints the same line under `No planning files found.` when the launch directory holds a plan, so the diagnostic command tells you what the hooks see, and `/pwf` appends it when the plan it just created went somewhere other than a launch directory that already holds one. Both stay silent for worktree sessions and for contexts whose working directory Hermes has pinned per session at command time; the TUI and Desktop dispatch plugin commands outside that context, where `/pwf-status` has always reported the backend's directory rather than the session's.
- `/pwf` and `/pwf-status` honor `PWF_PLAN_ROOT` exactly like the hooks. A pin that does not resolve is reported instead of creating or reading a plan in whatever directory Hermes named. Without a pin the slash commands follow the Hermes working directory (a command handler receives only its arguments, no platform), so on an affected host an unpinned `/pwf name` creates the plan under the home directory and prints that path; the `planning_with_files_init` tool uses the process working directory instead.
On an affected host, start project-scoped CLI sessions with the pin until the upstream fix lands: `PWF_PLAN_ROOT=/abs/path/to/project hermes chat` (PowerShell: `$env:PWF_PLAN_ROOT = "C:\path\to\project"`). The pin fails closed when the path does not resolve. The shell-hook route below reads the process working directory and is not affected. The pin restores the plan injection only; the agent's terminal and file tools keep following the rewritten directory (`hermes chat --in <project>` does not change that on an affected build), so ask the model to work with absolute paths. Keep planning files out of your home directory: on an affected host a `~/.planning/` or `~/task_plan.md` would be resolved by every session started anywhere.
## Usage
- `/pwf` creates `task_plan.md`, `findings.md` and `progress.md` in the project root. `/pwf Night run` creates an isolated `.planning/YYYY-MM-DD-night-run/` plan and points `.planning/.active_plan` at it. `/pwf --gated Night run` also writes `.mode`, `.nonce`, resets the gate counter and attests the plan, mirroring `init-session.sh --gated`.
@@ -125,7 +139,7 @@ Hermes asks for consent on first use (`hermes hooks list` shows the allowlist st
python -m pytest tests/test_hermes_adapter.py tests/test_hermes_first_class.py -q
```
`tests/test_hermes_first_class.py` covers slug resolution, the `PWF_PLAN_ROOT` pin, the ambiguity rule, `PLANNING_DISABLED`, slug attestation, the `pre_verify` gate (block, counter, stall, cap), `/pwf` and `/pwf-status`, bundled-skill registration, the Python completion fallback and the shell-hook bridge.
`tests/test_hermes_first_class.py` covers slug resolution, the `PWF_PLAN_ROOT` pin, the ambiguity rule, `PLANNING_DISABLED`, slug attestation, the `pre_verify` gate (block, counter, stall, cap), `/pwf` and `/pwf-status`, bundled-skill registration, the Python completion fallback, the shell-hook bridge, and the Hermes 0.21.3 working-directory cases of #272 (the launch-directory notice and where it stays silent, the `/pwf-status` hint, the pinned slash commands).
## Integration Notes
+17 -5
View File
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
+7 -3
View File
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
+23 -2
View File
@@ -139,6 +139,23 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory carries and which are not links to sh.
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +175,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +195,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -198,7 +218,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +231,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
+10 -1
View File
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
+7
View File
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
+8 -1
View File
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
+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.20.1"
version: "3.20.3"
---
# نظام تخطيط الملفات
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,23 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory carries and which are not links to sh.
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +175,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +195,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -198,7 +218,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +231,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -204,6 +204,8 @@ function Show-PlanList {
Write-Output "[active] marks the shared .active_plan pointer; listing does not bind this session."
$found = $false
foreach ($plan in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue | Sort-Object Name)) {
# A linked plan directory is never a plan (#270): no resolver selects it.
if (([string]$plan.LinkType) -in @('SymbolicLink', 'Junction')) { continue }
if (-not (Test-ValidSlug $plan.Name) -or -not (Test-WithinRoot $plan.FullName)) { continue }
$planFile = Join-Path $plan.FullName "task_plan.md"
if (-not (Test-Path -LiteralPath $planFile -PathType Leaf) -or -not (Test-WithinRoot $planFile)) { continue }
@@ -281,6 +283,11 @@ if (-not (Test-Path -LiteralPath $PlanDir -PathType Container)) {
Write-Error "Run: init-session.sh `"$PlanId`" to create it, or check .planning\ for available plans."
exit 1
}
$planDirItem = Get-Item -LiteralPath $PlanDir -Force -ErrorAction SilentlyContinue
if ($planDirItem -and (([string]$planDirItem.LinkType) -in @('SymbolicLink', 'Junction'))) {
Write-Error "Error: plan directory is a symlink or junction and no route selects it: $PlanDir"
exit 1
}
if (-not (Test-WithinRoot $PlanRoot) -or -not (Test-WithinRoot $PlanDir)) {
Write-Error "Error: plan directory must remain within the project."
exit 1
@@ -272,6 +272,9 @@ list_plans() {
printf '%s\n' 'Available plans:'
for _dir in "${PLAN_ROOT}"/*; do
[ -d "${_dir}" ] || continue
# A linked plan directory is never a plan (#270): no resolver selects
# it, so listing it would advertise a PLAN_ID every route refuses.
[ -L "${_dir}" ] && continue
_id="${_dir##*/}"
slug_is_valid "${_id}" || continue
is_within_root "${_dir}" || continue
@@ -312,7 +315,7 @@ if [ "${1:-}" = '' ]; then
exit 1
fi
plan_id="$(current_active)"
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
if [ -n "${plan_id}" ] && [ -d "${PLAN_ROOT}/${plan_id}" ] && [ ! -L "${PLAN_ROOT}/${plan_id}" ] && is_within_root "${PLAN_ROOT}/${plan_id}"; then
printf '%s\n' "Active plan: ${plan_id}" "Path: ${PLAN_ROOT}/${plan_id}"
elif [ -n "${plan_id}" ]; then
printf '%s\n' "Active plan pointer: ${plan_id} (directory not found or outside project - stale pointer)"
@@ -333,6 +336,10 @@ if [ ! -d "${PLAN_DIR}" ]; then
"Run: init-session.sh \"${PLAN_ID}\" to create it, or use --list to see available plans." >&2
exit 1
fi
if [ -L "${PLAN_DIR}" ]; then
printf '%s\n' "Error: plan directory is a symlink or junction and no route selects it: ${PLAN_DIR}" >&2
exit 1
fi
if ! is_within_root "${PLAN_ROOT}" || ! is_within_root "${PLAN_DIR}"; then
printf '%s\n' 'Error: plan directory is outside the project or cannot be verified.' >&2
exit 1
+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.20.1"
version: "3.20.3"
---
# Dateiplanungssystem
@@ -845,7 +845,10 @@ class Injector(object):
)
raise Bail()
if plan_id:
if slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id):
# A linked plan directory is never selectable (#270): the same
# `[ ! -L ]` the reference applies on every branch below.
if (slug_is_valid(plan_id) and is_dir(plan_prefix + ".planning/" + plan_id)
and not is_link(plan_prefix + ".planning/" + plan_id)):
resolved = plan_prefix + ".planning/" + plan_id
scope = "scoped"
explicit = True
@@ -864,7 +867,7 @@ class Injector(object):
active = b""
if active and slug_is_valid(active):
slug = active.decode("ascii")
if is_dir(plan_prefix + ".planning/" + slug):
if is_dir(plan_prefix + ".planning/" + slug) and not is_link(plan_prefix + ".planning/" + slug):
resolved = plan_prefix + ".planning/" + slug
scope = "scoped"
if not resolved and is_dir(plan_prefix + ".planning"):
@@ -880,6 +883,8 @@ class Injector(object):
candidate = plan_prefix + ".planning/" + name
if not is_dir(candidate):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -1327,7 +1332,12 @@ def plan_is_ambiguous(plan_root, project_root, plan_id=""):
except OSError:
names = []
for name in names:
if slug_is_valid(name) and is_file(plan_root + "/" + name + "/task_plan.md"):
candidate_dir = plan_root + "/" + name
# A linked plan directory is not selectable, so it never counts (#270):
# the reference tests `[ -L "$plan_candidate_dir" ]` before `-f`.
if is_link(candidate_dir):
continue
if slug_is_valid(name) and is_file(candidate_dir + "/task_plan.md"):
count += 1
if count > 1:
return True
@@ -1364,7 +1374,7 @@ def resolve_plan_dir(env=None):
if plan_id:
if slug_is_valid(plan_id):
candidate = fs_root + "/" + plan_id
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(plan_id)
return ("", "")
@@ -1382,7 +1392,7 @@ def resolve_plan_dir(env=None):
if slug_is_valid(active):
slug = active.decode("ascii")
candidate = fs_root + "/" + slug
if is_dir(candidate) and within(candidate):
if is_dir(candidate) and not is_link(candidate) and within(candidate):
return found(slug)
if is_dir(fs_root):
@@ -1398,6 +1408,8 @@ def resolve_plan_dir(env=None):
continue
if name.startswith("."):
continue
if is_link(candidate):
continue
if not slug_is_valid(name):
continue
if not is_file(candidate + "/task_plan.md"):
@@ -263,8 +263,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_PREFIX}".planning/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi
@@ -295,7 +296,9 @@ if [ -n "${PLAN_ID:-}" ]; then
# printing on those would spam the transcript with the same line. The
# userprompt fire is also the one plan-doctor.sh drives, so /plan-doctor
# still sees and reports the state.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
# A linked plan directory is never selectable (#270): same `-L` rule as
# the counter above and as resolve-plan-dir.sh, on every branch below.
if slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ] && [ ! -L "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
@@ -305,7 +308,7 @@ if [ -n "${PLAN_ID:-}" ]; then
fi
elif [ -f "${PLAN_PREFIX}.planning/.active_plan" ]; then
AP=$(tr -d '\r\n[:space:]' < "${PLAN_PREFIX}.planning/.active_plan" 2>/dev/null)
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ]; then
if [ -n "$AP" ] && slug_is_valid "$AP" && [ -d "${PLAN_PREFIX}.planning/${AP}" ] && [ ! -L "${PLAN_PREFIX}.planning/${AP}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${AP}"; SCOPE="scoped"
fi
fi
@@ -314,6 +317,7 @@ if [ -z "$RESOLVED" ] && [ -d "${PLAN_PREFIX}.planning" ]; then
for d in "${PLAN_PREFIX}".planning/*/; do
d="${d%/}"; n="${d##*/}"
case "$n" in .*) continue;; esac
[ -L "$d" ] && continue
slug_is_valid "$n" || continue
[ -f "$d/task_plan.md" ] || continue
m=$(stat -c '%Y' "$d" 2>/dev/null || stat -f '%m' "$d" 2>/dev/null || date -r "$d" +%s 2>/dev/null || echo 0)
@@ -139,6 +139,23 @@ function Test-WithinRoot {
return $candNorm.StartsWith($rootNorm + [System.IO.Path]::DirectorySeparatorChar, [System.StringComparison]::OrdinalIgnoreCase)
}
# A linked plan directory (symlink or junction) is never selectable: not by
# PLAN_ID, not by the pointer, not by the newest scan, and it never counts
# (#270). This is `[ -L ]` of resolve-plan-dir.sh and is_link of the Python
# twin: LinkType names symlinks and junctions only. The ReparsePoint
# attribute alone would also match OneDrive Files On-Demand placeholders,
# which every synced directory carries and which are not links to sh.
function Test-LinkedDirectory {
param($PathOrItem)
if ($PathOrItem -is [string]) {
$item = Get-Item -LiteralPath $PathOrItem -Force -ErrorAction SilentlyContinue
} else {
$item = $PathOrItem
}
if (-not $item) { return $false }
return ([string]$item.LinkType) -in @('SymbolicLink', 'Junction')
}
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
@@ -158,6 +175,9 @@ if (-not $env:PLAN_ID) {
}
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
foreach ($entry in (Get-ChildItem -LiteralPath $PlanRoot -Directory -ErrorAction SilentlyContinue)) {
# A linked plan directory (symlink, junction) is not selectable and
# never counts, matching `[ -L ]` in resolve-plan-dir.sh (#270).
if (Test-LinkedDirectory $entry) { continue }
if ((Test-ValidSlug $entry.Name) -and
(Test-Path -LiteralPath (Join-Path $entry.FullName "task_plan.md") -PathType Leaf)) {
$planCount++
@@ -175,7 +195,7 @@ if ($planCount -gt 1) { exit 0 }
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -198,7 +218,7 @@ if ($activeItem) {
$planId = "$(Get-Content -LiteralPath $activeFile -Raw -ErrorAction SilentlyContinue)".Trim()
if ($planId -and (Test-ValidSlug $planId)) {
$candidate = Join-Path $PlanRoot $planId
if ((Test-Path -LiteralPath $candidate -PathType Container) -and (Test-WithinRoot $candidate)) {
if ((Test-Path -LiteralPath $candidate -PathType Container) -and -not (Test-LinkedDirectory $candidate) -and (Test-WithinRoot $candidate)) {
Write-Output $candidate
exit 0
}
@@ -211,6 +231,7 @@ if ($activeItem) {
if (Test-Path -LiteralPath $PlanRoot -PathType Container) {
$latest = Get-ChildItem -LiteralPath $PlanRoot -Directory |
Where-Object { -not $_.Name.StartsWith('.') } |
Where-Object { -not (Test-LinkedDirectory $_) } |
Where-Object { Test-ValidSlug $_.Name } |
Where-Object { Test-Path -LiteralPath (Join-Path $_.FullName "task_plan.md") -PathType Leaf } |
Where-Object { Test-WithinRoot $_.FullName } |
@@ -246,10 +246,16 @@ mtime_of() {
printf "0\n"
}
# A linked plan directory (symlink or junction; `-L` sees both under Git
# Bash) is never selectable: not by PLAN_ID, not by the pointer, not by the
# newest-mtime scan, and it never counts below (#270). Containment alone let
# a link that stays inside the root be selected while the counter skipped
# it, so one real plan plus a newer linked one became an mtime guess again.
resolve_from_env() {
plan_id="${PLAN_ID:-}"
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -268,6 +274,7 @@ resolve_from_active_file() {
esac
slug_is_valid "${plan_id}" || return 1
candidate="${PLAN_ROOT}/${plan_id}"
[ -L "${candidate}" ] && return 1
if [ -d "${candidate}" ] && is_within_root "${candidate}"; then
printf "%s\n" "${candidate}"
return 0
@@ -288,6 +295,7 @@ resolve_latest_dir() {
case "${name}" in
.*) continue ;;
esac
[ -L "${clean}" ] && continue
slug_is_valid "${name}" || continue
[ -f "${clean}/task_plan.md" ] || continue
is_within_root "${clean}" || continue
@@ -338,8 +346,9 @@ if [ -z "${PLAN_ID:-}" ]; then
PLAN_COUNT=1
fi
for plan_candidate in "${PLAN_ROOT}"/*/task_plan.md; do
[ -f "$plan_candidate" ] || continue
plan_candidate_dir="${plan_candidate%/task_plan.md}"
[ -L "$plan_candidate_dir" ] && continue
[ -f "$plan_candidate" ] || continue
slug_is_valid "${plan_candidate_dir##*/}" || continue
PLAN_COUNT=$((PLAN_COUNT + 1))
if [ "$PLAN_COUNT" -gt 1 ]; then PLAN_AMBIGUOUS=1; break; fi

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