Compare commits

..
4 Commits
Author SHA1 Message Date
OthmanAdi 0fb67596fa release: v3.16.0
Version bumped to 3.16.0 across the 20 tracked parity targets plus the ClawHub
stage. The OpenCode plugin package stays at 1.0.1 and the Pi extension at
1.2.5: this cycle touched hooks/ and .codex/hooks/, neither package.

CHANGELOG entry for #239 including the two scope calls stated rather than left
to be discovered (FileChanged deferred, the standalone skill route unchanged);
README releases-table row; Raymond Manaloto's CONTRIBUTORS entry extended with
#239. Suite size pinned at 706 in README and llms.txt with its guard.
2026-09-03 01:16:42 +02:00
OthmanAdi eb8af2f02f fix(hooks): send the PostToolUse nudge to the model, once per turn, off read-only tools
closes #239, reported by Raymond Manaloto (@sortakool)

The progress reminder is addressed to Claude:

    [planning-with-files] Update progress.md with what you just did. ...

hooks/claude-hook.sh emitted it as systemMessage, which Claude Code documents
as a warning shown to the USER. So the person saw the instruction after every
Write, Edit and Bash call for a whole session, and the model it is written for
never saw it once. emit_session_start eleven lines above already emitted
hookSpecificOutput.additionalContext for its own event, so the correct shape
was in the same file the whole time. .codex/hooks/post_tool_use.py had the
identical defect, next to a pre_tool_use.py and a run_sh.py that already used
the right shape.

Three defects, one line apart, fixed together:

1. The field. Both routes now emit additionalContext under hookSpecificOutput
   with "hookEventName": "PostToolUse".

2. The throttle. Once per turn rather than once per tool call. The string is a
   constant, so every repeat after the first carries no information: it names
   no tool, no file and no phase. UserPromptSubmit and SessionStart fire once
   per turn and clear a marker; the first post-tool fire of the turn sets it.
   The marker lives in the user's private cache under pwf-turn/, never in the
   plan directory, and is keyed on the plan path plus PWF_SESSION_ID so two
   sessions sharing a plan do not silence each other. A cache root that cannot
   be created skips the throttle rather than the reminder, so a broken cache
   cannot quietly remove the signal instead of the noise.

3. The matcher. Bash comes off PostToolUse on all three manifests: ls, git
   status and grep were tripping a "you changed something, record it" nudge.
   hooks/hooks.json goes to Write|Edit and both Codex manifests to
   apply_patch|Edit|Write. PreToolUse keeps Bash, because a plan reminder
   before a shell command is a different and wanted behaviour. The standalone
   skill route already used Write|Edit, which is further evidence the wider
   matchers were drift rather than intent.

Fixing this surfaced a fourth thing. active_plan_dir() in hooks/claude-hook.sh
resolves through the shared resolver and then fell back to the legacy root
task_plan.md: the #237 fallback removed from the script and Codex routes in
v3.15.0 and missed on the plugin dispatcher. A rejected PLAN_ID or
PWF_PLAN_ROOT now stops there too.

Deliberately not in this change: FileChanged, which would catch a Bash command
that rewrites a file, is a new event surface with its own behaviour and belongs
in a release where it can be tested on its own. The standalone skill route
still emits the sentence as plain stdout from a YAML frontmatter scalar with no
throttle; it already carries the narrow matcher so the volume reported here
never applied to it, and giving it the throttle means either putting cache-key
logic inside a hook scalar or routing it through a new script context across
eleven SKILL.md files.

Tests: 10 in tests/test_post_tool_nudge.py, driving both routes as processes
rather than asserting on source. One proves the two Codex scripts agree on the
marker key by asserting the re-arm deletes the exact file the throttle wrote:
they derive it independently and one resolves a PWF_PLAN_ROOT pin while the
other does not, so a divergence would leave the nudge firing once per session
with nothing in any log.
2026-09-03 01:16:16 +02:00
OthmanAdi 601df1713a release: v3.15.0
Version bumped to 3.15.0 across the 20 tracked parity targets plus the ClawHub
stage. The OpenCode plugin package goes to 1.0.1 and the bundled Pi extension
to 1.2.5, since both changed in this cycle.

CHANGELOG entry for #236, #237 and #238; README releases-table row; Raymond
Manaloto added to CONTRIBUTORS.md for all three. Suite size pinned at 696 in
README and llms.txt with its guard.

The resolver description in the English SKILL.md files said PLAN_ID "checks
first, then falls back"; it now states that a set PLAN_ID is a binding. The
five translated variants keep the old sentence until it can be translated
properly rather than shipped as English text under a localized heading.
2026-09-03 00:23:32 +02:00
OthmanAdi 3749f86ac3 fix: bind explicit plan selectors, floor slug modes on the project root, and classify doctor output on the data frame
Three defects reported by Raymond Manaloto (@sortakool), each reproduced on
Windows with Git Bash before any code changed. Two of them let a session work
on a plan nobody selected; the third made the diagnostic that should have
caught them report PASS.

closes #237: an explicit PLAN_ID was a hint, not a binding

resolve_from_env returned 1 both when no selector was set and when the selector
was rejected, so a PLAN_ID of valid slug shape naming no directory fell through
to .active_plan and then to newest-by-mtime. attest-plan.sh locked that other
plan at rc=0 and injection followed it. The guard in attest-plan.sh written for
exactly this case was unreachable, because the resolver never returned empty.
commands/plan-attest.md has promised the opposite since v3.9.0.

A non-empty PLAN_ID now resolves or stops, for every rejection reason: slug
shape (traversal included), naming no directory, or failing containment. An
empty value still means unset, which init-session.sh depends on. The rule went
into every resolver, because they disagreed otherwise: resolve-plan-dir.sh,
resolve-plan-dir.ps1, the inline resolver inside inject-plan.sh, and the
Hermes, OpenCode and Pi plugin resolvers. v3.14.0 had made the two plugin
resolvers fall through to match the shell; that parity was right and its target
was wrong.

Fixing the resolver alone would have moved the bug rather than removed it, so
every consumer was audited. check-complete.sh would have read the root plan's
completion state, which decides whether an autonomous run may stop.
ledger-summary.sh feeds phase counts into autonomous turns. phase-status.sh and
ledger-append.sh write into the directory they pick. The five Codex hooks call
the resolver directly and each fell through to the legacy root, stop.sh and
pre-compact.sh included. All of them now stop on a rejected selector, and the
once-per-turn routes print a notice, because a fail-closed path with no stated
cause would trade a wrong-plan bug for a silent one.

closes #238: a slug plan with no .mode bypassed the project's root .mode

A project makes attestation mandatory by committing a root .mode, a reviewed
project setting. inject-plan.sh read the slug's .mode and never the root's, and
init-session.sh writes no .mode unless --autonomous or --gated was passed, so
init-session.sh <name>, which /plan runs, produced a plan with no attestation
requirement and full injection. The policy was a flag the agent chose at plan
creation.

The root .mode is now a floor. Strictness-raising tokens count from either
file, so a slug may raise and never lower; the one strictness-lowering token,
plan-guard-off, needs the root's agreement. The same floor applies to the
completion gate in check-complete.sh and check-complete.ps1, which read .mode
the same way and had the same bypass, and to the Hermes and OpenCode plugins.
init-session.sh seeds a new slug from the root .mode so the effective policy is
visible in the plan directory, not only in the resolver. With no root .mode
present the effective token set is exactly the slug's, so existing projects are
unchanged.

closes #236: plan-doctor.sh reported PASS on a fully dark-hooks state

The injection check substring-matched five control strings against output that
carries the plan body verbatim inside the BEGIN-PWF-DATA fences. A plan whose
phase line read "fix the false PLAN TAMPERED warning in plan-doctor" reported a
hash mismatch while correctly attested. Worse, the PWF_PLAN_ROOT arm matched a
literal that is not a substring of what inject-plan.sh emits, so the arm was
dead code and execution fell to the success arm: PWF_PLAN_ROOT=/nonexistent
printed "PASS injection: emits plan context (123 bytes)" while nothing was
injected, counting the refusal notice's own bytes as plan context. The file's
own comment four lines above already warned against exactly that.

Classification now branches on the frame. Every refusal path exits before
frame_file runs, so a frame proves injection happened and unframed output is by
construction a notice. The default arm warns, so a reworded or translated
banner degrades noisily instead of silently. The stale literal is corrected
against the emitting echo.

Tests: Python suite 653 to 696, OpenCode Vitest 28 to 34. New files
test_plan_selector_binding.py, test_root_mode_floor.py and
test_plan_doctor_classification.py; new arms in test_resolver_parity.py,
test_resolve_plan_dir.py, test_resolver_plan_root_pin.py and
test_hermes_first_class.py. Five existing tests asserted the fall-through and
were rewritten to assert the refusal, keeping their original security
assertion. Each suite carries a control arm: two first drafts passed on
fixtures that could not have failed, a gate assertion over a plan with every
phase complete and a parallel-write-guard assertion over a plan with nothing
checked to lose.
2026-09-03 00:23:03 +02:00
223 changed files with 5164 additions and 426 deletions
+2 -2
View File
@@ -28,7 +28,7 @@ hooks:
- type: command
command: "SH=\"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\"; [ -f \"$SH\" ] || SH=$(ls \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\" 2>/dev/null | head -1); [ -n \"$SH\" ] && [ -f \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.14.0"
version: "3.16.0"
---
# Planning with Files
@@ -219,7 +219,7 @@ Helper scripts for automation:
- `scripts/init-session.sh` — Initialize planning files. With a name arg, creates an isolated plan under `.planning/YYYY-MM-DD-<slug>/` for parallel task workflows. Without args, writes `task_plan.md` at project root (legacy mode, backward-compatible).
- `scripts/set-active-plan.sh` — Switch the active plan pointer (`.planning/.active_plan`). Run with a plan ID to switch; run without args to show which plan is current.
- `scripts/resolve-plan-dir.sh` — Resolve the active plan directory. Checks `$PLAN_ID` env var first, then `.planning/.active_plan`, then newest plan dir by mtime, then falls back to project root (legacy). Used internally by hooks.
- `scripts/resolve-plan-dir.sh` — Resolve the active plan directory. A set `$PLAN_ID` is a binding: it resolves or resolution stops, never another plan (issue #237). With no `$PLAN_ID`, checks `.planning/.active_plan`, then newest plan dir by mtime, then falls back to project root (legacy). Used internally by hooks.
- `scripts/check-complete.sh` — Verify all phases in the active plan are complete.
- `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history.
- `scripts/attest-plan.sh` (and `.ps1`) — Lock the current `task_plan.md` content with a SHA-256 attestation (v2.37.0). Hooks then refuse to inject plan content if the file diverges from the attested hash. Use `--show` to print the stored hash, `--clear` to remove the attestation. See `/plan-attest` command.
@@ -108,7 +108,18 @@ case "${1:-}" in
esac
plan_file="$(resolve_plan_file)" || {
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
# Name the actual cause. "No task_plan.md found" is true but misleading
# when the plan exists and an explicit selector was rejected: before #237
# a mistyped PLAN_ID attested a DIFFERENT plan at rc=0, and an operator
# who now sees a generic not-found is likely to go looking for the wrong
# problem. The selectors are bindings, so say which one refused.
if [ -n "${PLAN_ID:-}" ]; then
printf "[plan-attest] PLAN_ID=%s names no plan directory under .planning. An explicit selector is a binding: nothing was attested and no other plan was substituted.\n" "${PLAN_ID}" >&2
elif [ -n "${PWF_PLAN_ROOT:-}" ]; then
printf "[plan-attest] PWF_PLAN_ROOT=%s did not resolve to a project root holding a plan. An explicit pin is a binding: nothing was attested and no other plan was substituted.\n" "${PWF_PLAN_ROOT}" >&2
else
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
fi
exit 1
}
@@ -107,13 +107,27 @@ if (-not $Gate) {
# ---- Gate path (-Gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate".
# Guard 1: gated mode. A .mode file must contain "gate".
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>\.mode let a slug plan with no .mode
# drop a project-committed gate. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope $PlanDir already IS the
# project root, so the second source is skipped and behavior is unchanged.
$modeFile = Join-Path $PlanDir ".mode"
$rootForMode = if ($env:PWF_PLAN_ROOT) { $env:PWF_PLAN_ROOT } else { "." }
$rootModeFile = $null
if ($PlanDir -ne $rootForMode -and $PlanDir -ne ".") {
$rootModeFile = Join-Path $rootForMode ".mode"
}
$gatedMode = $false
if (Test-Path $modeFile) {
$modeContent = Get-Content $modeFile -Raw -ErrorAction SilentlyContinue
foreach ($candidateMode in @($modeFile, $rootModeFile)) {
if (-not $candidateMode) { continue }
if (-not (Test-Path $candidateMode)) { continue }
$modeContent = Get-Content $candidateMode -Raw -ErrorAction SilentlyContinue
if ($null -ne $modeContent -and $modeContent -match "gate") {
$gatedMode = $true
break
}
}
if (-not $gatedMode) {
@@ -60,6 +60,14 @@ else
if [ -n "${RESOLVED_DIR}" ] && [ -f "${RESOLVED_DIR}/task_plan.md" ]; then
PLAN_FILE="${RESOLVED_DIR}/task_plan.md"
PLAN_DIR="${RESOLVED_DIR}"
elif [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
# Explicit selectors are bindings, not hints (issue #237). The shared
# resolver rejected one, so the legacy cwd fallback below must not run:
# answering a mistyped pin with the ROOT plan's completion state is the
# same wrong-plan harm the binding removes, and here it would decide
# whether an autonomous run is allowed to stop.
echo "[planning-with-files] An explicit PLAN_ID or PWF_PLAN_ROOT did not resolve to a plan; no completion state was read and no other plan was substituted."
exit 0
else
PLAN_FILE="task_plan.md"
PLAN_DIR="."
@@ -131,10 +139,30 @@ fi
# ---- Gate path (--gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate". Absent or other
# Guard 1: gated mode. A .mode file must contain "gate". Absent or other
# content means advisory mode (legacy behavior preserved).
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>/.mode let a slug plan with no .mode
# drop a project-committed gate, the same way it dropped the attestation
# requirement in inject-plan.sh. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope PLAN_DIR already IS the
# project root, so the second source stays empty and behavior is unchanged.
MODE_FILE="${PLAN_DIR}/.mode"
if [ ! -f "${MODE_FILE}" ] || ! grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
ROOT_MODE_FILE=""
_root_for_mode="${PWF_PLAN_ROOT:-.}"
if [ "${PLAN_DIR}" != "${_root_for_mode}" ] && [ "${PLAN_DIR}" != "." ]; then
ROOT_MODE_FILE="${_root_for_mode}/.mode"
fi
GATED=0
if [ -f "${MODE_FILE}" ] && grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ] && [ -n "${ROOT_MODE_FILE}" ] && [ -f "${ROOT_MODE_FILE}" ] \
&& grep -q "gate" "${ROOT_MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ]; then
advisory_report
exit 0
fi
@@ -152,6 +152,33 @@ gen_nonce() {
# $1 = plan dir (absolute or relative); dotfiles live directly inside it.
# $2 = plan file path (task_plan.md) used for auto-attestation resolution.
# No-op when MODE is empty (legacy path stays byte-equivalent to v2.43.0).
# Raise MODE to the project's committed floor before the side effects run
# (issue #238). A project that ships a root .mode has made that setting a
# reviewed part of the repo; a new slug plan must not start below it. Without
# this, `init-session.sh <name>` created a plan with no .mode at all, and the
# project's attestation requirement became a flag the agent chose at plan
# creation time.
#
# inject-plan.sh enforces the same floor at read time, so this is not the
# guard. It exists so the effective policy is VISIBLE in the plan directory
# rather than only inside the resolver, and so the new plan gets the nonce and
# the auto-attestation that autonomous mode needs to inject at all.
#
# An explicit --autonomous/--gated is never lowered: gated stays gated.
inherit_root_mode() {
_root_mode="${PWD}/.mode"
[ -f "${_root_mode}" ] || return 0
[ "$MODE" = "gated" ] && return 0
if grep -q 'gate' "${_root_mode}" 2>/dev/null; then
MODE='gated'
return 0
fi
if grep -q 'autonomous' "${_root_mode}" 2>/dev/null; then
MODE='autonomous'
fi
return 0
}
apply_v3_mode() {
_mode_dir="$1"
_mode_plan="$2"
@@ -367,6 +394,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
@@ -254,8 +254,28 @@ SCOPE=""
EXPLICIT=0
[ -n "$PLAN_PREFIX" ] && EXPLICIT=1
[ "$SESSION_ATTACHED" = "1" ] && EXPLICIT=1
if [ -n "${PLAN_ID:-}" ] && slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
if [ -n "${PLAN_ID:-}" ]; then
# A set PLAN_ID is a BINDING, not a hint (issue #237). This inline resolver
# is the one the hooks actually run, so it carries the same rule as
# resolve-plan-dir.sh: a selector that names no directory, fails slug
# validation, or fails containment refuses instead of falling through to
# .active_plan and newest-by-mtime. The fall-through is what let a
# one-character typo inject a DIFFERENT plan while attest-plan.sh locked
# that same wrong plan at rc=0.
#
# Unlike the PWF_PLAN_ROOT refusal above, the notice is userprompt-only.
# pretool fires per tool call and precompact carries no plan body, so
# 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
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
echo "[planning-with-files] PLAN_ID does not name a plan directory under .planning: ${PLAN_ID} — nothing injected. Fix or unset the pin; a broken pin fails closed rather than selecting another plan."
fi
exit 0
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
@@ -476,12 +496,16 @@ if [ "$SCOPE" = "root" ]; then
PROGRESS_FILE="${PLAN_PREFIX}progress.md"
ATTEST_FILE="${PLAN_PREFIX}.plan-attestation"
MODE_FILE="${PLAN_PREFIX}.mode"
ROOT_MODE_FILE=""
NONCE_FILE="${PLAN_PREFIX}.nonce"
else
PLAN_FILE="${RESOLVED}/task_plan.md"
PROGRESS_FILE="${RESOLVED}/progress.md"
ATTEST_FILE="${RESOLVED}/.attestation"
MODE_FILE="${RESOLVED}/.mode"
# The project's own .mode, when it has one (issue #238). In root scope
# MODE_FILE already IS that file, so the second source stays empty.
ROOT_MODE_FILE="${PLAN_PREFIX}.mode"
NONCE_FILE="${RESOLVED}/.nonce"
fi
[ -f "$PLAN_FILE" ] || exit 0
@@ -853,11 +877,52 @@ fi
# gated mode to legacy behavior (platform-critical: per-tool-call injection not
# suppressed, oracle re-hash skipped, raw progress tail injected). Use a grep
# token test, the same pattern check-complete.sh guard 1 uses.
# --- Root .mode is a FLOOR, not a default that slug scope replaces (#238). ---
# A project makes attestation mandatory by committing a root .mode, which is a
# reviewed project setting. Slug scope used to read ONLY the slug's .mode, and
# init-session.sh writes no .mode unless --autonomous or --gated was passed, so
# `init-session.sh <name>` produced a plan with no mode, no attestation
# requirement and full injection: one agent-invocable command turned the
# project's policy off.
#
# mode_has answers for a strictness-RAISING token: present in EITHER file. A
# slug may opt into autonomous/gated where the root left it unset; it can no
# longer opt out of what the root committed.
#
# mode_relax_allowed answers for the one strictness-LOWERING token
# (plan-guard-off): the slug must carry it AND, when the project committed a
# root .mode, that file must carry it too. A slug alone cannot switch off a
# protection the project kept on.
#
# With no root .mode present ROOT_MODE_FILE is either empty (root scope) or
# names a missing file, so the effective token set is exactly the slug's and
# existing projects are byte-identical.
mode_has() {
_mh_token="$1"
if [ -f "$MODE_FILE" ] && grep -q "$_mh_token" "$MODE_FILE" 2>/dev/null; then
return 0
fi
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ] \
&& grep -q "$_mh_token" "$ROOT_MODE_FILE" 2>/dev/null; then
return 0
fi
return 1
}
mode_relax_allowed() {
_mr_token="$1"
[ -f "$MODE_FILE" ] || return 1
grep -q "$_mr_token" "$MODE_FILE" 2>/dev/null || return 1
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ]; then
grep -q "$_mr_token" "$ROOT_MODE_FILE" 2>/dev/null || return 1
fi
return 0
}
MODE=""
if [ -f "$MODE_FILE" ]; then
grep -q 'autonomous' "$MODE_FILE" 2>/dev/null && MODE='autonomous'
grep -q 'gate' "$MODE_FILE" 2>/dev/null && MODE='gated'
fi
mode_has 'autonomous' && MODE='autonomous'
mode_has 'gate' && MODE='gated'
# In autonomous/gated mode the per-tool-call injection is dropped (recitation
# policy): strong models do not need the plan re-recited before every tool call,
@@ -881,7 +946,7 @@ fi
SMART=0
if [ "${PWF_INJECT:-}" = "smart" ]; then
SMART=1
elif [ -f "$MODE_FILE" ] && grep -q 'inject-smart' "$MODE_FILE" 2>/dev/null; then
elif mode_has 'inject-smart'; then
SMART=1
fi
@@ -1149,7 +1214,7 @@ esac
# holding the stale copy. Per-session keying needs PWF_SESSION_ID, which most
# hosts never set.
GUARD=1
[ -f "$MODE_FILE" ] && grep -q 'plan-guard-off' "$MODE_FILE" 2>/dev/null && GUARD=0
mode_relax_allowed 'plan-guard-off' && GUARD=0
[ "${PWF_PLAN_GUARD:-}" = "0" ] && GUARD=0
if [ "$GUARD" = "1" ]; then
# Same user-private cache root and same absolute-path key as the attestation
@@ -55,9 +55,14 @@ $validEvents = @("progress", "phase_complete", "error", "gate_block", "attest",
function Resolve-PlanDir {
$planRoot = Join-Path (Get-Location) ".planning"
# A set PLAN_ID is a BINDING, not a hint (issue #237). This script WRITES
# ledger rows into the directory it picks, so falling through to
# .active_plan, newest-by-mtime and finally the cwd after a mistyped pin
# files another plan's run history.
if ($env:PLAN_ID) {
$candidate = Join-Path $planRoot $env:PLAN_ID
if (Test-Path -LiteralPath $candidate -PathType Container) { return $candidate }
return $null
}
$activePointer = Join-Path $planRoot ".active_plan"
@@ -136,6 +141,10 @@ if (-not $agentClean) { $agentClean = "main" }
if ($Summary.Length -gt 200) { $Summary = $Summary.Substring(0, 200) }
$planDir = Resolve-PlanDir
if (-not $planDir) {
Write-Error "[ledger-append] An explicit PLAN_ID did not resolve to a plan directory; nothing was written and no other plan was substituted."
exit 1
}
$ledgerFile = Join-Path $planDir ("ledger-" + $agentClean + ".jsonl")
$lockFile = Join-Path $planDir ".ledger_lock"
@@ -53,6 +53,12 @@ resolve_plan_dir() {
printf "%s\n" "${plan_dir}"
return 0
fi
# Explicit selectors are bindings, not hints (issue #237). This script
# WRITES ledger rows into the plan dir it picks, so a legacy cwd fallback
# after a rejected selector files another plan's run history.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
return 1
fi
# Legacy single-file mode: ledger lives beside ./task_plan.md at root.
printf "%s\n" "."
return 0
@@ -274,7 +280,10 @@ AGENT="$(sanitize_agent "${AGENT}")"
SUMMARY="$(printf '%s' "${SUMMARY}" | cut -c1-200)"
SUMMARY="$(utf8_trim_incomplete "${SUMMARY}")"
PLAN_DIR="$(resolve_plan_dir)"
PLAN_DIR="$(resolve_plan_dir)" || {
printf "[ledger-append] An explicit PLAN_ID or PWF_PLAN_ROOT did not resolve to a plan directory; nothing was written and no other plan was substituted.\n" >&2
exit 1
}
LEDGER_FILE="${PLAN_DIR}/ledger-${AGENT}.jsonl"
LOCK_FILE="${PLAN_DIR}/.ledger_lock"
@@ -31,9 +31,15 @@ $ErrorActionPreference = "Stop"
function Resolve-PlanDir {
$planRoot = Join-Path (Get-Location) ".planning"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that
# names no plan directory stops resolution instead of falling through to
# .active_plan, newest-by-mtime and finally the cwd: summarizing another
# plan's ledger under a mistyped pin is the same wrong-plan harm that let
# a typo attest the wrong file.
if ($env:PLAN_ID) {
$candidate = Join-Path $planRoot $env:PLAN_ID
if (Test-Path -LiteralPath $candidate -PathType Container) { return $candidate }
return $null
}
$activePointer = Join-Path $planRoot ".active_plan"
@@ -58,6 +64,15 @@ function Resolve-PlanDir {
}
$planDir = Resolve-PlanDir
if (-not $planDir) {
# Loud degradation, same contract as ledger-summary.sh's emit_unavailable:
# a rejected PLAN_ID binding must not report the ROOT plan's phase counts,
# because an autonomous loop reads those counts as its termination signal.
Write-Output "=== RUN LEDGER ==="
Write-Output "ledger: unavailable (explicit PLAN_ID did not resolve)"
Write-Output "=================="
exit 0
}
$planFile = Join-Path $planDir "task_plan.md"
# --- Phase counts: same patterns as check-complete.ps1 ---
@@ -68,6 +68,15 @@ if [ -n "${ARG_DIR}" ]; then
elif [ -f "${RESOLVER}" ]; then
PLAN_DIR="$(sh "${RESOLVER}" 2>/dev/null)"
if [ -z "${PLAN_DIR}" ] || [ ! -d "${PLAN_DIR}" ]; then
# Explicit selectors are bindings, not hints (issue #237). A rejected
# PLAN_ID or PWF_PLAN_ROOT must not fall back to the cwd: this summary
# is injected into autonomous turns, so reporting the ROOT plan's
# phase counts under a mistyped pin feeds the loop another plan's
# termination signal. Degrade loudly, the same way a missing resolver
# already does.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
emit_unavailable "explicit PLAN_ID or PWF_PLAN_ROOT did not resolve"
fi
PLAN_DIR="."
fi
else
@@ -42,10 +42,16 @@ $ErrorActionPreference = "Stop"
function Resolve-PlanFile {
$planRoot = Join-Path (Get-Location) ".planning"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that
# names no plan directory stops resolution instead of falling through to
# .active_plan and newest-by-mtime: this script reports phase state, and
# answering a mistyped pin with a DIFFERENT plan's phases is the same
# wrong-plan harm that let a typo attest the wrong file.
if ($env:PLAN_ID) {
$candidate = Join-Path $planRoot $env:PLAN_ID
$planFile = Join-Path $candidate "task_plan.md"
if (Test-Path -LiteralPath $planFile) { return (Resolve-Path -LiteralPath $planFile).Path }
return $null
}
$activePointer = Join-Path $planRoot ".active_plan"
@@ -156,7 +162,11 @@ if ($validStatus -notcontains $Status) {
$planFile = Resolve-PlanFile
if (-not $planFile) {
Write-Error "[phase-status] No task_plan.md found. Create a plan first."
if ($env:PLAN_ID) {
Write-Error "[phase-status] PLAN_ID names no plan directory under .planning; nothing was written and no other plan was substituted."
} else {
Write-Error "[phase-status] No task_plan.md found. Create a plan first."
}
exit 1
}
@@ -40,6 +40,12 @@ resolve_plan_file() {
printf "%s\n" "${plan_dir}/task_plan.md"
return 0
fi
# Explicit selectors are bindings, not hints (issue #237). This script
# WRITES a phase status into the plan it picks, so a cwd fallback after a
# rejected selector edits a different plan than the operator named.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
return 1
fi
if [ -f "./task_plan.md" ]; then
printf "%s\n" "./task_plan.md"
return 0
@@ -73,7 +79,11 @@ case "${NEW_STATUS}" in
esac
PLAN_FILE="$(resolve_plan_file)" || {
printf "[phase-status] No task_plan.md found. Create a plan first.\n" >&2
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
printf "[phase-status] An explicit PLAN_ID or PWF_PLAN_ROOT did not resolve to a plan; nothing was written and no other plan was substituted.\n" >&2
else
printf "[phase-status] No task_plan.md found. Create a plan first.\n" >&2
fi
exit 1
}
@@ -74,27 +74,49 @@ if [ -f "${INJ}" ]; then
ok "injection: silent because no plan exists here (correct behavior)"
fi
else
# Classify on the DATA FRAMING first, never on substrings of the whole
# blob (issue #236). ${OUT} carries the plan body VERBATIM inside
# ===BEGIN-PWF-DATA=== fences, so a bare substring test also matches
# plan prose: a phase line reading "fix the false PLAN TAMPERED
# warning" made the doctor report a hash mismatch on a correctly
# attested plan.
#
# Every refusal path in inject-plan.sh prints its banner and exits
# before frame_file runs, so a frame in the output proves injection
# happened and rules out every refusal. Output WITHOUT a frame is by
# construction a notice, which is why the banner arms sit under the
# else side and the default arm warns instead of passing. A banner
# whose wording drifts then degrades to a generic warning rather than
# to a silent PASS: that is exactly how the stale
# "PWF_PLAN_ROOT is not a directory" literal (which was never a
# substring of what inject-plan.sh emits) reported PASS on a fully
# dark-hooks state.
case "${OUT}" in
*'PLAN TAMPERED'*)
*'===BEGIN-PWF-DATA'*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
;;
*'[PLAN TAMPERED'*)
warn "injection: plan is attested but the hash mismatches — run /plan-attest (or scripts/attest-plan.sh) to re-approve the current plan"
;;
*'requires attested plan'*)
warn "injection: v3 mode without attestation — run attest-plan once to arm injection"
;;
*'Session isolation is armed'*)
# Refusal notice, not plan context: reporting its byte count as
# PASS told a dark user their hooks were fine.
warn "injection: session isolation refuses this session — attach it with PWF_SESSION_ID=<id> plus .planning/sessions/<id>.attached, or delete the .planning/sessions/ dir (stale ones survive earlier Codex use and copied project trees) to turn isolation off"
;;
*'Ambiguous plan'*)
warn "injection: nested-plan ambiguity — a project directly below this cwd carries its own plan, so hooks refuse to guess. Pin the thread with PWF_PLAN_ROOT=<absolute project root> or PLAN_ID=<slug>"
;;
*'PWF_PLAN_ROOT is not a directory'*)
warn "injection: PWF_PLAN_ROOT points at a missing directory — fix or unset the pin; a broken pin fails closed and injects nothing"
*'PWF_PLAN_ROOT is not a supported absolute local directory'*)
warn "injection: PWF_PLAN_ROOT points at something that is not an absolute local directory — fix or unset the pin; a broken pin fails closed and injects nothing"
;;
*'PLAN_ID does not name a plan directory'*)
warn "injection: PLAN_ID names no plan directory under .planning — fix or unset the pin; a set PLAN_ID is a binding and fails closed rather than selecting another plan"
;;
*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
warn "injection: inject-plan.sh emitted ${BYTES} bytes but no ===BEGIN-PWF-DATA frame, so no plan context reached the model. This is a refusal notice this doctor does not recognize; read it directly with: sh scripts/inject-plan.sh --context=userprompt"
;;
esac
fi
@@ -130,6 +130,13 @@ function Test-WithinRoot {
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
# no directory, fails slug validation, or fails containment terminates
# resolution instead of falling through to .active_plan and newest-by-mtime:
# the fall-through let a one-character typo attest and inject a DIFFERENT plan
# at rc=0. Emptiness is the fail-closed signal on this channel, matching
# resolve-plan-dir.sh and the PWF_PLAN_ROOT pin. An empty $env:PLAN_ID is
# falsy here and still means "unset".
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
@@ -138,6 +145,7 @@ if ($env:PLAN_ID) {
exit 0
}
}
exit 0
}
# Get-Item observes the link object even when its target is missing, unlike
@@ -297,7 +297,34 @@ resolve_latest_dir() {
return 1
}
if resolve_from_env; then exit 0; fi
# A set PLAN_ID is a BINDING, not a hint (issue #237).
#
# resolve_from_env returns 1 both when no selector was set and when the
# selector was rejected, so continuing the chain after it turned a
# one-character typo into a silent switch: .active_plan or newest-by-mtime
# answered instead, attest-plan.sh locked THAT plan at rc=0, and injection
# followed the attestation onto it. commands/plan-attest.md already promised
# the opposite ("It never falls back to another plan").
#
# Any non-empty PLAN_ID therefore terminates resolution here, whether it was
# rejected for slug shape (traversal), for naming no directory, or for failing
# containment. The caller receives an empty result and takes its own
# fail-closed path rather than a different plan. PWF_PLAN_ROOT, the sibling
# selector, has failed closed on any bad value since #212; the two selectors
# now agree.
#
# An EMPTY PLAN_ID still means "unset": init-session.sh passes
# PLAN_ID="${PLAN_ID:-}" into attest-plan.sh on the legacy path and depends on
# that spelling resolving the root plan.
#
# Exit status stays 0 on the refusal (see the header contract). Emptiness is
# the fail-closed signal on this channel, exactly as the PWF_PLAN_ROOT guard
# above already does it; a non-zero status would kill callers running under
# set -e for a condition that is not an internal error.
if [ -n "${PLAN_ID:-}" ]; then
resolve_from_env && exit 0
exit 0
fi
if resolve_from_active_file; then exit 0; fi
if resolve_latest_dir; then exit 0; fi
exit 0
+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.14.0"
"version": "3.16.0"
}
]
}
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.14.0",
"version": "3.16.0",
"description": "Persistent project planning files with lifecycle hooks that inject selected plan context. Automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs commands declared in Markdown. No network upload path. Works across 60+ agents and includes Arabic, German, Spanish, Simplified Chinese, and Traditional Chinese.",
"author": {
"name": "OthmanAdi",
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"${CODEBUDDY_PLUGIN_ROOT}/scripts/inject-plan.sh\" \"$HOME/.codebuddy/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.14.0"
version: "3.16.0"
---
@@ -108,7 +108,18 @@ case "${1:-}" in
esac
plan_file="$(resolve_plan_file)" || {
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
# Name the actual cause. "No task_plan.md found" is true but misleading
# when the plan exists and an explicit selector was rejected: before #237
# a mistyped PLAN_ID attested a DIFFERENT plan at rc=0, and an operator
# who now sees a generic not-found is likely to go looking for the wrong
# problem. The selectors are bindings, so say which one refused.
if [ -n "${PLAN_ID:-}" ]; then
printf "[plan-attest] PLAN_ID=%s names no plan directory under .planning. An explicit selector is a binding: nothing was attested and no other plan was substituted.\n" "${PLAN_ID}" >&2
elif [ -n "${PWF_PLAN_ROOT:-}" ]; then
printf "[plan-attest] PWF_PLAN_ROOT=%s did not resolve to a project root holding a plan. An explicit pin is a binding: nothing was attested and no other plan was substituted.\n" "${PWF_PLAN_ROOT}" >&2
else
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
fi
exit 1
}
@@ -107,13 +107,27 @@ if (-not $Gate) {
# ---- Gate path (-Gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate".
# Guard 1: gated mode. A .mode file must contain "gate".
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>\.mode let a slug plan with no .mode
# drop a project-committed gate. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope $PlanDir already IS the
# project root, so the second source is skipped and behavior is unchanged.
$modeFile = Join-Path $PlanDir ".mode"
$rootForMode = if ($env:PWF_PLAN_ROOT) { $env:PWF_PLAN_ROOT } else { "." }
$rootModeFile = $null
if ($PlanDir -ne $rootForMode -and $PlanDir -ne ".") {
$rootModeFile = Join-Path $rootForMode ".mode"
}
$gatedMode = $false
if (Test-Path $modeFile) {
$modeContent = Get-Content $modeFile -Raw -ErrorAction SilentlyContinue
foreach ($candidateMode in @($modeFile, $rootModeFile)) {
if (-not $candidateMode) { continue }
if (-not (Test-Path $candidateMode)) { continue }
$modeContent = Get-Content $candidateMode -Raw -ErrorAction SilentlyContinue
if ($null -ne $modeContent -and $modeContent -match "gate") {
$gatedMode = $true
break
}
}
if (-not $gatedMode) {
@@ -60,6 +60,14 @@ else
if [ -n "${RESOLVED_DIR}" ] && [ -f "${RESOLVED_DIR}/task_plan.md" ]; then
PLAN_FILE="${RESOLVED_DIR}/task_plan.md"
PLAN_DIR="${RESOLVED_DIR}"
elif [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
# Explicit selectors are bindings, not hints (issue #237). The shared
# resolver rejected one, so the legacy cwd fallback below must not run:
# answering a mistyped pin with the ROOT plan's completion state is the
# same wrong-plan harm the binding removes, and here it would decide
# whether an autonomous run is allowed to stop.
echo "[planning-with-files] An explicit PLAN_ID or PWF_PLAN_ROOT did not resolve to a plan; no completion state was read and no other plan was substituted."
exit 0
else
PLAN_FILE="task_plan.md"
PLAN_DIR="."
@@ -131,10 +139,30 @@ fi
# ---- Gate path (--gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate". Absent or other
# Guard 1: gated mode. A .mode file must contain "gate". Absent or other
# content means advisory mode (legacy behavior preserved).
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>/.mode let a slug plan with no .mode
# drop a project-committed gate, the same way it dropped the attestation
# requirement in inject-plan.sh. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope PLAN_DIR already IS the
# project root, so the second source stays empty and behavior is unchanged.
MODE_FILE="${PLAN_DIR}/.mode"
if [ ! -f "${MODE_FILE}" ] || ! grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
ROOT_MODE_FILE=""
_root_for_mode="${PWF_PLAN_ROOT:-.}"
if [ "${PLAN_DIR}" != "${_root_for_mode}" ] && [ "${PLAN_DIR}" != "." ]; then
ROOT_MODE_FILE="${_root_for_mode}/.mode"
fi
GATED=0
if [ -f "${MODE_FILE}" ] && grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ] && [ -n "${ROOT_MODE_FILE}" ] && [ -f "${ROOT_MODE_FILE}" ] \
&& grep -q "gate" "${ROOT_MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ]; then
advisory_report
exit 0
fi
@@ -152,6 +152,33 @@ gen_nonce() {
# $1 = plan dir (absolute or relative); dotfiles live directly inside it.
# $2 = plan file path (task_plan.md) used for auto-attestation resolution.
# No-op when MODE is empty (legacy path stays byte-equivalent to v2.43.0).
# Raise MODE to the project's committed floor before the side effects run
# (issue #238). A project that ships a root .mode has made that setting a
# reviewed part of the repo; a new slug plan must not start below it. Without
# this, `init-session.sh <name>` created a plan with no .mode at all, and the
# project's attestation requirement became a flag the agent chose at plan
# creation time.
#
# inject-plan.sh enforces the same floor at read time, so this is not the
# guard. It exists so the effective policy is VISIBLE in the plan directory
# rather than only inside the resolver, and so the new plan gets the nonce and
# the auto-attestation that autonomous mode needs to inject at all.
#
# An explicit --autonomous/--gated is never lowered: gated stays gated.
inherit_root_mode() {
_root_mode="${PWD}/.mode"
[ -f "${_root_mode}" ] || return 0
[ "$MODE" = "gated" ] && return 0
if grep -q 'gate' "${_root_mode}" 2>/dev/null; then
MODE='gated'
return 0
fi
if grep -q 'autonomous' "${_root_mode}" 2>/dev/null; then
MODE='autonomous'
fi
return 0
}
apply_v3_mode() {
_mode_dir="$1"
_mode_plan="$2"
@@ -367,6 +394,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
@@ -254,8 +254,28 @@ SCOPE=""
EXPLICIT=0
[ -n "$PLAN_PREFIX" ] && EXPLICIT=1
[ "$SESSION_ATTACHED" = "1" ] && EXPLICIT=1
if [ -n "${PLAN_ID:-}" ] && slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
if [ -n "${PLAN_ID:-}" ]; then
# A set PLAN_ID is a BINDING, not a hint (issue #237). This inline resolver
# is the one the hooks actually run, so it carries the same rule as
# resolve-plan-dir.sh: a selector that names no directory, fails slug
# validation, or fails containment refuses instead of falling through to
# .active_plan and newest-by-mtime. The fall-through is what let a
# one-character typo inject a DIFFERENT plan while attest-plan.sh locked
# that same wrong plan at rc=0.
#
# Unlike the PWF_PLAN_ROOT refusal above, the notice is userprompt-only.
# pretool fires per tool call and precompact carries no plan body, so
# 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
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
echo "[planning-with-files] PLAN_ID does not name a plan directory under .planning: ${PLAN_ID} — nothing injected. Fix or unset the pin; a broken pin fails closed rather than selecting another plan."
fi
exit 0
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
@@ -476,12 +496,16 @@ if [ "$SCOPE" = "root" ]; then
PROGRESS_FILE="${PLAN_PREFIX}progress.md"
ATTEST_FILE="${PLAN_PREFIX}.plan-attestation"
MODE_FILE="${PLAN_PREFIX}.mode"
ROOT_MODE_FILE=""
NONCE_FILE="${PLAN_PREFIX}.nonce"
else
PLAN_FILE="${RESOLVED}/task_plan.md"
PROGRESS_FILE="${RESOLVED}/progress.md"
ATTEST_FILE="${RESOLVED}/.attestation"
MODE_FILE="${RESOLVED}/.mode"
# The project's own .mode, when it has one (issue #238). In root scope
# MODE_FILE already IS that file, so the second source stays empty.
ROOT_MODE_FILE="${PLAN_PREFIX}.mode"
NONCE_FILE="${RESOLVED}/.nonce"
fi
[ -f "$PLAN_FILE" ] || exit 0
@@ -853,11 +877,52 @@ fi
# gated mode to legacy behavior (platform-critical: per-tool-call injection not
# suppressed, oracle re-hash skipped, raw progress tail injected). Use a grep
# token test, the same pattern check-complete.sh guard 1 uses.
# --- Root .mode is a FLOOR, not a default that slug scope replaces (#238). ---
# A project makes attestation mandatory by committing a root .mode, which is a
# reviewed project setting. Slug scope used to read ONLY the slug's .mode, and
# init-session.sh writes no .mode unless --autonomous or --gated was passed, so
# `init-session.sh <name>` produced a plan with no mode, no attestation
# requirement and full injection: one agent-invocable command turned the
# project's policy off.
#
# mode_has answers for a strictness-RAISING token: present in EITHER file. A
# slug may opt into autonomous/gated where the root left it unset; it can no
# longer opt out of what the root committed.
#
# mode_relax_allowed answers for the one strictness-LOWERING token
# (plan-guard-off): the slug must carry it AND, when the project committed a
# root .mode, that file must carry it too. A slug alone cannot switch off a
# protection the project kept on.
#
# With no root .mode present ROOT_MODE_FILE is either empty (root scope) or
# names a missing file, so the effective token set is exactly the slug's and
# existing projects are byte-identical.
mode_has() {
_mh_token="$1"
if [ -f "$MODE_FILE" ] && grep -q "$_mh_token" "$MODE_FILE" 2>/dev/null; then
return 0
fi
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ] \
&& grep -q "$_mh_token" "$ROOT_MODE_FILE" 2>/dev/null; then
return 0
fi
return 1
}
mode_relax_allowed() {
_mr_token="$1"
[ -f "$MODE_FILE" ] || return 1
grep -q "$_mr_token" "$MODE_FILE" 2>/dev/null || return 1
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ]; then
grep -q "$_mr_token" "$ROOT_MODE_FILE" 2>/dev/null || return 1
fi
return 0
}
MODE=""
if [ -f "$MODE_FILE" ]; then
grep -q 'autonomous' "$MODE_FILE" 2>/dev/null && MODE='autonomous'
grep -q 'gate' "$MODE_FILE" 2>/dev/null && MODE='gated'
fi
mode_has 'autonomous' && MODE='autonomous'
mode_has 'gate' && MODE='gated'
# In autonomous/gated mode the per-tool-call injection is dropped (recitation
# policy): strong models do not need the plan re-recited before every tool call,
@@ -881,7 +946,7 @@ fi
SMART=0
if [ "${PWF_INJECT:-}" = "smart" ]; then
SMART=1
elif [ -f "$MODE_FILE" ] && grep -q 'inject-smart' "$MODE_FILE" 2>/dev/null; then
elif mode_has 'inject-smart'; then
SMART=1
fi
@@ -1149,7 +1214,7 @@ esac
# holding the stale copy. Per-session keying needs PWF_SESSION_ID, which most
# hosts never set.
GUARD=1
[ -f "$MODE_FILE" ] && grep -q 'plan-guard-off' "$MODE_FILE" 2>/dev/null && GUARD=0
mode_relax_allowed 'plan-guard-off' && GUARD=0
[ "${PWF_PLAN_GUARD:-}" = "0" ] && GUARD=0
if [ "$GUARD" = "1" ]; then
# Same user-private cache root and same absolute-path key as the attestation
@@ -68,6 +68,15 @@ if [ -n "${ARG_DIR}" ]; then
elif [ -f "${RESOLVER}" ]; then
PLAN_DIR="$(sh "${RESOLVER}" 2>/dev/null)"
if [ -z "${PLAN_DIR}" ] || [ ! -d "${PLAN_DIR}" ]; then
# Explicit selectors are bindings, not hints (issue #237). A rejected
# PLAN_ID or PWF_PLAN_ROOT must not fall back to the cwd: this summary
# is injected into autonomous turns, so reporting the ROOT plan's
# phase counts under a mistyped pin feeds the loop another plan's
# termination signal. Degrade loudly, the same way a missing resolver
# already does.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
emit_unavailable "explicit PLAN_ID or PWF_PLAN_ROOT did not resolve"
fi
PLAN_DIR="."
fi
else
@@ -74,27 +74,49 @@ if [ -f "${INJ}" ]; then
ok "injection: silent because no plan exists here (correct behavior)"
fi
else
# Classify on the DATA FRAMING first, never on substrings of the whole
# blob (issue #236). ${OUT} carries the plan body VERBATIM inside
# ===BEGIN-PWF-DATA=== fences, so a bare substring test also matches
# plan prose: a phase line reading "fix the false PLAN TAMPERED
# warning" made the doctor report a hash mismatch on a correctly
# attested plan.
#
# Every refusal path in inject-plan.sh prints its banner and exits
# before frame_file runs, so a frame in the output proves injection
# happened and rules out every refusal. Output WITHOUT a frame is by
# construction a notice, which is why the banner arms sit under the
# else side and the default arm warns instead of passing. A banner
# whose wording drifts then degrades to a generic warning rather than
# to a silent PASS: that is exactly how the stale
# "PWF_PLAN_ROOT is not a directory" literal (which was never a
# substring of what inject-plan.sh emits) reported PASS on a fully
# dark-hooks state.
case "${OUT}" in
*'PLAN TAMPERED'*)
*'===BEGIN-PWF-DATA'*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
;;
*'[PLAN TAMPERED'*)
warn "injection: plan is attested but the hash mismatches — run /plan-attest (or scripts/attest-plan.sh) to re-approve the current plan"
;;
*'requires attested plan'*)
warn "injection: v3 mode without attestation — run attest-plan once to arm injection"
;;
*'Session isolation is armed'*)
# Refusal notice, not plan context: reporting its byte count as
# PASS told a dark user their hooks were fine.
warn "injection: session isolation refuses this session — attach it with PWF_SESSION_ID=<id> plus .planning/sessions/<id>.attached, or delete the .planning/sessions/ dir (stale ones survive earlier Codex use and copied project trees) to turn isolation off"
;;
*'Ambiguous plan'*)
warn "injection: nested-plan ambiguity — a project directly below this cwd carries its own plan, so hooks refuse to guess. Pin the thread with PWF_PLAN_ROOT=<absolute project root> or PLAN_ID=<slug>"
;;
*'PWF_PLAN_ROOT is not a directory'*)
warn "injection: PWF_PLAN_ROOT points at a missing directory — fix or unset the pin; a broken pin fails closed and injects nothing"
*'PWF_PLAN_ROOT is not a supported absolute local directory'*)
warn "injection: PWF_PLAN_ROOT points at something that is not an absolute local directory — fix or unset the pin; a broken pin fails closed and injects nothing"
;;
*'PLAN_ID does not name a plan directory'*)
warn "injection: PLAN_ID names no plan directory under .planning — fix or unset the pin; a set PLAN_ID is a binding and fails closed rather than selecting another plan"
;;
*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
warn "injection: inject-plan.sh emitted ${BYTES} bytes but no ===BEGIN-PWF-DATA frame, so no plan context reached the model. This is a refusal notice this doctor does not recognize; read it directly with: sh scripts/inject-plan.sh --context=userprompt"
;;
esac
fi
@@ -130,6 +130,13 @@ function Test-WithinRoot {
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
# no directory, fails slug validation, or fails containment terminates
# resolution instead of falling through to .active_plan and newest-by-mtime:
# the fall-through let a one-character typo attest and inject a DIFFERENT plan
# at rc=0. Emptiness is the fail-closed signal on this channel, matching
# resolve-plan-dir.sh and the PWF_PLAN_ROOT pin. An empty $env:PLAN_ID is
# falsy here and still means "unset".
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
@@ -138,6 +145,7 @@ if ($env:PLAN_ID) {
exit 0
}
}
exit 0
}
# Get-Item observes the link object even when its target is missing, unlike
@@ -297,7 +297,34 @@ resolve_latest_dir() {
return 1
}
if resolve_from_env; then exit 0; fi
# A set PLAN_ID is a BINDING, not a hint (issue #237).
#
# resolve_from_env returns 1 both when no selector was set and when the
# selector was rejected, so continuing the chain after it turned a
# one-character typo into a silent switch: .active_plan or newest-by-mtime
# answered instead, attest-plan.sh locked THAT plan at rc=0, and injection
# followed the attestation onto it. commands/plan-attest.md already promised
# the opposite ("It never falls back to another plan").
#
# Any non-empty PLAN_ID therefore terminates resolution here, whether it was
# rejected for slug shape (traversal), for naming no directory, or for failing
# containment. The caller receives an empty result and takes its own
# fail-closed path rather than a different plan. PWF_PLAN_ROOT, the sibling
# selector, has failed closed on any bad value since #212; the two selectors
# now agree.
#
# An EMPTY PLAN_ID still means "unset": init-session.sh passes
# PLAN_ID="${PLAN_ID:-}" into attest-plan.sh on the legacy path and depends on
# that spelling resolving the root plan.
#
# Exit status stays 0 on the refusal (see the header contract). Emptiness is
# the fail-closed signal on this channel, exactly as the PWF_PLAN_ROOT guard
# above already does it; a non-zero status would kill callers running under
# set -e for a condition that is not an internal error.
if [ -n "${PLAN_ID:-}" ]; then
resolve_from_env && exit 0
exit 0
fi
if resolve_from_active_file; then exit 0; fi
if resolve_latest_dir; then exit 0; fi
exit 0
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "planning-with-files",
"version": "3.14.0",
"version": "3.16.0",
"description": "Persistent project planning for Codex. Opt-in lifecycle hooks inject selected plan context; automatic recovery uses project files only. Explicit catchup modes may read same-project local session records to emit aggregate counts or bounded nonce-framed excerpts. Optional gated mode can request continuation on capable hosts and never runs Markdown-declared commands. No network upload path.",
"author": {
"name": "OthmanAdi",
+1 -1
View File
@@ -50,7 +50,7 @@
],
"PostToolUse": [
{
"matcher": "Bash|apply_patch|Edit|Write",
"matcher": "apply_patch|Edit|Write",
"hooks": [
{
"type": "command",
+44 -2
View File
@@ -6,9 +6,51 @@
HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
PLAN_DIR="$(sh "${HOOK_DIR}/resolve-plan-dir.sh" 2>/dev/null)"
# An explicit PLAN_ID is a binding, not a hint (issue #237). When the shared
# resolver rejected one it emits nothing, and the legacy-root fallback below
# would answer for a plan the operator never named. Stay silent instead; the
# once-per-turn user-prompt-submit hook carries the notice.
[ -z "$PLAN_DIR" ] && [ -n "${PLAN_ID:-}" ] && exit 0
PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
if [ -f "$PLAN_FILE" ]; then
echo "[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."
[ -f "$PLAN_FILE" ] || exit 0
# --- Once-per-turn throttle (issue #239). ---
# The reminder is a constant string, so every repeat after the first in a turn
# carries no information: it names no tool, no file and no phase. The Codex
# matcher fired on every shell command, so a session running twenty of them got
# twenty identical lines. user-prompt-submit.sh fires once per turn and clears
# this marker; the first post-tool fire of the turn sets it.
#
# The marker lives in the user's private cache, never in the plan directory:
# that directory is shared project state. Cache root and key derivation match
# hooks/claude-hook.sh and the slots inject-plan.sh already uses, so the two
# routes throttle the same way. When no cache root can be created the throttle
# is skipped rather than the nudge suppressed, so a broken cache cannot
# silently remove the reminder.
if [ -n "${XDG_CACHE_HOME:-}" ]; then
TURN_ROOT="${XDG_CACHE_HOME}/pwf-turn"
elif [ -n "${HOME:-}" ]; then
TURN_ROOT="${HOME}/.cache/pwf-turn"
else
TURN_ROOT="${TMPDIR:-/tmp}/pwf-turn"
fi
TURN_MARKER=""
if mkdir -p "$TURN_ROOT" 2>/dev/null; then
case "$PLAN_FILE" in
/*|[A-Za-z]:*|\\\\*) TURN_KEY_SRC="$PLAN_FILE" ;;
*) TURN_KEY_SRC="${PWD}/${PLAN_FILE}" ;;
esac
TURN_KEY_SRC="${TURN_KEY_SRC}|${PWF_SESSION_ID:-}"
TURN_KEY=$(printf '%s' "$TURN_KEY_SRC" \
| { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } \
| awk '{print $1}' | cut -c1-16)
[ -n "$TURN_KEY" ] && TURN_MARKER="${TURN_ROOT}/${TURN_KEY}"
fi
if [ -n "$TURN_MARKER" ]; then
[ -e "$TURN_MARKER" ] && exit 0
: > "$TURN_MARKER" 2>/dev/null || :
fi
echo "[planning-with-files] Update progress.md with what you just did. If a phase is now complete, update task_plan.md status."
exit 0
+12 -1
View File
@@ -15,7 +15,18 @@ def main() -> None:
stdout, _ = adapter.run_shell_script("post-tool-use.sh", root)
if stdout:
adapter.emit_json({"systemMessage": stdout})
# The nudge is addressed to Claude, so it belongs in the model's
# context, not in a systemMessage (issue #239). systemMessage is a
# warning shown to the USER, so the instruction never reached the model
# while the person saw it after every matching tool call.
# pre_tool_use.py and run_sh.py already emit this shape for their own
# events; this path had simply never been moved over.
adapter.emit_json({
"hookSpecificOutput": {
"hookEventName": "PostToolUse",
"additionalContext": stdout,
}
})
if __name__ == "__main__":
+5
View File
@@ -7,6 +7,11 @@
HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
PLAN_DIR="$(sh "${HOOK_DIR}/resolve-plan-dir.sh" 2>/dev/null)"
# An explicit PLAN_ID is a binding, not a hint (issue #237). When the shared
# resolver rejected one it emits nothing, and the legacy-root fallback below
# would carry the wrong plan through compaction, which is the one moment the
# session cannot re-read it. Stay silent instead.
[ -z "$PLAN_DIR" ] && [ -n "${PLAN_ID:-}" ] && exit 0
PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
if [ ! -f "$PLAN_FILE" ]; then
+5
View File
@@ -10,6 +10,11 @@ fi
HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
PLAN_DIR="$(sh "${HOOK_DIR}/resolve-plan-dir.sh" 2>/dev/null)"
# An explicit PLAN_ID is a binding, not a hint (issue #237). When the shared
# resolver rejected one it emits nothing, and the legacy-root fallback below
# would recite a plan the operator never named on every tool call. Stay silent
# instead; the once-per-turn user-prompt-submit hook carries the notice.
[ -z "$PLAN_DIR" ] && [ -n "${PLAN_ID:-}" ] && exit 0
PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
if [ -f "$PLAN_FILE" ]; then
+5
View File
@@ -6,6 +6,11 @@
HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
PLAN_DIR="$(sh "${HOOK_DIR}/resolve-plan-dir.sh" 2>/dev/null)"
# An explicit PLAN_ID is a binding, not a hint (issue #237). When the shared
# resolver rejected one it emits nothing, and the legacy-root fallback below
# would decide whether this run may stop from a plan the operator never named.
# Allow the stop rather than gating on the wrong plan.
[ -z "$PLAN_DIR" ] && [ -n "${PLAN_ID:-}" ] && exit 0
PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
if [ ! -f "$PLAN_FILE" ]; then
+40
View File
@@ -79,12 +79,52 @@ PLAN_DIR="$(sh "${HOOK_DIR}/resolve-plan-dir.sh" 2>/dev/null)"
if [ -n "$PLAN_DIR" ]; then
PLAN_FILE="${PLAN_DIR}/task_plan.md"
PROGRESS_FILE="${PLAN_DIR}/progress.md"
elif [ -n "${PLAN_ID:-}" ]; then
# An explicit PLAN_ID is a binding, not a hint (issue #237). The shared
# resolver rejected it, so the legacy-root fallback below would inject a
# plan the operator never named. This hook fires once per turn, so one
# diagnosable line is not spam and the alternative is a dark session with
# no stated cause. Wording matches scripts/inject-plan.sh so all routes say
# the same thing.
echo "[planning-with-files] PLAN_ID does not name a plan directory under .planning: ${PLAN_ID} — nothing injected. Fix or unset the pin; a broken pin fails closed rather than selecting another plan."
exit 0
else
PLAN_FILE="${PLAN_PREFIX}task_plan.md"
PROGRESS_FILE="${PLAN_PREFIX}progress.md"
fi
[ -f "$PLAN_FILE" ] || exit 0
# --- Re-arm the once-per-turn PostToolUse nudge (issue #239). ---
# One user message is one turn, and this hook fires once per turn, so clearing
# the marker here is what makes the nudge appear once after the first write
# instead of after every matching tool call.
#
# The key is computed from post-tool-use.sh's OWN plan-file expression, not
# from $PLAN_FILE above. This hook resolves a PWF_PLAN_ROOT pin and that one
# does not, so the two spellings diverge under a pin; keying off the shared
# expression keeps both sides on one marker. A mismatch here would not be
# loud: the marker would never be cleared and the nudge would fire once per
# session instead of once per turn.
TURN_PLAN_FILE="${PLAN_DIR:+${PLAN_DIR}/}task_plan.md"
if [ -n "${XDG_CACHE_HOME:-}" ]; then
TURN_ROOT="${XDG_CACHE_HOME}/pwf-turn"
elif [ -n "${HOME:-}" ]; then
TURN_ROOT="${HOME}/.cache/pwf-turn"
else
TURN_ROOT="${TMPDIR:-/tmp}/pwf-turn"
fi
if [ -d "$TURN_ROOT" ]; then
case "$TURN_PLAN_FILE" in
/*|[A-Za-z]:*|\\\\*) TURN_KEY_SRC="$TURN_PLAN_FILE" ;;
*) TURN_KEY_SRC="${PWD}/${TURN_PLAN_FILE}" ;;
esac
TURN_KEY_SRC="${TURN_KEY_SRC}|${PWF_SESSION_ID:-}"
TURN_KEY=$(printf '%s' "$TURN_KEY_SRC" \
| { sha256sum 2>/dev/null || shasum -a 256 2>/dev/null; } \
| awk '{print $1}' | cut -c1-16)
[ -n "$TURN_KEY" ] && rm -f -- "${TURN_ROOT}/${TURN_KEY}" 2>/dev/null || :
fi
# Session isolation: if .planning/sessions/ exists, only attached sessions see
# plan context. Absence of the sessions dir means legacy single-session mode —
# all sessions in the cwd receive context to preserve backward compatibility.
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.codex/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.14.0"
version: "3.16.0"
---
@@ -108,7 +108,18 @@ case "${1:-}" in
esac
plan_file="$(resolve_plan_file)" || {
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
# Name the actual cause. "No task_plan.md found" is true but misleading
# when the plan exists and an explicit selector was rejected: before #237
# a mistyped PLAN_ID attested a DIFFERENT plan at rc=0, and an operator
# who now sees a generic not-found is likely to go looking for the wrong
# problem. The selectors are bindings, so say which one refused.
if [ -n "${PLAN_ID:-}" ]; then
printf "[plan-attest] PLAN_ID=%s names no plan directory under .planning. An explicit selector is a binding: nothing was attested and no other plan was substituted.\n" "${PLAN_ID}" >&2
elif [ -n "${PWF_PLAN_ROOT:-}" ]; then
printf "[plan-attest] PWF_PLAN_ROOT=%s did not resolve to a project root holding a plan. An explicit pin is a binding: nothing was attested and no other plan was substituted.\n" "${PWF_PLAN_ROOT}" >&2
else
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
fi
exit 1
}
@@ -107,13 +107,27 @@ if (-not $Gate) {
# ---- Gate path (-Gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate".
# Guard 1: gated mode. A .mode file must contain "gate".
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>\.mode let a slug plan with no .mode
# drop a project-committed gate. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope $PlanDir already IS the
# project root, so the second source is skipped and behavior is unchanged.
$modeFile = Join-Path $PlanDir ".mode"
$rootForMode = if ($env:PWF_PLAN_ROOT) { $env:PWF_PLAN_ROOT } else { "." }
$rootModeFile = $null
if ($PlanDir -ne $rootForMode -and $PlanDir -ne ".") {
$rootModeFile = Join-Path $rootForMode ".mode"
}
$gatedMode = $false
if (Test-Path $modeFile) {
$modeContent = Get-Content $modeFile -Raw -ErrorAction SilentlyContinue
foreach ($candidateMode in @($modeFile, $rootModeFile)) {
if (-not $candidateMode) { continue }
if (-not (Test-Path $candidateMode)) { continue }
$modeContent = Get-Content $candidateMode -Raw -ErrorAction SilentlyContinue
if ($null -ne $modeContent -and $modeContent -match "gate") {
$gatedMode = $true
break
}
}
if (-not $gatedMode) {
@@ -60,6 +60,14 @@ else
if [ -n "${RESOLVED_DIR}" ] && [ -f "${RESOLVED_DIR}/task_plan.md" ]; then
PLAN_FILE="${RESOLVED_DIR}/task_plan.md"
PLAN_DIR="${RESOLVED_DIR}"
elif [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
# Explicit selectors are bindings, not hints (issue #237). The shared
# resolver rejected one, so the legacy cwd fallback below must not run:
# answering a mistyped pin with the ROOT plan's completion state is the
# same wrong-plan harm the binding removes, and here it would decide
# whether an autonomous run is allowed to stop.
echo "[planning-with-files] An explicit PLAN_ID or PWF_PLAN_ROOT did not resolve to a plan; no completion state was read and no other plan was substituted."
exit 0
else
PLAN_FILE="task_plan.md"
PLAN_DIR="."
@@ -131,10 +139,30 @@ fi
# ---- Gate path (--gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate". Absent or other
# Guard 1: gated mode. A .mode file must contain "gate". Absent or other
# content means advisory mode (legacy behavior preserved).
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>/.mode let a slug plan with no .mode
# drop a project-committed gate, the same way it dropped the attestation
# requirement in inject-plan.sh. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope PLAN_DIR already IS the
# project root, so the second source stays empty and behavior is unchanged.
MODE_FILE="${PLAN_DIR}/.mode"
if [ ! -f "${MODE_FILE}" ] || ! grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
ROOT_MODE_FILE=""
_root_for_mode="${PWF_PLAN_ROOT:-.}"
if [ "${PLAN_DIR}" != "${_root_for_mode}" ] && [ "${PLAN_DIR}" != "." ]; then
ROOT_MODE_FILE="${_root_for_mode}/.mode"
fi
GATED=0
if [ -f "${MODE_FILE}" ] && grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ] && [ -n "${ROOT_MODE_FILE}" ] && [ -f "${ROOT_MODE_FILE}" ] \
&& grep -q "gate" "${ROOT_MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ]; then
advisory_report
exit 0
fi
@@ -152,6 +152,33 @@ gen_nonce() {
# $1 = plan dir (absolute or relative); dotfiles live directly inside it.
# $2 = plan file path (task_plan.md) used for auto-attestation resolution.
# No-op when MODE is empty (legacy path stays byte-equivalent to v2.43.0).
# Raise MODE to the project's committed floor before the side effects run
# (issue #238). A project that ships a root .mode has made that setting a
# reviewed part of the repo; a new slug plan must not start below it. Without
# this, `init-session.sh <name>` created a plan with no .mode at all, and the
# project's attestation requirement became a flag the agent chose at plan
# creation time.
#
# inject-plan.sh enforces the same floor at read time, so this is not the
# guard. It exists so the effective policy is VISIBLE in the plan directory
# rather than only inside the resolver, and so the new plan gets the nonce and
# the auto-attestation that autonomous mode needs to inject at all.
#
# An explicit --autonomous/--gated is never lowered: gated stays gated.
inherit_root_mode() {
_root_mode="${PWD}/.mode"
[ -f "${_root_mode}" ] || return 0
[ "$MODE" = "gated" ] && return 0
if grep -q 'gate' "${_root_mode}" 2>/dev/null; then
MODE='gated'
return 0
fi
if grep -q 'autonomous' "${_root_mode}" 2>/dev/null; then
MODE='autonomous'
fi
return 0
}
apply_v3_mode() {
_mode_dir="$1"
_mode_plan="$2"
@@ -367,6 +394,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
@@ -254,8 +254,28 @@ SCOPE=""
EXPLICIT=0
[ -n "$PLAN_PREFIX" ] && EXPLICIT=1
[ "$SESSION_ATTACHED" = "1" ] && EXPLICIT=1
if [ -n "${PLAN_ID:-}" ] && slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
if [ -n "${PLAN_ID:-}" ]; then
# A set PLAN_ID is a BINDING, not a hint (issue #237). This inline resolver
# is the one the hooks actually run, so it carries the same rule as
# resolve-plan-dir.sh: a selector that names no directory, fails slug
# validation, or fails containment refuses instead of falling through to
# .active_plan and newest-by-mtime. The fall-through is what let a
# one-character typo inject a DIFFERENT plan while attest-plan.sh locked
# that same wrong plan at rc=0.
#
# Unlike the PWF_PLAN_ROOT refusal above, the notice is userprompt-only.
# pretool fires per tool call and precompact carries no plan body, so
# 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
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
echo "[planning-with-files] PLAN_ID does not name a plan directory under .planning: ${PLAN_ID} — nothing injected. Fix or unset the pin; a broken pin fails closed rather than selecting another plan."
fi
exit 0
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
@@ -476,12 +496,16 @@ if [ "$SCOPE" = "root" ]; then
PROGRESS_FILE="${PLAN_PREFIX}progress.md"
ATTEST_FILE="${PLAN_PREFIX}.plan-attestation"
MODE_FILE="${PLAN_PREFIX}.mode"
ROOT_MODE_FILE=""
NONCE_FILE="${PLAN_PREFIX}.nonce"
else
PLAN_FILE="${RESOLVED}/task_plan.md"
PROGRESS_FILE="${RESOLVED}/progress.md"
ATTEST_FILE="${RESOLVED}/.attestation"
MODE_FILE="${RESOLVED}/.mode"
# The project's own .mode, when it has one (issue #238). In root scope
# MODE_FILE already IS that file, so the second source stays empty.
ROOT_MODE_FILE="${PLAN_PREFIX}.mode"
NONCE_FILE="${RESOLVED}/.nonce"
fi
[ -f "$PLAN_FILE" ] || exit 0
@@ -853,11 +877,52 @@ fi
# gated mode to legacy behavior (platform-critical: per-tool-call injection not
# suppressed, oracle re-hash skipped, raw progress tail injected). Use a grep
# token test, the same pattern check-complete.sh guard 1 uses.
# --- Root .mode is a FLOOR, not a default that slug scope replaces (#238). ---
# A project makes attestation mandatory by committing a root .mode, which is a
# reviewed project setting. Slug scope used to read ONLY the slug's .mode, and
# init-session.sh writes no .mode unless --autonomous or --gated was passed, so
# `init-session.sh <name>` produced a plan with no mode, no attestation
# requirement and full injection: one agent-invocable command turned the
# project's policy off.
#
# mode_has answers for a strictness-RAISING token: present in EITHER file. A
# slug may opt into autonomous/gated where the root left it unset; it can no
# longer opt out of what the root committed.
#
# mode_relax_allowed answers for the one strictness-LOWERING token
# (plan-guard-off): the slug must carry it AND, when the project committed a
# root .mode, that file must carry it too. A slug alone cannot switch off a
# protection the project kept on.
#
# With no root .mode present ROOT_MODE_FILE is either empty (root scope) or
# names a missing file, so the effective token set is exactly the slug's and
# existing projects are byte-identical.
mode_has() {
_mh_token="$1"
if [ -f "$MODE_FILE" ] && grep -q "$_mh_token" "$MODE_FILE" 2>/dev/null; then
return 0
fi
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ] \
&& grep -q "$_mh_token" "$ROOT_MODE_FILE" 2>/dev/null; then
return 0
fi
return 1
}
mode_relax_allowed() {
_mr_token="$1"
[ -f "$MODE_FILE" ] || return 1
grep -q "$_mr_token" "$MODE_FILE" 2>/dev/null || return 1
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ]; then
grep -q "$_mr_token" "$ROOT_MODE_FILE" 2>/dev/null || return 1
fi
return 0
}
MODE=""
if [ -f "$MODE_FILE" ]; then
grep -q 'autonomous' "$MODE_FILE" 2>/dev/null && MODE='autonomous'
grep -q 'gate' "$MODE_FILE" 2>/dev/null && MODE='gated'
fi
mode_has 'autonomous' && MODE='autonomous'
mode_has 'gate' && MODE='gated'
# In autonomous/gated mode the per-tool-call injection is dropped (recitation
# policy): strong models do not need the plan re-recited before every tool call,
@@ -881,7 +946,7 @@ fi
SMART=0
if [ "${PWF_INJECT:-}" = "smart" ]; then
SMART=1
elif [ -f "$MODE_FILE" ] && grep -q 'inject-smart' "$MODE_FILE" 2>/dev/null; then
elif mode_has 'inject-smart'; then
SMART=1
fi
@@ -1149,7 +1214,7 @@ esac
# holding the stale copy. Per-session keying needs PWF_SESSION_ID, which most
# hosts never set.
GUARD=1
[ -f "$MODE_FILE" ] && grep -q 'plan-guard-off' "$MODE_FILE" 2>/dev/null && GUARD=0
mode_relax_allowed 'plan-guard-off' && GUARD=0
[ "${PWF_PLAN_GUARD:-}" = "0" ] && GUARD=0
if [ "$GUARD" = "1" ]; then
# Same user-private cache root and same absolute-path key as the attestation
@@ -68,6 +68,15 @@ if [ -n "${ARG_DIR}" ]; then
elif [ -f "${RESOLVER}" ]; then
PLAN_DIR="$(sh "${RESOLVER}" 2>/dev/null)"
if [ -z "${PLAN_DIR}" ] || [ ! -d "${PLAN_DIR}" ]; then
# Explicit selectors are bindings, not hints (issue #237). A rejected
# PLAN_ID or PWF_PLAN_ROOT must not fall back to the cwd: this summary
# is injected into autonomous turns, so reporting the ROOT plan's
# phase counts under a mistyped pin feeds the loop another plan's
# termination signal. Degrade loudly, the same way a missing resolver
# already does.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
emit_unavailable "explicit PLAN_ID or PWF_PLAN_ROOT did not resolve"
fi
PLAN_DIR="."
fi
else
@@ -74,27 +74,49 @@ if [ -f "${INJ}" ]; then
ok "injection: silent because no plan exists here (correct behavior)"
fi
else
# Classify on the DATA FRAMING first, never on substrings of the whole
# blob (issue #236). ${OUT} carries the plan body VERBATIM inside
# ===BEGIN-PWF-DATA=== fences, so a bare substring test also matches
# plan prose: a phase line reading "fix the false PLAN TAMPERED
# warning" made the doctor report a hash mismatch on a correctly
# attested plan.
#
# Every refusal path in inject-plan.sh prints its banner and exits
# before frame_file runs, so a frame in the output proves injection
# happened and rules out every refusal. Output WITHOUT a frame is by
# construction a notice, which is why the banner arms sit under the
# else side and the default arm warns instead of passing. A banner
# whose wording drifts then degrades to a generic warning rather than
# to a silent PASS: that is exactly how the stale
# "PWF_PLAN_ROOT is not a directory" literal (which was never a
# substring of what inject-plan.sh emits) reported PASS on a fully
# dark-hooks state.
case "${OUT}" in
*'PLAN TAMPERED'*)
*'===BEGIN-PWF-DATA'*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
;;
*'[PLAN TAMPERED'*)
warn "injection: plan is attested but the hash mismatches — run /plan-attest (or scripts/attest-plan.sh) to re-approve the current plan"
;;
*'requires attested plan'*)
warn "injection: v3 mode without attestation — run attest-plan once to arm injection"
;;
*'Session isolation is armed'*)
# Refusal notice, not plan context: reporting its byte count as
# PASS told a dark user their hooks were fine.
warn "injection: session isolation refuses this session — attach it with PWF_SESSION_ID=<id> plus .planning/sessions/<id>.attached, or delete the .planning/sessions/ dir (stale ones survive earlier Codex use and copied project trees) to turn isolation off"
;;
*'Ambiguous plan'*)
warn "injection: nested-plan ambiguity — a project directly below this cwd carries its own plan, so hooks refuse to guess. Pin the thread with PWF_PLAN_ROOT=<absolute project root> or PLAN_ID=<slug>"
;;
*'PWF_PLAN_ROOT is not a directory'*)
warn "injection: PWF_PLAN_ROOT points at a missing directory — fix or unset the pin; a broken pin fails closed and injects nothing"
*'PWF_PLAN_ROOT is not a supported absolute local directory'*)
warn "injection: PWF_PLAN_ROOT points at something that is not an absolute local directory — fix or unset the pin; a broken pin fails closed and injects nothing"
;;
*'PLAN_ID does not name a plan directory'*)
warn "injection: PLAN_ID names no plan directory under .planning — fix or unset the pin; a set PLAN_ID is a binding and fails closed rather than selecting another plan"
;;
*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
warn "injection: inject-plan.sh emitted ${BYTES} bytes but no ===BEGIN-PWF-DATA frame, so no plan context reached the model. This is a refusal notice this doctor does not recognize; read it directly with: sh scripts/inject-plan.sh --context=userprompt"
;;
esac
fi
@@ -130,6 +130,13 @@ function Test-WithinRoot {
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
# no directory, fails slug validation, or fails containment terminates
# resolution instead of falling through to .active_plan and newest-by-mtime:
# the fall-through let a one-character typo attest and inject a DIFFERENT plan
# at rc=0. Emptiness is the fail-closed signal on this channel, matching
# resolve-plan-dir.sh and the PWF_PLAN_ROOT pin. An empty $env:PLAN_ID is
# falsy here and still means "unset".
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
@@ -138,6 +145,7 @@ if ($env:PLAN_ID) {
exit 0
}
}
exit 0
}
# Get-Item observes the link object even when its target is missing, unlike
@@ -297,7 +297,34 @@ resolve_latest_dir() {
return 1
}
if resolve_from_env; then exit 0; fi
# A set PLAN_ID is a BINDING, not a hint (issue #237).
#
# resolve_from_env returns 1 both when no selector was set and when the
# selector was rejected, so continuing the chain after it turned a
# one-character typo into a silent switch: .active_plan or newest-by-mtime
# answered instead, attest-plan.sh locked THAT plan at rc=0, and injection
# followed the attestation onto it. commands/plan-attest.md already promised
# the opposite ("It never falls back to another plan").
#
# Any non-empty PLAN_ID therefore terminates resolution here, whether it was
# rejected for slug shape (traversal), for naming no directory, or for failing
# containment. The caller receives an empty result and takes its own
# fail-closed path rather than a different plan. PWF_PLAN_ROOT, the sibling
# selector, has failed closed on any bad value since #212; the two selectors
# now agree.
#
# An EMPTY PLAN_ID still means "unset": init-session.sh passes
# PLAN_ID="${PLAN_ID:-}" into attest-plan.sh on the legacy path and depends on
# that spelling resolving the root plan.
#
# Exit status stays 0 on the refusal (see the header contract). Emptiness is
# the fail-closed signal on this channel, exactly as the PWF_PLAN_ROOT guard
# above already does it; a non-zero status would kill callers running under
# set -e for a condition that is not an internal error.
if [ -n "${PLAN_ID:-}" ]; then
resolve_from_env && exit 0
exit 0
fi
if resolve_from_active_file; then exit 0; fi
if resolve_latest_dir; then exit 0; fi
exit 0
@@ -181,7 +181,7 @@ Helper scripts for automation:
- `scripts/init-session.sh` — Initialize planning files. With a name arg, creates an isolated plan under `.planning/YYYY-MM-DD-<slug>/` for parallel task workflows. Without args, writes `task_plan.md` at project root (legacy mode, backward-compatible).
- `scripts/set-active-plan.sh` — Switch the active plan pointer (`.planning/.active_plan`). Run with a plan ID to switch; run without args to show which plan is current.
- `scripts/resolve-plan-dir.sh` — Resolve the active plan directory. Checks `$PLAN_ID` env var first, then `.planning/.active_plan`, then newest plan dir by mtime, then falls back to project root (legacy). Used internally by hooks.
- `scripts/resolve-plan-dir.sh` — Resolve the active plan directory. A set `$PLAN_ID` is a binding: it resolves or resolution stops, never another plan (issue #237). With no `$PLAN_ID`, checks `.planning/.active_plan`, then newest plan dir by mtime, then falls back to project root (legacy). Used internally by hooks.
- `scripts/check-complete.sh` — Verify all phases in the active plan are complete.
- `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history. OpenCode uses its read-only SQLite store.
- `scripts/attest-plan.sh` (and `.ps1`) — Lock the current `task_plan.md` content with a SHA-256 attestation (v2.37.0). Hooks then refuse to inject plan content if the file diverges from the attested hash. Use `--show` to print the stored hash, `--clear` to remove the attestation.
@@ -108,7 +108,18 @@ case "${1:-}" in
esac
plan_file="$(resolve_plan_file)" || {
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
# Name the actual cause. "No task_plan.md found" is true but misleading
# when the plan exists and an explicit selector was rejected: before #237
# a mistyped PLAN_ID attested a DIFFERENT plan at rc=0, and an operator
# who now sees a generic not-found is likely to go looking for the wrong
# problem. The selectors are bindings, so say which one refused.
if [ -n "${PLAN_ID:-}" ]; then
printf "[plan-attest] PLAN_ID=%s names no plan directory under .planning. An explicit selector is a binding: nothing was attested and no other plan was substituted.\n" "${PLAN_ID}" >&2
elif [ -n "${PWF_PLAN_ROOT:-}" ]; then
printf "[plan-attest] PWF_PLAN_ROOT=%s did not resolve to a project root holding a plan. An explicit pin is a binding: nothing was attested and no other plan was substituted.\n" "${PWF_PLAN_ROOT}" >&2
else
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
fi
exit 1
}
@@ -107,13 +107,27 @@ if (-not $Gate) {
# ---- Gate path (-Gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate".
# Guard 1: gated mode. A .mode file must contain "gate".
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>\.mode let a slug plan with no .mode
# drop a project-committed gate. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope $PlanDir already IS the
# project root, so the second source is skipped and behavior is unchanged.
$modeFile = Join-Path $PlanDir ".mode"
$rootForMode = if ($env:PWF_PLAN_ROOT) { $env:PWF_PLAN_ROOT } else { "." }
$rootModeFile = $null
if ($PlanDir -ne $rootForMode -and $PlanDir -ne ".") {
$rootModeFile = Join-Path $rootForMode ".mode"
}
$gatedMode = $false
if (Test-Path $modeFile) {
$modeContent = Get-Content $modeFile -Raw -ErrorAction SilentlyContinue
foreach ($candidateMode in @($modeFile, $rootModeFile)) {
if (-not $candidateMode) { continue }
if (-not (Test-Path $candidateMode)) { continue }
$modeContent = Get-Content $candidateMode -Raw -ErrorAction SilentlyContinue
if ($null -ne $modeContent -and $modeContent -match "gate") {
$gatedMode = $true
break
}
}
if (-not $gatedMode) {
@@ -60,6 +60,14 @@ else
if [ -n "${RESOLVED_DIR}" ] && [ -f "${RESOLVED_DIR}/task_plan.md" ]; then
PLAN_FILE="${RESOLVED_DIR}/task_plan.md"
PLAN_DIR="${RESOLVED_DIR}"
elif [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
# Explicit selectors are bindings, not hints (issue #237). The shared
# resolver rejected one, so the legacy cwd fallback below must not run:
# answering a mistyped pin with the ROOT plan's completion state is the
# same wrong-plan harm the binding removes, and here it would decide
# whether an autonomous run is allowed to stop.
echo "[planning-with-files] An explicit PLAN_ID or PWF_PLAN_ROOT did not resolve to a plan; no completion state was read and no other plan was substituted."
exit 0
else
PLAN_FILE="task_plan.md"
PLAN_DIR="."
@@ -131,10 +139,30 @@ fi
# ---- Gate path (--gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate". Absent or other
# Guard 1: gated mode. A .mode file must contain "gate". Absent or other
# content means advisory mode (legacy behavior preserved).
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>/.mode let a slug plan with no .mode
# drop a project-committed gate, the same way it dropped the attestation
# requirement in inject-plan.sh. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope PLAN_DIR already IS the
# project root, so the second source stays empty and behavior is unchanged.
MODE_FILE="${PLAN_DIR}/.mode"
if [ ! -f "${MODE_FILE}" ] || ! grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
ROOT_MODE_FILE=""
_root_for_mode="${PWF_PLAN_ROOT:-.}"
if [ "${PLAN_DIR}" != "${_root_for_mode}" ] && [ "${PLAN_DIR}" != "." ]; then
ROOT_MODE_FILE="${_root_for_mode}/.mode"
fi
GATED=0
if [ -f "${MODE_FILE}" ] && grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ] && [ -n "${ROOT_MODE_FILE}" ] && [ -f "${ROOT_MODE_FILE}" ] \
&& grep -q "gate" "${ROOT_MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ]; then
advisory_report
exit 0
fi
@@ -152,6 +152,33 @@ gen_nonce() {
# $1 = plan dir (absolute or relative); dotfiles live directly inside it.
# $2 = plan file path (task_plan.md) used for auto-attestation resolution.
# No-op when MODE is empty (legacy path stays byte-equivalent to v2.43.0).
# Raise MODE to the project's committed floor before the side effects run
# (issue #238). A project that ships a root .mode has made that setting a
# reviewed part of the repo; a new slug plan must not start below it. Without
# this, `init-session.sh <name>` created a plan with no .mode at all, and the
# project's attestation requirement became a flag the agent chose at plan
# creation time.
#
# inject-plan.sh enforces the same floor at read time, so this is not the
# guard. It exists so the effective policy is VISIBLE in the plan directory
# rather than only inside the resolver, and so the new plan gets the nonce and
# the auto-attestation that autonomous mode needs to inject at all.
#
# An explicit --autonomous/--gated is never lowered: gated stays gated.
inherit_root_mode() {
_root_mode="${PWD}/.mode"
[ -f "${_root_mode}" ] || return 0
[ "$MODE" = "gated" ] && return 0
if grep -q 'gate' "${_root_mode}" 2>/dev/null; then
MODE='gated'
return 0
fi
if grep -q 'autonomous' "${_root_mode}" 2>/dev/null; then
MODE='autonomous'
fi
return 0
}
apply_v3_mode() {
_mode_dir="$1"
_mode_plan="$2"
@@ -367,6 +394,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
@@ -74,27 +74,49 @@ if [ -f "${INJ}" ]; then
ok "injection: silent because no plan exists here (correct behavior)"
fi
else
# Classify on the DATA FRAMING first, never on substrings of the whole
# blob (issue #236). ${OUT} carries the plan body VERBATIM inside
# ===BEGIN-PWF-DATA=== fences, so a bare substring test also matches
# plan prose: a phase line reading "fix the false PLAN TAMPERED
# warning" made the doctor report a hash mismatch on a correctly
# attested plan.
#
# Every refusal path in inject-plan.sh prints its banner and exits
# before frame_file runs, so a frame in the output proves injection
# happened and rules out every refusal. Output WITHOUT a frame is by
# construction a notice, which is why the banner arms sit under the
# else side and the default arm warns instead of passing. A banner
# whose wording drifts then degrades to a generic warning rather than
# to a silent PASS: that is exactly how the stale
# "PWF_PLAN_ROOT is not a directory" literal (which was never a
# substring of what inject-plan.sh emits) reported PASS on a fully
# dark-hooks state.
case "${OUT}" in
*'PLAN TAMPERED'*)
*'===BEGIN-PWF-DATA'*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
;;
*'[PLAN TAMPERED'*)
warn "injection: plan is attested but the hash mismatches — run /plan-attest (or scripts/attest-plan.sh) to re-approve the current plan"
;;
*'requires attested plan'*)
warn "injection: v3 mode without attestation — run attest-plan once to arm injection"
;;
*'Session isolation is armed'*)
# Refusal notice, not plan context: reporting its byte count as
# PASS told a dark user their hooks were fine.
warn "injection: session isolation refuses this session — attach it with PWF_SESSION_ID=<id> plus .planning/sessions/<id>.attached, or delete the .planning/sessions/ dir (stale ones survive earlier Codex use and copied project trees) to turn isolation off"
;;
*'Ambiguous plan'*)
warn "injection: nested-plan ambiguity — a project directly below this cwd carries its own plan, so hooks refuse to guess. Pin the thread with PWF_PLAN_ROOT=<absolute project root> or PLAN_ID=<slug>"
;;
*'PWF_PLAN_ROOT is not a directory'*)
warn "injection: PWF_PLAN_ROOT points at a missing directory — fix or unset the pin; a broken pin fails closed and injects nothing"
*'PWF_PLAN_ROOT is not a supported absolute local directory'*)
warn "injection: PWF_PLAN_ROOT points at something that is not an absolute local directory — fix or unset the pin; a broken pin fails closed and injects nothing"
;;
*'PLAN_ID does not name a plan directory'*)
warn "injection: PLAN_ID names no plan directory under .planning — fix or unset the pin; a set PLAN_ID is a binding and fails closed rather than selecting another plan"
;;
*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
warn "injection: inject-plan.sh emitted ${BYTES} bytes but no ===BEGIN-PWF-DATA frame, so no plan context reached the model. This is a refusal notice this doctor does not recognize; read it directly with: sh scripts/inject-plan.sh --context=userprompt"
;;
esac
fi
@@ -130,6 +130,13 @@ function Test-WithinRoot {
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
# no directory, fails slug validation, or fails containment terminates
# resolution instead of falling through to .active_plan and newest-by-mtime:
# the fall-through let a one-character typo attest and inject a DIFFERENT plan
# at rc=0. Emptiness is the fail-closed signal on this channel, matching
# resolve-plan-dir.sh and the PWF_PLAN_ROOT pin. An empty $env:PLAN_ID is
# falsy here and still means "unset".
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
@@ -138,6 +145,7 @@ if ($env:PLAN_ID) {
exit 0
}
}
exit 0
}
# Get-Item observes the link object even when its target is missing, unlike
@@ -297,7 +297,34 @@ resolve_latest_dir() {
return 1
}
if resolve_from_env; then exit 0; fi
# A set PLAN_ID is a BINDING, not a hint (issue #237).
#
# resolve_from_env returns 1 both when no selector was set and when the
# selector was rejected, so continuing the chain after it turned a
# one-character typo into a silent switch: .active_plan or newest-by-mtime
# answered instead, attest-plan.sh locked THAT plan at rc=0, and injection
# followed the attestation onto it. commands/plan-attest.md already promised
# the opposite ("It never falls back to another plan").
#
# Any non-empty PLAN_ID therefore terminates resolution here, whether it was
# rejected for slug shape (traversal), for naming no directory, or for failing
# containment. The caller receives an empty result and takes its own
# fail-closed path rather than a different plan. PWF_PLAN_ROOT, the sibling
# selector, has failed closed on any bad value since #212; the two selectors
# now agree.
#
# An EMPTY PLAN_ID still means "unset": init-session.sh passes
# PLAN_ID="${PLAN_ID:-}" into attest-plan.sh on the legacy path and depends on
# that spelling resolving the root plan.
#
# Exit status stays 0 on the refusal (see the header contract). Emptiness is
# the fail-closed signal on this channel, exactly as the PWF_PLAN_ROOT guard
# above already does it; a non-zero status would kill callers running under
# set -e for a condition that is not an internal error.
if [ -n "${PLAN_ID:-}" ]; then
resolve_from_env && exit 0
exit 0
fi
if resolve_from_active_file; then exit 0; fi
if resolve_latest_dir; then exit 0; fi
exit 0
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.cursor/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.14.0"
version: "3.16.0"
---
@@ -108,7 +108,18 @@ case "${1:-}" in
esac
plan_file="$(resolve_plan_file)" || {
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
# Name the actual cause. "No task_plan.md found" is true but misleading
# when the plan exists and an explicit selector was rejected: before #237
# a mistyped PLAN_ID attested a DIFFERENT plan at rc=0, and an operator
# who now sees a generic not-found is likely to go looking for the wrong
# problem. The selectors are bindings, so say which one refused.
if [ -n "${PLAN_ID:-}" ]; then
printf "[plan-attest] PLAN_ID=%s names no plan directory under .planning. An explicit selector is a binding: nothing was attested and no other plan was substituted.\n" "${PLAN_ID}" >&2
elif [ -n "${PWF_PLAN_ROOT:-}" ]; then
printf "[plan-attest] PWF_PLAN_ROOT=%s did not resolve to a project root holding a plan. An explicit pin is a binding: nothing was attested and no other plan was substituted.\n" "${PWF_PLAN_ROOT}" >&2
else
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
fi
exit 1
}
@@ -107,13 +107,27 @@ if (-not $Gate) {
# ---- Gate path (-Gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate".
# Guard 1: gated mode. A .mode file must contain "gate".
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>\.mode let a slug plan with no .mode
# drop a project-committed gate. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope $PlanDir already IS the
# project root, so the second source is skipped and behavior is unchanged.
$modeFile = Join-Path $PlanDir ".mode"
$rootForMode = if ($env:PWF_PLAN_ROOT) { $env:PWF_PLAN_ROOT } else { "." }
$rootModeFile = $null
if ($PlanDir -ne $rootForMode -and $PlanDir -ne ".") {
$rootModeFile = Join-Path $rootForMode ".mode"
}
$gatedMode = $false
if (Test-Path $modeFile) {
$modeContent = Get-Content $modeFile -Raw -ErrorAction SilentlyContinue
foreach ($candidateMode in @($modeFile, $rootModeFile)) {
if (-not $candidateMode) { continue }
if (-not (Test-Path $candidateMode)) { continue }
$modeContent = Get-Content $candidateMode -Raw -ErrorAction SilentlyContinue
if ($null -ne $modeContent -and $modeContent -match "gate") {
$gatedMode = $true
break
}
}
if (-not $gatedMode) {
@@ -60,6 +60,14 @@ else
if [ -n "${RESOLVED_DIR}" ] && [ -f "${RESOLVED_DIR}/task_plan.md" ]; then
PLAN_FILE="${RESOLVED_DIR}/task_plan.md"
PLAN_DIR="${RESOLVED_DIR}"
elif [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
# Explicit selectors are bindings, not hints (issue #237). The shared
# resolver rejected one, so the legacy cwd fallback below must not run:
# answering a mistyped pin with the ROOT plan's completion state is the
# same wrong-plan harm the binding removes, and here it would decide
# whether an autonomous run is allowed to stop.
echo "[planning-with-files] An explicit PLAN_ID or PWF_PLAN_ROOT did not resolve to a plan; no completion state was read and no other plan was substituted."
exit 0
else
PLAN_FILE="task_plan.md"
PLAN_DIR="."
@@ -131,10 +139,30 @@ fi
# ---- Gate path (--gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate". Absent or other
# Guard 1: gated mode. A .mode file must contain "gate". Absent or other
# content means advisory mode (legacy behavior preserved).
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>/.mode let a slug plan with no .mode
# drop a project-committed gate, the same way it dropped the attestation
# requirement in inject-plan.sh. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope PLAN_DIR already IS the
# project root, so the second source stays empty and behavior is unchanged.
MODE_FILE="${PLAN_DIR}/.mode"
if [ ! -f "${MODE_FILE}" ] || ! grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
ROOT_MODE_FILE=""
_root_for_mode="${PWF_PLAN_ROOT:-.}"
if [ "${PLAN_DIR}" != "${_root_for_mode}" ] && [ "${PLAN_DIR}" != "." ]; then
ROOT_MODE_FILE="${_root_for_mode}/.mode"
fi
GATED=0
if [ -f "${MODE_FILE}" ] && grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ] && [ -n "${ROOT_MODE_FILE}" ] && [ -f "${ROOT_MODE_FILE}" ] \
&& grep -q "gate" "${ROOT_MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ]; then
advisory_report
exit 0
fi
@@ -152,6 +152,33 @@ gen_nonce() {
# $1 = plan dir (absolute or relative); dotfiles live directly inside it.
# $2 = plan file path (task_plan.md) used for auto-attestation resolution.
# No-op when MODE is empty (legacy path stays byte-equivalent to v2.43.0).
# Raise MODE to the project's committed floor before the side effects run
# (issue #238). A project that ships a root .mode has made that setting a
# reviewed part of the repo; a new slug plan must not start below it. Without
# this, `init-session.sh <name>` created a plan with no .mode at all, and the
# project's attestation requirement became a flag the agent chose at plan
# creation time.
#
# inject-plan.sh enforces the same floor at read time, so this is not the
# guard. It exists so the effective policy is VISIBLE in the plan directory
# rather than only inside the resolver, and so the new plan gets the nonce and
# the auto-attestation that autonomous mode needs to inject at all.
#
# An explicit --autonomous/--gated is never lowered: gated stays gated.
inherit_root_mode() {
_root_mode="${PWD}/.mode"
[ -f "${_root_mode}" ] || return 0
[ "$MODE" = "gated" ] && return 0
if grep -q 'gate' "${_root_mode}" 2>/dev/null; then
MODE='gated'
return 0
fi
if grep -q 'autonomous' "${_root_mode}" 2>/dev/null; then
MODE='autonomous'
fi
return 0
}
apply_v3_mode() {
_mode_dir="$1"
_mode_plan="$2"
@@ -367,6 +394,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
@@ -254,8 +254,28 @@ SCOPE=""
EXPLICIT=0
[ -n "$PLAN_PREFIX" ] && EXPLICIT=1
[ "$SESSION_ATTACHED" = "1" ] && EXPLICIT=1
if [ -n "${PLAN_ID:-}" ] && slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
if [ -n "${PLAN_ID:-}" ]; then
# A set PLAN_ID is a BINDING, not a hint (issue #237). This inline resolver
# is the one the hooks actually run, so it carries the same rule as
# resolve-plan-dir.sh: a selector that names no directory, fails slug
# validation, or fails containment refuses instead of falling through to
# .active_plan and newest-by-mtime. The fall-through is what let a
# one-character typo inject a DIFFERENT plan while attest-plan.sh locked
# that same wrong plan at rc=0.
#
# Unlike the PWF_PLAN_ROOT refusal above, the notice is userprompt-only.
# pretool fires per tool call and precompact carries no plan body, so
# 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
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
echo "[planning-with-files] PLAN_ID does not name a plan directory under .planning: ${PLAN_ID} — nothing injected. Fix or unset the pin; a broken pin fails closed rather than selecting another plan."
fi
exit 0
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
@@ -476,12 +496,16 @@ if [ "$SCOPE" = "root" ]; then
PROGRESS_FILE="${PLAN_PREFIX}progress.md"
ATTEST_FILE="${PLAN_PREFIX}.plan-attestation"
MODE_FILE="${PLAN_PREFIX}.mode"
ROOT_MODE_FILE=""
NONCE_FILE="${PLAN_PREFIX}.nonce"
else
PLAN_FILE="${RESOLVED}/task_plan.md"
PROGRESS_FILE="${RESOLVED}/progress.md"
ATTEST_FILE="${RESOLVED}/.attestation"
MODE_FILE="${RESOLVED}/.mode"
# The project's own .mode, when it has one (issue #238). In root scope
# MODE_FILE already IS that file, so the second source stays empty.
ROOT_MODE_FILE="${PLAN_PREFIX}.mode"
NONCE_FILE="${RESOLVED}/.nonce"
fi
[ -f "$PLAN_FILE" ] || exit 0
@@ -853,11 +877,52 @@ fi
# gated mode to legacy behavior (platform-critical: per-tool-call injection not
# suppressed, oracle re-hash skipped, raw progress tail injected). Use a grep
# token test, the same pattern check-complete.sh guard 1 uses.
# --- Root .mode is a FLOOR, not a default that slug scope replaces (#238). ---
# A project makes attestation mandatory by committing a root .mode, which is a
# reviewed project setting. Slug scope used to read ONLY the slug's .mode, and
# init-session.sh writes no .mode unless --autonomous or --gated was passed, so
# `init-session.sh <name>` produced a plan with no mode, no attestation
# requirement and full injection: one agent-invocable command turned the
# project's policy off.
#
# mode_has answers for a strictness-RAISING token: present in EITHER file. A
# slug may opt into autonomous/gated where the root left it unset; it can no
# longer opt out of what the root committed.
#
# mode_relax_allowed answers for the one strictness-LOWERING token
# (plan-guard-off): the slug must carry it AND, when the project committed a
# root .mode, that file must carry it too. A slug alone cannot switch off a
# protection the project kept on.
#
# With no root .mode present ROOT_MODE_FILE is either empty (root scope) or
# names a missing file, so the effective token set is exactly the slug's and
# existing projects are byte-identical.
mode_has() {
_mh_token="$1"
if [ -f "$MODE_FILE" ] && grep -q "$_mh_token" "$MODE_FILE" 2>/dev/null; then
return 0
fi
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ] \
&& grep -q "$_mh_token" "$ROOT_MODE_FILE" 2>/dev/null; then
return 0
fi
return 1
}
mode_relax_allowed() {
_mr_token="$1"
[ -f "$MODE_FILE" ] || return 1
grep -q "$_mr_token" "$MODE_FILE" 2>/dev/null || return 1
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ]; then
grep -q "$_mr_token" "$ROOT_MODE_FILE" 2>/dev/null || return 1
fi
return 0
}
MODE=""
if [ -f "$MODE_FILE" ]; then
grep -q 'autonomous' "$MODE_FILE" 2>/dev/null && MODE='autonomous'
grep -q 'gate' "$MODE_FILE" 2>/dev/null && MODE='gated'
fi
mode_has 'autonomous' && MODE='autonomous'
mode_has 'gate' && MODE='gated'
# In autonomous/gated mode the per-tool-call injection is dropped (recitation
# policy): strong models do not need the plan re-recited before every tool call,
@@ -881,7 +946,7 @@ fi
SMART=0
if [ "${PWF_INJECT:-}" = "smart" ]; then
SMART=1
elif [ -f "$MODE_FILE" ] && grep -q 'inject-smart' "$MODE_FILE" 2>/dev/null; then
elif mode_has 'inject-smart'; then
SMART=1
fi
@@ -1149,7 +1214,7 @@ esac
# holding the stale copy. Per-session keying needs PWF_SESSION_ID, which most
# hosts never set.
GUARD=1
[ -f "$MODE_FILE" ] && grep -q 'plan-guard-off' "$MODE_FILE" 2>/dev/null && GUARD=0
mode_relax_allowed 'plan-guard-off' && GUARD=0
[ "${PWF_PLAN_GUARD:-}" = "0" ] && GUARD=0
if [ "$GUARD" = "1" ]; then
# Same user-private cache root and same absolute-path key as the attestation
@@ -68,6 +68,15 @@ if [ -n "${ARG_DIR}" ]; then
elif [ -f "${RESOLVER}" ]; then
PLAN_DIR="$(sh "${RESOLVER}" 2>/dev/null)"
if [ -z "${PLAN_DIR}" ] || [ ! -d "${PLAN_DIR}" ]; then
# Explicit selectors are bindings, not hints (issue #237). A rejected
# PLAN_ID or PWF_PLAN_ROOT must not fall back to the cwd: this summary
# is injected into autonomous turns, so reporting the ROOT plan's
# phase counts under a mistyped pin feeds the loop another plan's
# termination signal. Degrade loudly, the same way a missing resolver
# already does.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
emit_unavailable "explicit PLAN_ID or PWF_PLAN_ROOT did not resolve"
fi
PLAN_DIR="."
fi
else
@@ -74,27 +74,49 @@ if [ -f "${INJ}" ]; then
ok "injection: silent because no plan exists here (correct behavior)"
fi
else
# Classify on the DATA FRAMING first, never on substrings of the whole
# blob (issue #236). ${OUT} carries the plan body VERBATIM inside
# ===BEGIN-PWF-DATA=== fences, so a bare substring test also matches
# plan prose: a phase line reading "fix the false PLAN TAMPERED
# warning" made the doctor report a hash mismatch on a correctly
# attested plan.
#
# Every refusal path in inject-plan.sh prints its banner and exits
# before frame_file runs, so a frame in the output proves injection
# happened and rules out every refusal. Output WITHOUT a frame is by
# construction a notice, which is why the banner arms sit under the
# else side and the default arm warns instead of passing. A banner
# whose wording drifts then degrades to a generic warning rather than
# to a silent PASS: that is exactly how the stale
# "PWF_PLAN_ROOT is not a directory" literal (which was never a
# substring of what inject-plan.sh emits) reported PASS on a fully
# dark-hooks state.
case "${OUT}" in
*'PLAN TAMPERED'*)
*'===BEGIN-PWF-DATA'*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
;;
*'[PLAN TAMPERED'*)
warn "injection: plan is attested but the hash mismatches — run /plan-attest (or scripts/attest-plan.sh) to re-approve the current plan"
;;
*'requires attested plan'*)
warn "injection: v3 mode without attestation — run attest-plan once to arm injection"
;;
*'Session isolation is armed'*)
# Refusal notice, not plan context: reporting its byte count as
# PASS told a dark user their hooks were fine.
warn "injection: session isolation refuses this session — attach it with PWF_SESSION_ID=<id> plus .planning/sessions/<id>.attached, or delete the .planning/sessions/ dir (stale ones survive earlier Codex use and copied project trees) to turn isolation off"
;;
*'Ambiguous plan'*)
warn "injection: nested-plan ambiguity — a project directly below this cwd carries its own plan, so hooks refuse to guess. Pin the thread with PWF_PLAN_ROOT=<absolute project root> or PLAN_ID=<slug>"
;;
*'PWF_PLAN_ROOT is not a directory'*)
warn "injection: PWF_PLAN_ROOT points at a missing directory — fix or unset the pin; a broken pin fails closed and injects nothing"
*'PWF_PLAN_ROOT is not a supported absolute local directory'*)
warn "injection: PWF_PLAN_ROOT points at something that is not an absolute local directory — fix or unset the pin; a broken pin fails closed and injects nothing"
;;
*'PLAN_ID does not name a plan directory'*)
warn "injection: PLAN_ID names no plan directory under .planning — fix or unset the pin; a set PLAN_ID is a binding and fails closed rather than selecting another plan"
;;
*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
warn "injection: inject-plan.sh emitted ${BYTES} bytes but no ===BEGIN-PWF-DATA frame, so no plan context reached the model. This is a refusal notice this doctor does not recognize; read it directly with: sh scripts/inject-plan.sh --context=userprompt"
;;
esac
fi
@@ -130,6 +130,13 @@ function Test-WithinRoot {
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
# no directory, fails slug validation, or fails containment terminates
# resolution instead of falling through to .active_plan and newest-by-mtime:
# the fall-through let a one-character typo attest and inject a DIFFERENT plan
# at rc=0. Emptiness is the fail-closed signal on this channel, matching
# resolve-plan-dir.sh and the PWF_PLAN_ROOT pin. An empty $env:PLAN_ID is
# falsy here and still means "unset".
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
@@ -138,6 +145,7 @@ if ($env:PLAN_ID) {
exit 0
}
}
exit 0
}
# Get-Item observes the link object even when its target is missing, unlike
@@ -297,7 +297,34 @@ resolve_latest_dir() {
return 1
}
if resolve_from_env; then exit 0; fi
# A set PLAN_ID is a BINDING, not a hint (issue #237).
#
# resolve_from_env returns 1 both when no selector was set and when the
# selector was rejected, so continuing the chain after it turned a
# one-character typo into a silent switch: .active_plan or newest-by-mtime
# answered instead, attest-plan.sh locked THAT plan at rc=0, and injection
# followed the attestation onto it. commands/plan-attest.md already promised
# the opposite ("It never falls back to another plan").
#
# Any non-empty PLAN_ID therefore terminates resolution here, whether it was
# rejected for slug shape (traversal), for naming no directory, or for failing
# containment. The caller receives an empty result and takes its own
# fail-closed path rather than a different plan. PWF_PLAN_ROOT, the sibling
# selector, has failed closed on any bad value since #212; the two selectors
# now agree.
#
# An EMPTY PLAN_ID still means "unset": init-session.sh passes
# PLAN_ID="${PLAN_ID:-}" into attest-plan.sh on the legacy path and depends on
# that spelling resolving the root plan.
#
# Exit status stays 0 on the refusal (see the header contract). Emptiness is
# the fail-closed signal on this channel, exactly as the PWF_PLAN_ROOT guard
# above already does it; a non-zero status would kill callers running under
# set -e for a condition that is not an internal error.
if [ -n "${PLAN_ID:-}" ]; then
resolve_from_env && exit 0
exit 0
fi
if resolve_from_active_file; then exit 0; fi
if resolve_latest_dir; then exit 0; fi
exit 0
+1 -1
View File
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.factory/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.14.0"
version: "3.16.0"
---
# Planning with Files
@@ -108,7 +108,18 @@ case "${1:-}" in
esac
plan_file="$(resolve_plan_file)" || {
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
# Name the actual cause. "No task_plan.md found" is true but misleading
# when the plan exists and an explicit selector was rejected: before #237
# a mistyped PLAN_ID attested a DIFFERENT plan at rc=0, and an operator
# who now sees a generic not-found is likely to go looking for the wrong
# problem. The selectors are bindings, so say which one refused.
if [ -n "${PLAN_ID:-}" ]; then
printf "[plan-attest] PLAN_ID=%s names no plan directory under .planning. An explicit selector is a binding: nothing was attested and no other plan was substituted.\n" "${PLAN_ID}" >&2
elif [ -n "${PWF_PLAN_ROOT:-}" ]; then
printf "[plan-attest] PWF_PLAN_ROOT=%s did not resolve to a project root holding a plan. An explicit pin is a binding: nothing was attested and no other plan was substituted.\n" "${PWF_PLAN_ROOT}" >&2
else
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
fi
exit 1
}
@@ -107,13 +107,27 @@ if (-not $Gate) {
# ---- Gate path (-Gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate".
# Guard 1: gated mode. A .mode file must contain "gate".
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>\.mode let a slug plan with no .mode
# drop a project-committed gate. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope $PlanDir already IS the
# project root, so the second source is skipped and behavior is unchanged.
$modeFile = Join-Path $PlanDir ".mode"
$rootForMode = if ($env:PWF_PLAN_ROOT) { $env:PWF_PLAN_ROOT } else { "." }
$rootModeFile = $null
if ($PlanDir -ne $rootForMode -and $PlanDir -ne ".") {
$rootModeFile = Join-Path $rootForMode ".mode"
}
$gatedMode = $false
if (Test-Path $modeFile) {
$modeContent = Get-Content $modeFile -Raw -ErrorAction SilentlyContinue
foreach ($candidateMode in @($modeFile, $rootModeFile)) {
if (-not $candidateMode) { continue }
if (-not (Test-Path $candidateMode)) { continue }
$modeContent = Get-Content $candidateMode -Raw -ErrorAction SilentlyContinue
if ($null -ne $modeContent -and $modeContent -match "gate") {
$gatedMode = $true
break
}
}
if (-not $gatedMode) {
@@ -60,6 +60,14 @@ else
if [ -n "${RESOLVED_DIR}" ] && [ -f "${RESOLVED_DIR}/task_plan.md" ]; then
PLAN_FILE="${RESOLVED_DIR}/task_plan.md"
PLAN_DIR="${RESOLVED_DIR}"
elif [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
# Explicit selectors are bindings, not hints (issue #237). The shared
# resolver rejected one, so the legacy cwd fallback below must not run:
# answering a mistyped pin with the ROOT plan's completion state is the
# same wrong-plan harm the binding removes, and here it would decide
# whether an autonomous run is allowed to stop.
echo "[planning-with-files] An explicit PLAN_ID or PWF_PLAN_ROOT did not resolve to a plan; no completion state was read and no other plan was substituted."
exit 0
else
PLAN_FILE="task_plan.md"
PLAN_DIR="."
@@ -131,10 +139,30 @@ fi
# ---- Gate path (--gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate". Absent or other
# Guard 1: gated mode. A .mode file must contain "gate". Absent or other
# content means advisory mode (legacy behavior preserved).
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>/.mode let a slug plan with no .mode
# drop a project-committed gate, the same way it dropped the attestation
# requirement in inject-plan.sh. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope PLAN_DIR already IS the
# project root, so the second source stays empty and behavior is unchanged.
MODE_FILE="${PLAN_DIR}/.mode"
if [ ! -f "${MODE_FILE}" ] || ! grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
ROOT_MODE_FILE=""
_root_for_mode="${PWF_PLAN_ROOT:-.}"
if [ "${PLAN_DIR}" != "${_root_for_mode}" ] && [ "${PLAN_DIR}" != "." ]; then
ROOT_MODE_FILE="${_root_for_mode}/.mode"
fi
GATED=0
if [ -f "${MODE_FILE}" ] && grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ] && [ -n "${ROOT_MODE_FILE}" ] && [ -f "${ROOT_MODE_FILE}" ] \
&& grep -q "gate" "${ROOT_MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ]; then
advisory_report
exit 0
fi
@@ -152,6 +152,33 @@ gen_nonce() {
# $1 = plan dir (absolute or relative); dotfiles live directly inside it.
# $2 = plan file path (task_plan.md) used for auto-attestation resolution.
# No-op when MODE is empty (legacy path stays byte-equivalent to v2.43.0).
# Raise MODE to the project's committed floor before the side effects run
# (issue #238). A project that ships a root .mode has made that setting a
# reviewed part of the repo; a new slug plan must not start below it. Without
# this, `init-session.sh <name>` created a plan with no .mode at all, and the
# project's attestation requirement became a flag the agent chose at plan
# creation time.
#
# inject-plan.sh enforces the same floor at read time, so this is not the
# guard. It exists so the effective policy is VISIBLE in the plan directory
# rather than only inside the resolver, and so the new plan gets the nonce and
# the auto-attestation that autonomous mode needs to inject at all.
#
# An explicit --autonomous/--gated is never lowered: gated stays gated.
inherit_root_mode() {
_root_mode="${PWD}/.mode"
[ -f "${_root_mode}" ] || return 0
[ "$MODE" = "gated" ] && return 0
if grep -q 'gate' "${_root_mode}" 2>/dev/null; then
MODE='gated'
return 0
fi
if grep -q 'autonomous' "${_root_mode}" 2>/dev/null; then
MODE='autonomous'
fi
return 0
}
apply_v3_mode() {
_mode_dir="$1"
_mode_plan="$2"
@@ -367,6 +394,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
@@ -254,8 +254,28 @@ SCOPE=""
EXPLICIT=0
[ -n "$PLAN_PREFIX" ] && EXPLICIT=1
[ "$SESSION_ATTACHED" = "1" ] && EXPLICIT=1
if [ -n "${PLAN_ID:-}" ] && slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
if [ -n "${PLAN_ID:-}" ]; then
# A set PLAN_ID is a BINDING, not a hint (issue #237). This inline resolver
# is the one the hooks actually run, so it carries the same rule as
# resolve-plan-dir.sh: a selector that names no directory, fails slug
# validation, or fails containment refuses instead of falling through to
# .active_plan and newest-by-mtime. The fall-through is what let a
# one-character typo inject a DIFFERENT plan while attest-plan.sh locked
# that same wrong plan at rc=0.
#
# Unlike the PWF_PLAN_ROOT refusal above, the notice is userprompt-only.
# pretool fires per tool call and precompact carries no plan body, so
# 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
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
echo "[planning-with-files] PLAN_ID does not name a plan directory under .planning: ${PLAN_ID} — nothing injected. Fix or unset the pin; a broken pin fails closed rather than selecting another plan."
fi
exit 0
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
@@ -476,12 +496,16 @@ if [ "$SCOPE" = "root" ]; then
PROGRESS_FILE="${PLAN_PREFIX}progress.md"
ATTEST_FILE="${PLAN_PREFIX}.plan-attestation"
MODE_FILE="${PLAN_PREFIX}.mode"
ROOT_MODE_FILE=""
NONCE_FILE="${PLAN_PREFIX}.nonce"
else
PLAN_FILE="${RESOLVED}/task_plan.md"
PROGRESS_FILE="${RESOLVED}/progress.md"
ATTEST_FILE="${RESOLVED}/.attestation"
MODE_FILE="${RESOLVED}/.mode"
# The project's own .mode, when it has one (issue #238). In root scope
# MODE_FILE already IS that file, so the second source stays empty.
ROOT_MODE_FILE="${PLAN_PREFIX}.mode"
NONCE_FILE="${RESOLVED}/.nonce"
fi
[ -f "$PLAN_FILE" ] || exit 0
@@ -853,11 +877,52 @@ fi
# gated mode to legacy behavior (platform-critical: per-tool-call injection not
# suppressed, oracle re-hash skipped, raw progress tail injected). Use a grep
# token test, the same pattern check-complete.sh guard 1 uses.
# --- Root .mode is a FLOOR, not a default that slug scope replaces (#238). ---
# A project makes attestation mandatory by committing a root .mode, which is a
# reviewed project setting. Slug scope used to read ONLY the slug's .mode, and
# init-session.sh writes no .mode unless --autonomous or --gated was passed, so
# `init-session.sh <name>` produced a plan with no mode, no attestation
# requirement and full injection: one agent-invocable command turned the
# project's policy off.
#
# mode_has answers for a strictness-RAISING token: present in EITHER file. A
# slug may opt into autonomous/gated where the root left it unset; it can no
# longer opt out of what the root committed.
#
# mode_relax_allowed answers for the one strictness-LOWERING token
# (plan-guard-off): the slug must carry it AND, when the project committed a
# root .mode, that file must carry it too. A slug alone cannot switch off a
# protection the project kept on.
#
# With no root .mode present ROOT_MODE_FILE is either empty (root scope) or
# names a missing file, so the effective token set is exactly the slug's and
# existing projects are byte-identical.
mode_has() {
_mh_token="$1"
if [ -f "$MODE_FILE" ] && grep -q "$_mh_token" "$MODE_FILE" 2>/dev/null; then
return 0
fi
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ] \
&& grep -q "$_mh_token" "$ROOT_MODE_FILE" 2>/dev/null; then
return 0
fi
return 1
}
mode_relax_allowed() {
_mr_token="$1"
[ -f "$MODE_FILE" ] || return 1
grep -q "$_mr_token" "$MODE_FILE" 2>/dev/null || return 1
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ]; then
grep -q "$_mr_token" "$ROOT_MODE_FILE" 2>/dev/null || return 1
fi
return 0
}
MODE=""
if [ -f "$MODE_FILE" ]; then
grep -q 'autonomous' "$MODE_FILE" 2>/dev/null && MODE='autonomous'
grep -q 'gate' "$MODE_FILE" 2>/dev/null && MODE='gated'
fi
mode_has 'autonomous' && MODE='autonomous'
mode_has 'gate' && MODE='gated'
# In autonomous/gated mode the per-tool-call injection is dropped (recitation
# policy): strong models do not need the plan re-recited before every tool call,
@@ -881,7 +946,7 @@ fi
SMART=0
if [ "${PWF_INJECT:-}" = "smart" ]; then
SMART=1
elif [ -f "$MODE_FILE" ] && grep -q 'inject-smart' "$MODE_FILE" 2>/dev/null; then
elif mode_has 'inject-smart'; then
SMART=1
fi
@@ -1149,7 +1214,7 @@ esac
# holding the stale copy. Per-session keying needs PWF_SESSION_ID, which most
# hosts never set.
GUARD=1
[ -f "$MODE_FILE" ] && grep -q 'plan-guard-off' "$MODE_FILE" 2>/dev/null && GUARD=0
mode_relax_allowed 'plan-guard-off' && GUARD=0
[ "${PWF_PLAN_GUARD:-}" = "0" ] && GUARD=0
if [ "$GUARD" = "1" ]; then
# Same user-private cache root and same absolute-path key as the attestation
@@ -68,6 +68,15 @@ if [ -n "${ARG_DIR}" ]; then
elif [ -f "${RESOLVER}" ]; then
PLAN_DIR="$(sh "${RESOLVER}" 2>/dev/null)"
if [ -z "${PLAN_DIR}" ] || [ ! -d "${PLAN_DIR}" ]; then
# Explicit selectors are bindings, not hints (issue #237). A rejected
# PLAN_ID or PWF_PLAN_ROOT must not fall back to the cwd: this summary
# is injected into autonomous turns, so reporting the ROOT plan's
# phase counts under a mistyped pin feeds the loop another plan's
# termination signal. Degrade loudly, the same way a missing resolver
# already does.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
emit_unavailable "explicit PLAN_ID or PWF_PLAN_ROOT did not resolve"
fi
PLAN_DIR="."
fi
else
@@ -74,27 +74,49 @@ if [ -f "${INJ}" ]; then
ok "injection: silent because no plan exists here (correct behavior)"
fi
else
# Classify on the DATA FRAMING first, never on substrings of the whole
# blob (issue #236). ${OUT} carries the plan body VERBATIM inside
# ===BEGIN-PWF-DATA=== fences, so a bare substring test also matches
# plan prose: a phase line reading "fix the false PLAN TAMPERED
# warning" made the doctor report a hash mismatch on a correctly
# attested plan.
#
# Every refusal path in inject-plan.sh prints its banner and exits
# before frame_file runs, so a frame in the output proves injection
# happened and rules out every refusal. Output WITHOUT a frame is by
# construction a notice, which is why the banner arms sit under the
# else side and the default arm warns instead of passing. A banner
# whose wording drifts then degrades to a generic warning rather than
# to a silent PASS: that is exactly how the stale
# "PWF_PLAN_ROOT is not a directory" literal (which was never a
# substring of what inject-plan.sh emits) reported PASS on a fully
# dark-hooks state.
case "${OUT}" in
*'PLAN TAMPERED'*)
*'===BEGIN-PWF-DATA'*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
;;
*'[PLAN TAMPERED'*)
warn "injection: plan is attested but the hash mismatches — run /plan-attest (or scripts/attest-plan.sh) to re-approve the current plan"
;;
*'requires attested plan'*)
warn "injection: v3 mode without attestation — run attest-plan once to arm injection"
;;
*'Session isolation is armed'*)
# Refusal notice, not plan context: reporting its byte count as
# PASS told a dark user their hooks were fine.
warn "injection: session isolation refuses this session — attach it with PWF_SESSION_ID=<id> plus .planning/sessions/<id>.attached, or delete the .planning/sessions/ dir (stale ones survive earlier Codex use and copied project trees) to turn isolation off"
;;
*'Ambiguous plan'*)
warn "injection: nested-plan ambiguity — a project directly below this cwd carries its own plan, so hooks refuse to guess. Pin the thread with PWF_PLAN_ROOT=<absolute project root> or PLAN_ID=<slug>"
;;
*'PWF_PLAN_ROOT is not a directory'*)
warn "injection: PWF_PLAN_ROOT points at a missing directory — fix or unset the pin; a broken pin fails closed and injects nothing"
*'PWF_PLAN_ROOT is not a supported absolute local directory'*)
warn "injection: PWF_PLAN_ROOT points at something that is not an absolute local directory — fix or unset the pin; a broken pin fails closed and injects nothing"
;;
*'PLAN_ID does not name a plan directory'*)
warn "injection: PLAN_ID names no plan directory under .planning — fix or unset the pin; a set PLAN_ID is a binding and fails closed rather than selecting another plan"
;;
*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
warn "injection: inject-plan.sh emitted ${BYTES} bytes but no ===BEGIN-PWF-DATA frame, so no plan context reached the model. This is a refusal notice this doctor does not recognize; read it directly with: sh scripts/inject-plan.sh --context=userprompt"
;;
esac
fi
@@ -130,6 +130,13 @@ function Test-WithinRoot {
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
# no directory, fails slug validation, or fails containment terminates
# resolution instead of falling through to .active_plan and newest-by-mtime:
# the fall-through let a one-character typo attest and inject a DIFFERENT plan
# at rc=0. Emptiness is the fail-closed signal on this channel, matching
# resolve-plan-dir.sh and the PWF_PLAN_ROOT pin. An empty $env:PLAN_ID is
# falsy here and still means "unset".
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
@@ -138,6 +145,7 @@ if ($env:PLAN_ID) {
exit 0
}
}
exit 0
}
# Get-Item observes the link object even when its target is missing, unlike
@@ -297,7 +297,34 @@ resolve_latest_dir() {
return 1
}
if resolve_from_env; then exit 0; fi
# A set PLAN_ID is a BINDING, not a hint (issue #237).
#
# resolve_from_env returns 1 both when no selector was set and when the
# selector was rejected, so continuing the chain after it turned a
# one-character typo into a silent switch: .active_plan or newest-by-mtime
# answered instead, attest-plan.sh locked THAT plan at rc=0, and injection
# followed the attestation onto it. commands/plan-attest.md already promised
# the opposite ("It never falls back to another plan").
#
# Any non-empty PLAN_ID therefore terminates resolution here, whether it was
# rejected for slug shape (traversal), for naming no directory, or for failing
# containment. The caller receives an empty result and takes its own
# fail-closed path rather than a different plan. PWF_PLAN_ROOT, the sibling
# selector, has failed closed on any bad value since #212; the two selectors
# now agree.
#
# An EMPTY PLAN_ID still means "unset": init-session.sh passes
# PLAN_ID="${PLAN_ID:-}" into attest-plan.sh on the legacy path and depends on
# that spelling resolving the root plan.
#
# Exit status stays 0 on the refusal (see the header contract). Emptiness is
# the fail-closed signal on this channel, exactly as the PWF_PLAN_ROOT guard
# above already does it; a non-zero status would kill callers running under
# set -e for a condition that is not an internal error.
if [ -n "${PLAN_ID:-}" ]; then
resolve_from_env && exit 0
exit 0
fi
if resolve_from_active_file; then exit 0; fi
if resolve_latest_dir; then exit 0; fi
exit 0
+1 -1
View File
@@ -182,7 +182,7 @@ Helper scripts for automation:
- `scripts/init-session.sh` — Initialize planning files. With a name arg, creates an isolated plan under `.planning/YYYY-MM-DD-<slug>/` for parallel task workflows. Without args, writes `task_plan.md` at project root (legacy mode, backward-compatible).
- `scripts/set-active-plan.sh` — Switch the active plan pointer (`.planning/.active_plan`). Run with a plan ID to switch; run without args to show which plan is current.
- `scripts/resolve-plan-dir.sh` — Resolve the active plan directory. Checks `$PLAN_ID` env var first, then `.planning/.active_plan`, then newest plan dir by mtime, then falls back to project root (legacy). Used internally by hooks.
- `scripts/resolve-plan-dir.sh` — Resolve the active plan directory. A set `$PLAN_ID` is a binding: it resolves or resolution stops, never another plan (issue #237). With no `$PLAN_ID`, checks `.planning/.active_plan`, then newest plan dir by mtime, then falls back to project root (legacy). Used internally by hooks.
- `scripts/check-complete.sh` — Verify all phases in the active plan are complete.
- `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history. OpenCode uses its read-only SQLite store.
- `scripts/attest-plan.sh` (and `.ps1`) — Lock the current `task_plan.md` content with a SHA-256 attestation (v2.37.0). Use `--show` to print the stored hash, `--clear` to remove the attestation.
@@ -108,7 +108,18 @@ case "${1:-}" in
esac
plan_file="$(resolve_plan_file)" || {
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
# Name the actual cause. "No task_plan.md found" is true but misleading
# when the plan exists and an explicit selector was rejected: before #237
# a mistyped PLAN_ID attested a DIFFERENT plan at rc=0, and an operator
# who now sees a generic not-found is likely to go looking for the wrong
# problem. The selectors are bindings, so say which one refused.
if [ -n "${PLAN_ID:-}" ]; then
printf "[plan-attest] PLAN_ID=%s names no plan directory under .planning. An explicit selector is a binding: nothing was attested and no other plan was substituted.\n" "${PLAN_ID}" >&2
elif [ -n "${PWF_PLAN_ROOT:-}" ]; then
printf "[plan-attest] PWF_PLAN_ROOT=%s did not resolve to a project root holding a plan. An explicit pin is a binding: nothing was attested and no other plan was substituted.\n" "${PWF_PLAN_ROOT}" >&2
else
printf "[plan-attest] No task_plan.md found. Create a plan first.\n" >&2
fi
exit 1
}
@@ -107,13 +107,27 @@ if (-not $Gate) {
# ---- Gate path (-Gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate".
# Guard 1: gated mode. A .mode file must contain "gate".
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>\.mode let a slug plan with no .mode
# drop a project-committed gate. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope $PlanDir already IS the
# project root, so the second source is skipped and behavior is unchanged.
$modeFile = Join-Path $PlanDir ".mode"
$rootForMode = if ($env:PWF_PLAN_ROOT) { $env:PWF_PLAN_ROOT } else { "." }
$rootModeFile = $null
if ($PlanDir -ne $rootForMode -and $PlanDir -ne ".") {
$rootModeFile = Join-Path $rootForMode ".mode"
}
$gatedMode = $false
if (Test-Path $modeFile) {
$modeContent = Get-Content $modeFile -Raw -ErrorAction SilentlyContinue
foreach ($candidateMode in @($modeFile, $rootModeFile)) {
if (-not $candidateMode) { continue }
if (-not (Test-Path $candidateMode)) { continue }
$modeContent = Get-Content $candidateMode -Raw -ErrorAction SilentlyContinue
if ($null -ne $modeContent -and $modeContent -match "gate") {
$gatedMode = $true
break
}
}
if (-not $gatedMode) {
@@ -60,6 +60,14 @@ else
if [ -n "${RESOLVED_DIR}" ] && [ -f "${RESOLVED_DIR}/task_plan.md" ]; then
PLAN_FILE="${RESOLVED_DIR}/task_plan.md"
PLAN_DIR="${RESOLVED_DIR}"
elif [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
# Explicit selectors are bindings, not hints (issue #237). The shared
# resolver rejected one, so the legacy cwd fallback below must not run:
# answering a mistyped pin with the ROOT plan's completion state is the
# same wrong-plan harm the binding removes, and here it would decide
# whether an autonomous run is allowed to stop.
echo "[planning-with-files] An explicit PLAN_ID or PWF_PLAN_ROOT did not resolve to a plan; no completion state was read and no other plan was substituted."
exit 0
else
PLAN_FILE="task_plan.md"
PLAN_DIR="."
@@ -131,10 +139,30 @@ fi
# ---- Gate path (--gate). Resolves to advisory unless every guard says block. ----
# Guard 1: gated mode. The .mode file must contain "gate". Absent or other
# Guard 1: gated mode. A .mode file must contain "gate". Absent or other
# content means advisory mode (legacy behavior preserved).
#
# The project's root .mode is a FLOOR, not a default that slug scope replaces
# (issue #238). Reading only <plan-dir>/.mode let a slug plan with no .mode
# drop a project-committed gate, the same way it dropped the attestation
# requirement in inject-plan.sh. "gate" from EITHER file arms the gate; a slug
# may raise strictness, never lower it. In root scope PLAN_DIR already IS the
# project root, so the second source stays empty and behavior is unchanged.
MODE_FILE="${PLAN_DIR}/.mode"
if [ ! -f "${MODE_FILE}" ] || ! grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
ROOT_MODE_FILE=""
_root_for_mode="${PWF_PLAN_ROOT:-.}"
if [ "${PLAN_DIR}" != "${_root_for_mode}" ] && [ "${PLAN_DIR}" != "." ]; then
ROOT_MODE_FILE="${_root_for_mode}/.mode"
fi
GATED=0
if [ -f "${MODE_FILE}" ] && grep -q "gate" "${MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ] && [ -n "${ROOT_MODE_FILE}" ] && [ -f "${ROOT_MODE_FILE}" ] \
&& grep -q "gate" "${ROOT_MODE_FILE}" 2>/dev/null; then
GATED=1
fi
if [ "${GATED}" -eq 0 ]; then
advisory_report
exit 0
fi
@@ -152,6 +152,33 @@ gen_nonce() {
# $1 = plan dir (absolute or relative); dotfiles live directly inside it.
# $2 = plan file path (task_plan.md) used for auto-attestation resolution.
# No-op when MODE is empty (legacy path stays byte-equivalent to v2.43.0).
# Raise MODE to the project's committed floor before the side effects run
# (issue #238). A project that ships a root .mode has made that setting a
# reviewed part of the repo; a new slug plan must not start below it. Without
# this, `init-session.sh <name>` created a plan with no .mode at all, and the
# project's attestation requirement became a flag the agent chose at plan
# creation time.
#
# inject-plan.sh enforces the same floor at read time, so this is not the
# guard. It exists so the effective policy is VISIBLE in the plan directory
# rather than only inside the resolver, and so the new plan gets the nonce and
# the auto-attestation that autonomous mode needs to inject at all.
#
# An explicit --autonomous/--gated is never lowered: gated stays gated.
inherit_root_mode() {
_root_mode="${PWD}/.mode"
[ -f "${_root_mode}" ] || return 0
[ "$MODE" = "gated" ] && return 0
if grep -q 'gate' "${_root_mode}" 2>/dev/null; then
MODE='gated'
return 0
fi
if grep -q 'autonomous' "${_root_mode}" 2>/dev/null; then
MODE='autonomous'
fi
return 0
}
apply_v3_mode() {
_mode_dir="$1"
_mode_plan="$2"
@@ -367,6 +394,7 @@ if [ "$SLUG_MODE" -eq 1 ]; then
echo "PLAN_ID=$PLAN_ID"
create_files_in "$PLAN_DIR"
printf "%s\n" "$PLAN_ID" > "${PLAN_ROOT}/.active_plan"
inherit_root_mode
apply_v3_mode "$PLAN_DIR" "${PLAN_DIR}/task_plan.md"
echo ""
echo "Active plan recorded: ${PLAN_ROOT}/.active_plan"
@@ -74,27 +74,49 @@ if [ -f "${INJ}" ]; then
ok "injection: silent because no plan exists here (correct behavior)"
fi
else
# Classify on the DATA FRAMING first, never on substrings of the whole
# blob (issue #236). ${OUT} carries the plan body VERBATIM inside
# ===BEGIN-PWF-DATA=== fences, so a bare substring test also matches
# plan prose: a phase line reading "fix the false PLAN TAMPERED
# warning" made the doctor report a hash mismatch on a correctly
# attested plan.
#
# Every refusal path in inject-plan.sh prints its banner and exits
# before frame_file runs, so a frame in the output proves injection
# happened and rules out every refusal. Output WITHOUT a frame is by
# construction a notice, which is why the banner arms sit under the
# else side and the default arm warns instead of passing. A banner
# whose wording drifts then degrades to a generic warning rather than
# to a silent PASS: that is exactly how the stale
# "PWF_PLAN_ROOT is not a directory" literal (which was never a
# substring of what inject-plan.sh emits) reported PASS on a fully
# dark-hooks state.
case "${OUT}" in
*'PLAN TAMPERED'*)
*'===BEGIN-PWF-DATA'*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
;;
*'[PLAN TAMPERED'*)
warn "injection: plan is attested but the hash mismatches — run /plan-attest (or scripts/attest-plan.sh) to re-approve the current plan"
;;
*'requires attested plan'*)
warn "injection: v3 mode without attestation — run attest-plan once to arm injection"
;;
*'Session isolation is armed'*)
# Refusal notice, not plan context: reporting its byte count as
# PASS told a dark user their hooks were fine.
warn "injection: session isolation refuses this session — attach it with PWF_SESSION_ID=<id> plus .planning/sessions/<id>.attached, or delete the .planning/sessions/ dir (stale ones survive earlier Codex use and copied project trees) to turn isolation off"
;;
*'Ambiguous plan'*)
warn "injection: nested-plan ambiguity — a project directly below this cwd carries its own plan, so hooks refuse to guess. Pin the thread with PWF_PLAN_ROOT=<absolute project root> or PLAN_ID=<slug>"
;;
*'PWF_PLAN_ROOT is not a directory'*)
warn "injection: PWF_PLAN_ROOT points at a missing directory — fix or unset the pin; a broken pin fails closed and injects nothing"
*'PWF_PLAN_ROOT is not a supported absolute local directory'*)
warn "injection: PWF_PLAN_ROOT points at something that is not an absolute local directory — fix or unset the pin; a broken pin fails closed and injects nothing"
;;
*'PLAN_ID does not name a plan directory'*)
warn "injection: PLAN_ID names no plan directory under .planning — fix or unset the pin; a set PLAN_ID is a binding and fails closed rather than selecting another plan"
;;
*)
BYTES="$(printf '%s' "${OUT}" | wc -c | tr -d '[:space:]')"
ok "injection: emits plan context (${BYTES} bytes)"
warn "injection: inject-plan.sh emitted ${BYTES} bytes but no ===BEGIN-PWF-DATA frame, so no plan context reached the model. This is a refusal notice this doctor does not recognize; read it directly with: sh scripts/inject-plan.sh --context=userprompt"
;;
esac
fi
@@ -130,6 +130,13 @@ function Test-WithinRoot {
$activeFile = Join-Path $PlanRoot ".active_plan"
# A set PLAN_ID is a BINDING, not a hint (issue #237). A selector that names
# no directory, fails slug validation, or fails containment terminates
# resolution instead of falling through to .active_plan and newest-by-mtime:
# the fall-through let a one-character typo attest and inject a DIFFERENT plan
# at rc=0. Emptiness is the fail-closed signal on this channel, matching
# resolve-plan-dir.sh and the PWF_PLAN_ROOT pin. An empty $env:PLAN_ID is
# falsy here and still means "unset".
if ($env:PLAN_ID) {
if (Test-ValidSlug $env:PLAN_ID) {
$candidate = Join-Path $PlanRoot $env:PLAN_ID
@@ -138,6 +145,7 @@ if ($env:PLAN_ID) {
exit 0
}
}
exit 0
}
# Get-Item observes the link object even when its target is missing, unlike
@@ -297,7 +297,34 @@ resolve_latest_dir() {
return 1
}
if resolve_from_env; then exit 0; fi
# A set PLAN_ID is a BINDING, not a hint (issue #237).
#
# resolve_from_env returns 1 both when no selector was set and when the
# selector was rejected, so continuing the chain after it turned a
# one-character typo into a silent switch: .active_plan or newest-by-mtime
# answered instead, attest-plan.sh locked THAT plan at rc=0, and injection
# followed the attestation onto it. commands/plan-attest.md already promised
# the opposite ("It never falls back to another plan").
#
# Any non-empty PLAN_ID therefore terminates resolution here, whether it was
# rejected for slug shape (traversal), for naming no directory, or for failing
# containment. The caller receives an empty result and takes its own
# fail-closed path rather than a different plan. PWF_PLAN_ROOT, the sibling
# selector, has failed closed on any bad value since #212; the two selectors
# now agree.
#
# An EMPTY PLAN_ID still means "unset": init-session.sh passes
# PLAN_ID="${PLAN_ID:-}" into attest-plan.sh on the legacy path and depends on
# that spelling resolving the root plan.
#
# Exit status stays 0 on the refusal (see the header contract). Emptiness is
# the fail-closed signal on this channel, exactly as the PWF_PLAN_ROOT guard
# above already does it; a non-zero status would kill callers running under
# set -e for a condition that is not an internal error.
if [ -n "${PLAN_ID:-}" ]; then
resolve_from_env && exit 0
exit 0
fi
if resolve_from_active_file; then exit 0; fi
if resolve_latest_dir; then exit 0; fi
exit 0
+1 -1
View File
@@ -217,7 +217,7 @@ def pre_verify(**kwargs: Any) -> dict[str, str] | None:
if project_dir is None or plan_dir is None:
return None
try:
reason = evaluate_gate(plan_dir)
reason = evaluate_gate(project_dir, plan_dir)
except (OSError, RuntimeError, ValueError):
return None
if not reason:
+16 -3
View File
@@ -251,12 +251,25 @@ def resolve_plan(
planning_root = project_dir / ".planning"
requested = plan_id if plan_id is not None else os.environ.get("PLAN_ID", "").strip()
if requested:
# An explicit slug that resolves is authoritative and skips the nested
# check. One that does not resolve falls through to the pointer, the
# newest slug and the legacy root, exactly like resolve-plan-dir.sh.
# A set PLAN_ID is a BINDING, not a hint (issue #237).
#
# A slug that resolves is authoritative and skips the nested check. One
# that does NOT resolve ends resolution right here. Falling through to
# the pointer, the newest slug and the legacy root turned a
# one-character typo into a silent switch: the operator asked for plan
# A, .active_plan or newest-by-mtime answered with plan B, and B was
# what got attested and injected at rc=0. Every rejection route ends the
# same way, whether the selector failed slug validation (traversal
# shapes included), named no directory, or failed containment. The
# caller receives "no plan" and takes its own fail-closed path rather
# than a plan nobody selected.
#
# An EMPTY PLAN_ID still means "no selector": resolution continues below
# exactly as before, which is what the legacy root path depends on.
explicit_dir = _slug_plan_dir(planning_root, requested)
if explicit_dir is not None:
return explicit_dir, []
return None, []
chosen: Path | None = None
if planning_root.is_dir() and not _is_link_or_reparse(planning_root):
@@ -291,15 +291,59 @@ def gate_counts(task_plan: str) -> dict[str, int]:
return counts
def mode_tokens(plan_dir: Path) -> list[str]:
"""Tokens of <plan-dir>/.mode; empty when absent or unreadable."""
# The strictness-LOWERING mode tokens. Everything else raises strictness, and
# the root .mode floor (issue #238) treats the two halves in opposite
# directions, so a new token must be classified here deliberately.
_LOWERING_MODE_TOKENS = frozenset({"plan-guard-off"})
def _read_mode_file(directory: Path) -> list[str]:
"""Tokens of one directory's .mode; empty when absent or unreadable."""
try:
raw = (plan_dir / ".mode").read_text(encoding="ascii", errors="strict")
raw = (directory / ".mode").read_text(encoding="ascii", errors="strict")
except (OSError, UnicodeError):
return []
return raw.split()
def mode_tokens(project_dir: Path, plan_dir: Path) -> list[str]:
"""Effective mode: the slug's .mode raised by the project root .mode FLOOR.
A project makes attestation mandatory by committing a root .mode, which is
a reviewed project setting. Reading only <plan-dir>/.mode let a slug plan
silently exempt itself (issue #238): init_plan writes no .mode unless the
operator asked for a mode, so creating a plan turned the project policy off
in one agent-invocable call.
Strictness-RAISING tokens (autonomous, gate, inject-smart) count when
EITHER file carries them: a slug may go stricter than the project asked, it
can never go looser. The strictness-LOWERING token (plan-guard-off) survives
only when the slug carries it AND, where a root .mode exists, that file
carries it too, so a slug cannot switch off a protection the project kept
on.
With no root .mode the result is exactly the slug's tokens, in the slug's
own order, which is the invariant existing projects depend on. Root scope
has no second source at all: <root>/.mode already IS the plan's .mode
there.
"""
slug = _read_mode_file(plan_dir)
if plan_dir == project_dir:
return slug
# Presence of the file is what makes the root a policy statement, not the
# tokens in it. A committed but empty root .mode still says "this project
# reviewed its mode and asked for no relaxations", so a slug's
# plan-guard-off does not survive it. Testing `not floor` instead would
# treat an empty file like a missing one and diverge from inject-plan.sh,
# which checks `[ -f "$ROOT_MODE_FILE" ]`.
if not (project_dir / ".mode").is_file():
return slug
floor = _read_mode_file(project_dir)
effective = [t for t in slug if t not in _LOWERING_MODE_TOKENS or t in floor]
effective.extend(t for t in floor if t not in _LOWERING_MODE_TOKENS and t not in effective)
return effective
def _read_counter(path: Path) -> int:
try:
raw = path.read_text(encoding="ascii", errors="strict").strip()
@@ -324,13 +368,15 @@ def ledger_line_count(plan_dir: Path) -> int:
return total
def evaluate_gate(plan_dir: Path) -> str | None:
def evaluate_gate(project_dir: Path, plan_dir: Path) -> str | None:
"""The v3 completion gate decision table, in Python, for the Hermes pre_verify hook.
Returns the continuation message when the stop must be held, otherwise
None. Byte-for-byte the same guards as check-complete.sh --gate:
1. <plan-dir>/.mode contains the ``gate`` token (explicit opt-in).
1. The effective mode contains the ``gate`` token (explicit opt-in):
<plan-dir>/.mode, or the project root .mode floor the slug cannot
opt out of (issue #238), which is why the project root is a parameter.
2. An in_progress phase exists; complete < total alone never blocks.
3. (Hermes has no stop_hook_active field; the host bounds re-entry itself
through agent.max_verify_nudges.)
@@ -343,7 +389,7 @@ def evaluate_gate(plan_dir: Path) -> str | None:
"""
if os.environ.get("PLANNING_DISABLED", "") == "1":
return None
if "gate" not in mode_tokens(plan_dir):
if "gate" not in mode_tokens(project_dir, plan_dir):
return None
try:
task_plan = (plan_dir / "task_plan.md").read_text(encoding="utf-8", errors="replace")
@@ -394,7 +440,7 @@ def summarize_status(project_dir: Path) -> dict[str, Any]:
progress_path = plan_dir / "progress.md"
task_plan = task_plan_path.read_text(encoding="utf-8")
counts = phase_counts(task_plan)
tokens = mode_tokens(plan_dir)
tokens = mode_tokens(project_dir, plan_dir)
return {
"exists": True,
"project_dir": str(project_dir),
+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.14.0"
version: "3.16.0"
hermes:
tags: [planning, long-running-tasks, context-engineering, workflow]
---
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.mastracode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.14.0"
version: "3.16.0"
---
@@ -254,8 +254,28 @@ SCOPE=""
EXPLICIT=0
[ -n "$PLAN_PREFIX" ] && EXPLICIT=1
[ "$SESSION_ATTACHED" = "1" ] && EXPLICIT=1
if [ -n "${PLAN_ID:-}" ] && slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
if [ -n "${PLAN_ID:-}" ]; then
# A set PLAN_ID is a BINDING, not a hint (issue #237). This inline resolver
# is the one the hooks actually run, so it carries the same rule as
# resolve-plan-dir.sh: a selector that names no directory, fails slug
# validation, or fails containment refuses instead of falling through to
# .active_plan and newest-by-mtime. The fall-through is what let a
# one-character typo inject a DIFFERENT plan while attest-plan.sh locked
# that same wrong plan at rc=0.
#
# Unlike the PWF_PLAN_ROOT refusal above, the notice is userprompt-only.
# pretool fires per tool call and precompact carries no plan body, so
# 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
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
echo "[planning-with-files] PLAN_ID does not name a plan directory under .planning: ${PLAN_ID} — nothing injected. Fix or unset the pin; a broken pin fails closed rather than selecting another plan."
fi
exit 0
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
@@ -476,12 +496,16 @@ if [ "$SCOPE" = "root" ]; then
PROGRESS_FILE="${PLAN_PREFIX}progress.md"
ATTEST_FILE="${PLAN_PREFIX}.plan-attestation"
MODE_FILE="${PLAN_PREFIX}.mode"
ROOT_MODE_FILE=""
NONCE_FILE="${PLAN_PREFIX}.nonce"
else
PLAN_FILE="${RESOLVED}/task_plan.md"
PROGRESS_FILE="${RESOLVED}/progress.md"
ATTEST_FILE="${RESOLVED}/.attestation"
MODE_FILE="${RESOLVED}/.mode"
# The project's own .mode, when it has one (issue #238). In root scope
# MODE_FILE already IS that file, so the second source stays empty.
ROOT_MODE_FILE="${PLAN_PREFIX}.mode"
NONCE_FILE="${RESOLVED}/.nonce"
fi
[ -f "$PLAN_FILE" ] || exit 0
@@ -853,11 +877,52 @@ fi
# gated mode to legacy behavior (platform-critical: per-tool-call injection not
# suppressed, oracle re-hash skipped, raw progress tail injected). Use a grep
# token test, the same pattern check-complete.sh guard 1 uses.
# --- Root .mode is a FLOOR, not a default that slug scope replaces (#238). ---
# A project makes attestation mandatory by committing a root .mode, which is a
# reviewed project setting. Slug scope used to read ONLY the slug's .mode, and
# init-session.sh writes no .mode unless --autonomous or --gated was passed, so
# `init-session.sh <name>` produced a plan with no mode, no attestation
# requirement and full injection: one agent-invocable command turned the
# project's policy off.
#
# mode_has answers for a strictness-RAISING token: present in EITHER file. A
# slug may opt into autonomous/gated where the root left it unset; it can no
# longer opt out of what the root committed.
#
# mode_relax_allowed answers for the one strictness-LOWERING token
# (plan-guard-off): the slug must carry it AND, when the project committed a
# root .mode, that file must carry it too. A slug alone cannot switch off a
# protection the project kept on.
#
# With no root .mode present ROOT_MODE_FILE is either empty (root scope) or
# names a missing file, so the effective token set is exactly the slug's and
# existing projects are byte-identical.
mode_has() {
_mh_token="$1"
if [ -f "$MODE_FILE" ] && grep -q "$_mh_token" "$MODE_FILE" 2>/dev/null; then
return 0
fi
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ] \
&& grep -q "$_mh_token" "$ROOT_MODE_FILE" 2>/dev/null; then
return 0
fi
return 1
}
mode_relax_allowed() {
_mr_token="$1"
[ -f "$MODE_FILE" ] || return 1
grep -q "$_mr_token" "$MODE_FILE" 2>/dev/null || return 1
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ]; then
grep -q "$_mr_token" "$ROOT_MODE_FILE" 2>/dev/null || return 1
fi
return 0
}
MODE=""
if [ -f "$MODE_FILE" ]; then
grep -q 'autonomous' "$MODE_FILE" 2>/dev/null && MODE='autonomous'
grep -q 'gate' "$MODE_FILE" 2>/dev/null && MODE='gated'
fi
mode_has 'autonomous' && MODE='autonomous'
mode_has 'gate' && MODE='gated'
# In autonomous/gated mode the per-tool-call injection is dropped (recitation
# policy): strong models do not need the plan re-recited before every tool call,
@@ -881,7 +946,7 @@ fi
SMART=0
if [ "${PWF_INJECT:-}" = "smart" ]; then
SMART=1
elif [ -f "$MODE_FILE" ] && grep -q 'inject-smart' "$MODE_FILE" 2>/dev/null; then
elif mode_has 'inject-smart'; then
SMART=1
fi
@@ -1149,7 +1214,7 @@ esac
# holding the stale copy. Per-session keying needs PWF_SESSION_ID, which most
# hosts never set.
GUARD=1
[ -f "$MODE_FILE" ] && grep -q 'plan-guard-off' "$MODE_FILE" 2>/dev/null && GUARD=0
mode_relax_allowed 'plan-guard-off' && GUARD=0
[ "${PWF_PLAN_GUARD:-}" = "0" ] && GUARD=0
if [ "$GUARD" = "1" ]; then
# Same user-private cache root and same absolute-path key as the attestation
@@ -68,6 +68,15 @@ if [ -n "${ARG_DIR}" ]; then
elif [ -f "${RESOLVER}" ]; then
PLAN_DIR="$(sh "${RESOLVER}" 2>/dev/null)"
if [ -z "${PLAN_DIR}" ] || [ ! -d "${PLAN_DIR}" ]; then
# Explicit selectors are bindings, not hints (issue #237). A rejected
# PLAN_ID or PWF_PLAN_ROOT must not fall back to the cwd: this summary
# is injected into autonomous turns, so reporting the ROOT plan's
# phase counts under a mistyped pin feeds the loop another plan's
# termination signal. Degrade loudly, the same way a missing resolver
# already does.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
emit_unavailable "explicit PLAN_ID or PWF_PLAN_ROOT did not resolve"
fi
PLAN_DIR="."
fi
else
@@ -297,7 +297,34 @@ resolve_latest_dir() {
return 1
}
if resolve_from_env; then exit 0; fi
# A set PLAN_ID is a BINDING, not a hint (issue #237).
#
# resolve_from_env returns 1 both when no selector was set and when the
# selector was rejected, so continuing the chain after it turned a
# one-character typo into a silent switch: .active_plan or newest-by-mtime
# answered instead, attest-plan.sh locked THAT plan at rc=0, and injection
# followed the attestation onto it. commands/plan-attest.md already promised
# the opposite ("It never falls back to another plan").
#
# Any non-empty PLAN_ID therefore terminates resolution here, whether it was
# rejected for slug shape (traversal), for naming no directory, or for failing
# containment. The caller receives an empty result and takes its own
# fail-closed path rather than a different plan. PWF_PLAN_ROOT, the sibling
# selector, has failed closed on any bad value since #212; the two selectors
# now agree.
#
# An EMPTY PLAN_ID still means "unset": init-session.sh passes
# PLAN_ID="${PLAN_ID:-}" into attest-plan.sh on the legacy path and depends on
# that spelling resolving the root plan.
#
# Exit status stays 0 on the refusal (see the header contract). Emptiness is
# the fail-closed signal on this channel, exactly as the PWF_PLAN_ROOT guard
# above already does it; a non-zero status would kill callers running under
# set -e for a condition that is not an internal error.
if [ -n "${PLAN_ID:-}" ]; then
resolve_from_env && exit 0
exit 0
fi
if resolve_from_active_file; then exit 0; fi
if resolve_latest_dir; then exit 0; fi
exit 0
@@ -13,6 +13,7 @@ import {
gateCounts,
initPlan,
ledgerLineCount,
modeTokens,
nestedLivePlans,
resolvePlan,
slugIsValid,
@@ -90,13 +91,26 @@ describe("resolver", () => {
for (const bad of ["../outside", "bad slug", "/abs", ".hidden"]) {
fs.writeFileSync(path.join(root, ".planning", ".active_plan"), `${bad}\n`)
expect(resolvePlan(root, {}, env).planDir).toBe(root)
// a PLAN_ID that does not resolve falls through, like resolve-plan-dir.sh
expect(resolvePlan(root, {}, { ...env, PLAN_ID: bad }).planDir).toBe(root)
// a rejected PLAN_ID stops resolution instead of falling through to the
// pointer, the newest slug or the legacy root (#237)
expect(resolvePlan(root, {}, { ...env, PLAN_ID: bad }).planDir).toBeNull()
}
expect(slugIsValid("-leading")).toBe(false)
expect(slugIsValid("2026-09-02-run.v2")).toBe(true)
})
it("stops when a valid-shape PLAN_ID names no directory, ignoring the pointer (#237)", () => {
const active = slugPlan(root, "2026-09-02-active", { pointer: true })
expect(resolvePlan(root, {}, env).planDir).toBe(active)
// one typo in the slug: the pointed plan must NOT answer in its place
expect(resolvePlan(root, {}, { ...env, PLAN_ID: "2026-09-02-actve" })).toEqual({
planDir: null,
conflicts: [],
})
// an empty PLAN_ID is still "no selector" and resolves the pointer
expect(resolvePlan(root, {}, { ...env, PLAN_ID: "" }).planDir).toBe(active)
})
it("picks the newest slug by mtime when there is no pointer, and PLAN_ID overrides", () => {
const older = slugPlan(root, "2026-08-01-old")
const newer = slugPlan(root, "2026-09-02-new")
@@ -226,35 +240,83 @@ describe("injection", () => {
describe("gate", () => {
it("blocks, counts, stalls and caps like check-complete.sh --gate", () => {
const dir = slugPlan(root, "2026-09-02-run", { mode: "autonomous gate", attest: true, pointer: true })
const first = evaluateGate(dir, env)
const first = evaluateGate(root, dir, env)
expect(first).toContain("Phase 2: Build the adapter")
expect(first).toContain("(1/3 complete, gate block 1/20)")
expect(fs.readFileSync(path.join(dir, ".stop_blocks"), "utf8").trim()).toBe("1")
expect(evaluateGate(dir, env)).toBeNull()
expect(evaluateGate(root, dir, env)).toBeNull()
fs.writeFileSync(path.join(dir, "ledger-main.jsonl"), '{"tick":1}\n')
expect(evaluateGate(dir, env)).toContain("gate block 2/20")
expect(evaluateGate(root, dir, env)).toContain("gate block 2/20")
fs.writeFileSync(path.join(dir, "ledger-main.jsonl"), '{"tick":1}\n{"tick":2}\n')
expect(evaluateGate(dir, { ...env, PWF_GATE_CAP: "2" })).toBeNull()
expect(evaluateGate(root, dir, { ...env, PWF_GATE_CAP: "2" })).toBeNull()
})
it("never holds legacy, autonomous, complete, heading-less or disabled plans", () => {
const dir = slugPlan(root, "2026-09-02-run", { pointer: true })
expect(evaluateGate(dir, env)).toBeNull()
expect(evaluateGate(root, dir, env)).toBeNull()
fs.writeFileSync(path.join(dir, ".mode"), "autonomous\n")
expect(evaluateGate(dir, env)).toBeNull()
expect(evaluateGate(root, dir, env)).toBeNull()
fs.writeFileSync(path.join(dir, ".mode"), "autonomous gate\n")
expect(evaluateGate(dir, { ...env, PLANNING_DISABLED: "1" })).toBeNull()
expect(evaluateGate(root, dir, { ...env, PLANNING_DISABLED: "1" })).toBeNull()
fs.writeFileSync(path.join(dir, "task_plan.md"), "### Phase 1\n- **Status:** complete\n")
expect(evaluateGate(dir, env)).toBeNull()
expect(evaluateGate(root, dir, env)).toBeNull()
fs.writeFileSync(path.join(dir, "task_plan.md"), "no headings\n- [in_progress]\n")
expect(evaluateGate(dir, env)).toBeNull()
expect(evaluateGate(root, dir, env)).toBeNull()
})
it("counts mixed status formats per field like the shell", () => {
const mixed = "### Phase 1: A\n- **Status:** complete\n\n### Phase 2: B\n- [in_progress]\n\n### Phase 3: C\n- **Status:** pending\n"
expect(gateCounts(mixed)).toEqual({ total: 3, complete: 1, in_progress: 1, pending: 1 })
const dir = slugPlan(root, "2026-09-02-mixed", { text: mixed, mode: "autonomous gate", attest: true, pointer: true })
expect(evaluateGate(dir, env)).toContain("Phase 2: B")
expect(evaluateGate(root, dir, env)).toContain("Phase 2: B")
})
})
describe("root .mode floor (#238)", () => {
it("arms a slug plan that carries no .mode of its own from the project root", () => {
const dir = slugPlan(root, "2026-09-02-arbtask", { attest: true, pointer: true })
// Negative control first: without a root .mode the gate stays off, so the
// assertion below is evidence of the floor rather than of a fixture that
// would have blocked either way.
expect(modeTokens(root, dir)).toEqual([])
expect(evaluateGate(root, dir, env)).toBeNull()
fs.writeFileSync(path.join(root, ".mode"), "autonomous gate\n")
expect(modeTokens(root, dir)).toEqual(expect.arrayContaining(["autonomous", "gate"]))
expect(evaluateGate(root, dir, env)).toContain("Phase 2: Build the adapter")
})
it("lets a slug raise strictness but never lower it", () => {
const raised = slugPlan(root, "2026-09-02-raise", { mode: "autonomous gate" })
fs.writeFileSync(path.join(root, ".mode"), "autonomous\n")
expect(modeTokens(root, raised)).toContain("gate")
const lowered = slugPlan(root, "2026-09-02-lower", { mode: "autonomous plan-guard-off" })
expect(modeTokens(root, lowered)).not.toContain("plan-guard-off")
})
it("keeps plan-guard-off when the root carries it too", () => {
const dir = slugPlan(root, "2026-09-02-agree", { mode: "autonomous plan-guard-off" })
fs.writeFileSync(path.join(root, ".mode"), "autonomous plan-guard-off\n")
expect(modeTokens(root, dir)).toContain("plan-guard-off")
})
it("leaves the slug tokens untouched when the project has no .mode", () => {
const dir = slugPlan(root, "2026-09-02-legacy", { mode: "autonomous plan-guard-off" })
expect(modeTokens(root, dir)).toEqual(["autonomous", "plan-guard-off"])
})
it("refuses a malformed root .mode instead of proceeding as unset", () => {
const dir = slugPlan(root, "2026-09-02-malformed", { mode: "autonomous" })
fs.writeFileSync(path.join(root, ".mode"), "not-a-real-token\n")
expect(modeTokens(root, dir)).toBeNull()
expect(verifyPlan(root, dir)).toEqual({ ok: false, reason: "unsafe mode marker" })
})
it("has no second source in root scope", () => {
fs.writeFileSync(path.join(root, "task_plan.md"), GATED_PLAN)
fs.writeFileSync(path.join(root, ".mode"), "autonomous plan-guard-off\n")
expect(modeTokens(root, root)).toEqual(["autonomous", "plan-guard-off"])
})
})
@@ -1,6 +1,6 @@
{
"name": "opencode-planning-with-files",
"version": "1.0.0",
"version": "1.0.1",
"description": "Native OpenCode plugin for planning-with-files: per-turn plan injection, write reminders, compaction flush, a session-idle completion gate, and pwf_init / pwf_status / pwf_check tools.",
"type": "module",
"main": "dist/index.js",
@@ -30,6 +30,10 @@ export const WRITE_LIKE_TOOLS = new Set(["write", "edit", "patch", "multiedit",
const SLUG_RE = /^[A-Za-z0-9_][A-Za-z0-9._-]*$/
const MODE_TOKENS = new Set(["autonomous", "gate", "inject-smart", "plan-guard-off"])
// The strictness-LOWERING members of MODE_TOKENS. Everything else raises
// strictness, and the root .mode floor (issue #238) treats the two halves in
// opposite directions, so a new token must be classified here deliberately.
const MODE_LOWERING_TOKENS = new Set(["plan-guard-off"])
const READ_PREVIEW_LINES = 50
const PROGRESS_TAIL_LINES = 20
const MAX_SOURCE_BYTES = 4 * 1024 * 1024
@@ -188,11 +192,23 @@ export function resolvePlan(root: string, opts: { planId?: string; explicit?: bo
const planningRoot = path.join(root, ".planning")
const requested = opts.planId !== undefined ? opts.planId : (env.PLAN_ID ?? "").trim()
if (requested) {
// An explicit slug that resolves is authoritative and skips the nested-root
// check. One that does not resolve falls through to the pointer, the newest
// slug and the legacy root, exactly like resolve-plan-dir.sh.
// A set PLAN_ID is a BINDING, not a hint (issue #237).
//
// A slug that resolves is authoritative and skips the nested-root check.
// One that does NOT resolve ends resolution right here. Falling through to
// the pointer, the newest slug and the legacy root turned a one-character
// typo into a silent switch: the operator asked for plan A, .active_plan or
// newest-by-mtime answered with plan B, and B was what got attested and
// injected at rc=0. Every rejection route ends the same way, whether the
// selector failed slug validation (traversal shapes included), named no
// directory, or failed containment. The caller receives "no plan" and takes
// its own fail-closed path rather than a plan nobody selected.
//
// An EMPTY PLAN_ID still means "no selector": resolution continues below
// exactly as before, which is what the legacy root path depends on.
const explicitDir = slugPlanDir(planningRoot, requested)
if (explicitDir) return { planDir: explicitDir, conflicts: [] }
return { planDir: null, conflicts: [] }
}
let chosen: string | null = null
@@ -296,9 +312,9 @@ export function frameBytes(kind: "plan" | "progress", data: Buffer, truncated =
)
}
/** Tokens of <plan-dir>/.mode; [] when absent; null when a token is not allowed. */
export function modeTokens(planDir: string): string[] | null {
const raw = readText(path.join(planDir, ".mode"), 256)
/** Tokens of one directory's .mode; [] when absent; null when a token is not allowed. */
function readModeFile(dir: string): string[] | null {
const raw = readText(path.join(dir, ".mode"), 256)
if (raw === null) return []
const tokens = raw.split(/\s+/).filter(Boolean)
if (tokens.length === 0) return null
@@ -306,13 +322,54 @@ export function modeTokens(planDir: string): string[] | null {
return tokens
}
/**
* Effective mode for a plan: the slug's .mode raised by the project root's
* .mode FLOOR (issue #238). [] when neither file is present; null when either
* file carries a token outside MODE_TOKENS.
*
* A project makes attestation mandatory by committing a root .mode, which is a
* reviewed project setting. Reading only <plan-dir>/.mode let a slug plan
* silently exempt itself: initPlan writes no .mode unless the operator asked
* for a mode, so creating a plan turned the project's policy off in one
* agent-invocable call.
*
* Strictness-RAISING tokens (autonomous, gate, inject-smart) are effective when
* EITHER file carries them: a slug may go stricter than the project asked, it
* can never go looser. The single strictness-LOWERING token (plan-guard-off)
* survives only when the slug carries it AND, where a root .mode exists, that
* file carries it too, so a slug cannot switch off a protection the project
* kept on.
*
* A malformed ROOT .mode returns null, the same "not allowed" signal a
* malformed slug .mode already produces. That is the fail-closed reading: the
* committed policy is unreadable, so verifyPlan refuses the plan ("unsafe mode
* marker") instead of proceeding as if the project had asked for nothing.
*
* With no root .mode the effective set is byte-identical to the slug's, which
* is the invariant existing projects depend on. Root scope has no second
* source at all: <root>/.mode already IS the plan's .mode there.
*/
export function modeTokens(root: string, planDir: string): string[] | null {
const slug = readModeFile(planDir)
if (slug === null) return null
if (path.resolve(planDir) === path.resolve(root)) return slug
const floor = readModeFile(root)
if (floor === null) return null
if (floor.length === 0) return slug
const effective = slug.filter((token) => !MODE_LOWERING_TOKENS.has(token) || floor.includes(token))
for (const token of floor) {
if (!MODE_LOWERING_TOKENS.has(token) && !effective.includes(token)) effective.push(token)
}
return effective
}
export type Verified = { ok: true; plan: Buffer; mode: string } | { ok: false; reason: string }
/** Read task_plan.md and enforce the v3 attestation contract. */
export function verifyPlan(root: string, planDir: string): Verified {
const plan = readBytes(path.join(planDir, "task_plan.md"))
if (plan === null) return { ok: false, reason: "task_plan.md is not a readable regular file (or exceeds 4 MiB)" }
const tokens = modeTokens(planDir)
const tokens = modeTokens(root, planDir)
if (tokens === null) return { ok: false, reason: "unsafe mode marker" }
const mode = tokens.includes("gate") ? "gated" : tokens.includes("autonomous") ? "autonomous" : ""
const attestationRaw = readText(attestationPathFor(root, planDir), 128)
@@ -411,9 +468,9 @@ export function ledgerLineCount(planDir: string): number {
}
/** Returns the continuation message when the stop must be held, otherwise null. */
export function evaluateGate(planDir: string, env: Env): string | null {
export function evaluateGate(root: string, planDir: string, env: Env): string | null {
if (env.PLANNING_DISABLED === "1") return null
const tokens = modeTokens(planDir)
const tokens = modeTokens(root, planDir)
if (!tokens || !tokens.includes("gate")) return null
const text = readText(path.join(planDir, "task_plan.md"))
if (text === null) return null
@@ -694,7 +751,7 @@ export function summarizeStatus(root: string, env: Env): StatusResult {
return { exists: false, message: "No planning files found. Run pwf_init first.", project_dir: root, conflicts }
}
const text = readText(path.join(resolved.planDir, "task_plan.md")) ?? ""
const tokens = modeTokens(resolved.planDir)
const tokens = modeTokens(root, resolved.planDir)
return {
exists: true,
project_dir: root,
@@ -152,8 +152,8 @@ export const PlanningWithFiles: Plugin = async ({ client, directory }) => {
const info = await sessionInfo(sessionID)
if (!info.known || info.child) return
const located = locate(info.dir)
if (!located.planDir) return
const reason = evaluateGate(located.planDir, env)
if (!located.planDir || !located.root) return
const reason = evaluateGate(located.root, located.planDir, env)
if (!reason) return
gateInFlight.add(sessionID)
await client.session.promptAsync({
@@ -36,7 +36,7 @@ hooks:
- type: command
command: "SH=\"\"; for c in \"${PWF_SCRIPT_DIR}/inject-plan.sh\" \"${CLAUDE_SKILL_DIR}/scripts/inject-plan.sh\" \"$HOME/.config/opencode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.opencode/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/skills/planning-with-files/scripts/inject-plan.sh\" \"$HOME/.claude/plugins/marketplaces/planning-with-files/scripts/inject-plan.sh\"; do [ -f \"$c\" ] && { SH=\"$c\"; break; }; done; [ -n \"$SH\" ] && sh \"$SH\" --context=precompact; exit 0"
metadata:
version: "3.14.0"
version: "3.16.0"
---
@@ -254,8 +254,28 @@ SCOPE=""
EXPLICIT=0
[ -n "$PLAN_PREFIX" ] && EXPLICIT=1
[ "$SESSION_ATTACHED" = "1" ] && EXPLICIT=1
if [ -n "${PLAN_ID:-}" ] && slug_is_valid "$PLAN_ID" && [ -d "${PLAN_PREFIX}.planning/${PLAN_ID}" ]; then
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
if [ -n "${PLAN_ID:-}" ]; then
# A set PLAN_ID is a BINDING, not a hint (issue #237). This inline resolver
# is the one the hooks actually run, so it carries the same rule as
# resolve-plan-dir.sh: a selector that names no directory, fails slug
# validation, or fails containment refuses instead of falling through to
# .active_plan and newest-by-mtime. The fall-through is what let a
# one-character typo inject a DIFFERENT plan while attest-plan.sh locked
# that same wrong plan at rc=0.
#
# Unlike the PWF_PLAN_ROOT refusal above, the notice is userprompt-only.
# pretool fires per tool call and precompact carries no plan body, so
# 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
RESOLVED="${PLAN_PREFIX}.planning/${PLAN_ID}"; SCOPE="scoped"; EXPLICIT=1
else
if [ "$CONTEXT" = "userprompt" ]; then
echo "[planning-with-files] PLAN_ID does not name a plan directory under .planning: ${PLAN_ID} — nothing injected. Fix or unset the pin; a broken pin fails closed rather than selecting another plan."
fi
exit 0
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
@@ -476,12 +496,16 @@ if [ "$SCOPE" = "root" ]; then
PROGRESS_FILE="${PLAN_PREFIX}progress.md"
ATTEST_FILE="${PLAN_PREFIX}.plan-attestation"
MODE_FILE="${PLAN_PREFIX}.mode"
ROOT_MODE_FILE=""
NONCE_FILE="${PLAN_PREFIX}.nonce"
else
PLAN_FILE="${RESOLVED}/task_plan.md"
PROGRESS_FILE="${RESOLVED}/progress.md"
ATTEST_FILE="${RESOLVED}/.attestation"
MODE_FILE="${RESOLVED}/.mode"
# The project's own .mode, when it has one (issue #238). In root scope
# MODE_FILE already IS that file, so the second source stays empty.
ROOT_MODE_FILE="${PLAN_PREFIX}.mode"
NONCE_FILE="${RESOLVED}/.nonce"
fi
[ -f "$PLAN_FILE" ] || exit 0
@@ -853,11 +877,52 @@ fi
# gated mode to legacy behavior (platform-critical: per-tool-call injection not
# suppressed, oracle re-hash skipped, raw progress tail injected). Use a grep
# token test, the same pattern check-complete.sh guard 1 uses.
# --- Root .mode is a FLOOR, not a default that slug scope replaces (#238). ---
# A project makes attestation mandatory by committing a root .mode, which is a
# reviewed project setting. Slug scope used to read ONLY the slug's .mode, and
# init-session.sh writes no .mode unless --autonomous or --gated was passed, so
# `init-session.sh <name>` produced a plan with no mode, no attestation
# requirement and full injection: one agent-invocable command turned the
# project's policy off.
#
# mode_has answers for a strictness-RAISING token: present in EITHER file. A
# slug may opt into autonomous/gated where the root left it unset; it can no
# longer opt out of what the root committed.
#
# mode_relax_allowed answers for the one strictness-LOWERING token
# (plan-guard-off): the slug must carry it AND, when the project committed a
# root .mode, that file must carry it too. A slug alone cannot switch off a
# protection the project kept on.
#
# With no root .mode present ROOT_MODE_FILE is either empty (root scope) or
# names a missing file, so the effective token set is exactly the slug's and
# existing projects are byte-identical.
mode_has() {
_mh_token="$1"
if [ -f "$MODE_FILE" ] && grep -q "$_mh_token" "$MODE_FILE" 2>/dev/null; then
return 0
fi
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ] \
&& grep -q "$_mh_token" "$ROOT_MODE_FILE" 2>/dev/null; then
return 0
fi
return 1
}
mode_relax_allowed() {
_mr_token="$1"
[ -f "$MODE_FILE" ] || return 1
grep -q "$_mr_token" "$MODE_FILE" 2>/dev/null || return 1
if [ -n "$ROOT_MODE_FILE" ] && [ -f "$ROOT_MODE_FILE" ]; then
grep -q "$_mr_token" "$ROOT_MODE_FILE" 2>/dev/null || return 1
fi
return 0
}
MODE=""
if [ -f "$MODE_FILE" ]; then
grep -q 'autonomous' "$MODE_FILE" 2>/dev/null && MODE='autonomous'
grep -q 'gate' "$MODE_FILE" 2>/dev/null && MODE='gated'
fi
mode_has 'autonomous' && MODE='autonomous'
mode_has 'gate' && MODE='gated'
# In autonomous/gated mode the per-tool-call injection is dropped (recitation
# policy): strong models do not need the plan re-recited before every tool call,
@@ -881,7 +946,7 @@ fi
SMART=0
if [ "${PWF_INJECT:-}" = "smart" ]; then
SMART=1
elif [ -f "$MODE_FILE" ] && grep -q 'inject-smart' "$MODE_FILE" 2>/dev/null; then
elif mode_has 'inject-smart'; then
SMART=1
fi
@@ -1149,7 +1214,7 @@ esac
# holding the stale copy. Per-session keying needs PWF_SESSION_ID, which most
# hosts never set.
GUARD=1
[ -f "$MODE_FILE" ] && grep -q 'plan-guard-off' "$MODE_FILE" 2>/dev/null && GUARD=0
mode_relax_allowed 'plan-guard-off' && GUARD=0
[ "${PWF_PLAN_GUARD:-}" = "0" ] && GUARD=0
if [ "$GUARD" = "1" ]; then
# Same user-private cache root and same absolute-path key as the attestation
@@ -68,6 +68,15 @@ if [ -n "${ARG_DIR}" ]; then
elif [ -f "${RESOLVER}" ]; then
PLAN_DIR="$(sh "${RESOLVER}" 2>/dev/null)"
if [ -z "${PLAN_DIR}" ] || [ ! -d "${PLAN_DIR}" ]; then
# Explicit selectors are bindings, not hints (issue #237). A rejected
# PLAN_ID or PWF_PLAN_ROOT must not fall back to the cwd: this summary
# is injected into autonomous turns, so reporting the ROOT plan's
# phase counts under a mistyped pin feeds the loop another plan's
# termination signal. Degrade loudly, the same way a missing resolver
# already does.
if [ -n "${PLAN_ID:-}" ] || [ -n "${PWF_PLAN_ROOT:-}" ]; then
emit_unavailable "explicit PLAN_ID or PWF_PLAN_ROOT did not resolve"
fi
PLAN_DIR="."
fi
else
@@ -297,7 +297,34 @@ resolve_latest_dir() {
return 1
}
if resolve_from_env; then exit 0; fi
# A set PLAN_ID is a BINDING, not a hint (issue #237).
#
# resolve_from_env returns 1 both when no selector was set and when the
# selector was rejected, so continuing the chain after it turned a
# one-character typo into a silent switch: .active_plan or newest-by-mtime
# answered instead, attest-plan.sh locked THAT plan at rc=0, and injection
# followed the attestation onto it. commands/plan-attest.md already promised
# the opposite ("It never falls back to another plan").
#
# Any non-empty PLAN_ID therefore terminates resolution here, whether it was
# rejected for slug shape (traversal), for naming no directory, or for failing
# containment. The caller receives an empty result and takes its own
# fail-closed path rather than a different plan. PWF_PLAN_ROOT, the sibling
# selector, has failed closed on any bad value since #212; the two selectors
# now agree.
#
# An EMPTY PLAN_ID still means "unset": init-session.sh passes
# PLAN_ID="${PLAN_ID:-}" into attest-plan.sh on the legacy path and depends on
# that spelling resolving the root plan.
#
# Exit status stays 0 on the refusal (see the header contract). Emptiness is
# the fail-closed signal on this channel, exactly as the PWF_PLAN_ROOT guard
# above already does it; a non-zero status would kill callers running under
# set -e for a condition that is not an internal error.
if [ -n "${PLAN_ID:-}" ]; then
resolve_from_env && exit 0
exit 0
fi
if resolve_from_active_file; then exit 0; fi
if resolve_latest_dir; then exit 0; fi
exit 0
+1 -1
View File
@@ -220,7 +220,7 @@ Helper scripts for automation:
- `scripts/init-session.sh` — Initialize planning files. With a name arg, creates an isolated plan under `.planning/YYYY-MM-DD-<slug>/` for parallel task workflows. Without args, writes `task_plan.md` at project root (legacy mode, backward-compatible).
- `scripts/set-active-plan.sh` — Switch the active plan pointer (`.planning/.active_plan`). Run with a plan ID to switch; run without args to show which plan is current.
- `scripts/resolve-plan-dir.sh` — Resolve the active plan directory. Checks `$PLAN_ID` env var first, then `.planning/.active_plan`, then newest plan dir by mtime, then falls back to project root (legacy). Used internally by hooks.
- `scripts/resolve-plan-dir.sh` — Resolve the active plan directory. A set `$PLAN_ID` is a binding: it resolves or resolution stops, never another plan (issue #237). With no `$PLAN_ID`, checks `.planning/.active_plan`, then newest plan dir by mtime, then falls back to project root (legacy). Used internally by hooks.
- `scripts/check-complete.sh` — Verify all phases in the active plan are complete.
- `scripts/session-catchup.py`: Explicit same-project session-record aggregation or bounded replay (`--metadata` / `--replay`); bare invocation does not access host history.
- `scripts/attest-plan.sh` (and `.ps1`) — Lock the current `task_plan.md` content with a SHA-256 attestation (v2.37.0). Hooks then refuse to inject plan content if the file diverges from the attested hash. Use `--show` to print the stored hash, `--clear` to remove the attestation. See `/plan-attest` command.
@@ -133,7 +133,7 @@ describe("slug validation and containment parity with the sh resolver (v3.8.1)",
}
});
it("rejects a PLAN_ID containing whitespace", () => {
it("stops on a PLAN_ID containing whitespace instead of resolving another plan (#237)", () => {
const root = makeWorkspace();
writeScopedPlan(root, "plan a", "# spaced");
writeScopedPlan(root, "plan-fallback", "# fallback");
@@ -142,7 +142,25 @@ describe("slug validation and containment parity with the sh resolver (v3.8.1)",
process.env.PLAN_ID = "plan a";
try {
const paths = resolvePlanPaths(root);
expect(paths.planId).toBe("plan-fallback");
expect(paths.scope).toBe("none");
expect(paths.planId).toBeUndefined();
} finally {
if (previous === undefined) delete process.env.PLAN_ID;
else process.env.PLAN_ID = previous;
}
});
it("stops when a valid-shape PLAN_ID names no directory, ignoring .active_plan (#237)", () => {
const root = makeWorkspace();
writeScopedPlan(root, "plan-active", "# active");
writeFileSync(join(root, ".planning", ".active_plan"), "plan-active");
const previous = process.env.PLAN_ID;
process.env.PLAN_ID = "plan-actve";
try {
const paths = resolvePlanPaths(root);
expect(paths.scope).toBe("none");
expect(paths.planId).toBeUndefined();
} finally {
if (previous === undefined) delete process.env.PLAN_ID;
else process.env.PLAN_ID = previous;
@@ -1,6 +1,6 @@
{
"name": "planning-with-files-pi-extension",
"version": "1.2.4",
"version": "1.2.5",
"private": true,
"type": "module",
"scripts": {

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