planning-with-files 3.14.0 → 3.16.0

package/SKILL.md

@@ -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.

package/extensions/planning-with-files/__tests__/plan-anchor.test.ts

@@ -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;

package/extensions/planning-with-files/package.json

@@ -1,17 +1,17 @@
-{
-  "name": "planning-with-files-pi-extension",
-  "version": "1.2.4",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "test": "vitest run"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.1",
-    "typescript": "^5.7.2",
-    "vitest": "^2.1.8"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
-  }
-}
+{
+  "name": "planning-with-files-pi-extension",
+  "version": "1.2.5",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/extensions/planning-with-files/plan.ts

@@ -144,12 +144,35 @@ export function resolvePlanPaths(sessionCwd: string): PlanPaths {
 		attestationCandidates: [join(cwd, ".plan-attestation")],
 	});
 
+	const makeNone = (): PlanPaths => ({
+		cwd,
+		scope: "none",
+		attestationCandidates: [join(cwd, ".plan-attestation")],
+	});
+
+	// A set PLAN_ID is a BINDING, not a hint (issue #237).
+	//
+	// A slug that resolves to a contained scoped plan wins. One that does NOT
+	// resolve ends resolution right here. Falling through to .active_plan, the
+	// newest slug and the root plan turned a one-character typo into a silent
+	// switch: the operator asked for plan A, the pointer 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_RE (traversal shapes included), named no plan directory, or failed
+	// containment. The session gets the "none" scope and takes its own
+	// fail-closed path rather than a plan nobody selected.
+	//
+	// An EMPTY or unset PLAN_ID still means "no selector": resolution continues
+	// below exactly as before, which is what the legacy root path depends on.
 	const planId = process.env.PLAN_ID?.trim();
-	if (planId && SLUG_RE.test(planId)) {
-		const candidate = join(planRoot, planId);
-		if (existsSync(join(candidate, "task_plan.md")) && isWithinRoot(cwd, candidate)) {
-			return makeScoped(candidate);
+	if (planId) {
+		if (SLUG_RE.test(planId)) {
+			const candidate = join(planRoot, planId);
+			if (existsSync(join(candidate, "task_plan.md")) && isWithinRoot(cwd, candidate)) {
+				return makeScoped(candidate);
+			}
 		}
+		return makeNone();
 	}
 
 	const activePlanFile = join(planRoot, ".active_plan");
@@ -176,11 +199,7 @@ export function resolvePlanPaths(sessionCwd: string): PlanPaths {
 		return rootPlan;
 	}
 
-	return {
-		cwd,
-		scope: "none",
-		attestationCandidates: [join(cwd, ".plan-attestation")],
-	};
+	return makeNone();
 }
 
 export function readPlanStatus(cwd: string): PlanStatus {

package/package.json

@@ -1,56 +1,56 @@
-{
-  "name": "planning-with-files",
-  "version": "3.14.0",
-  "description": "Persistent project planning with selected context injection. Automatic recovery uses project files only; explicit catchup modes read same-project local session records for aggregate counts or bounded replay. The host-aware gate never runs Markdown-declared commands. No network upload path. Ships the skill plus a Pi Coding Agent extension.",
-  "keywords": [
-    "pi-package",
-    "pi-skill",
-    "planning",
-    "manus",
-    "agent",
-    "agent-skills",
-    "claude-code",
-    "claude-skills",
-    "coding-agent",
-    "context-engineering",
-    "session-recovery",
-    "long-running-agents"
-  ],
-  "pi": {
-    "skills": [
-      "SKILL.md"
-    ],
-    "extensions": [
-      "extensions/planning-with-files/index.ts"
-    ]
-  },
-  "scripts": {
-    "prepack": "node scripts/verify-shell-line-endings.mjs"
-  },
-  "files": [
-    "README.md",
-    "SKILL.md",
-    "examples.md",
-    "reference.md",
-    "scripts/",
-    "templates/",
-    "extensions/",
-    "!**/node_modules",
-    "!**/__pycache__",
-    "!**/*.pyc",
-    "!extensions/planning-with-files/package-lock.json"
-  ],
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/OthmanAdi/planning-with-files.git"
-  },
-  "author": "Ahmad Othman Ammar Adi",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/OthmanAdi/planning-with-files/issues"
-  },
-  "homepage": "https://github.com/OthmanAdi/planning-with-files#readme"
-}
+{
+  "name": "planning-with-files",
+  "version": "3.16.0",
+  "description": "Persistent project planning with selected context injection. Automatic recovery uses project files only; explicit catchup modes read same-project local session records for aggregate counts or bounded replay. The host-aware gate never runs Markdown-declared commands. No network upload path. Ships the skill plus a Pi Coding Agent extension.",
+  "keywords": [
+    "pi-package",
+    "pi-skill",
+    "planning",
+    "manus",
+    "agent",
+    "agent-skills",
+    "claude-code",
+    "claude-skills",
+    "coding-agent",
+    "context-engineering",
+    "session-recovery",
+    "long-running-agents"
+  ],
+  "pi": {
+    "skills": [
+      "SKILL.md"
+    ],
+    "extensions": [
+      "extensions/planning-with-files/index.ts"
+    ]
+  },
+  "scripts": {
+    "prepack": "node scripts/verify-shell-line-endings.mjs"
+  },
+  "files": [
+    "README.md",
+    "SKILL.md",
+    "examples.md",
+    "reference.md",
+    "scripts/",
+    "templates/",
+    "extensions/",
+    "!**/node_modules",
+    "!**/__pycache__",
+    "!**/*.pyc",
+    "!extensions/planning-with-files/package-lock.json"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OthmanAdi/planning-with-files.git"
+  },
+  "author": "Ahmad Othman Ammar Adi",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/OthmanAdi/planning-with-files/issues"
+  },
+  "homepage": "https://github.com/OthmanAdi/planning-with-files#readme"
+}

package/scripts/attest-plan.sh

@@ -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
 }
 

package/scripts/check-complete.ps1

@@ -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) {

package/scripts/check-complete.sh

@@ -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

package/scripts/init-session.sh

@@ -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"

package/scripts/inject-plan.sh

@@ -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

package/scripts/ledger-append.ps1

@@ -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"
 

package/scripts/ledger-append.sh

@@ -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"
 

package/scripts/ledger-summary.ps1

@@ -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 ---

package/scripts/ledger-summary.sh

@@ -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

package/scripts/phase-status.ps1

@@ -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
 }
 

package/scripts/phase-status.sh

@@ -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
 }
 

package/scripts/plan-doctor.sh

@@ -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

package/scripts/resolve-plan-dir.ps1

@@ -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

package/scripts/resolve-plan-dir.sh

@@ -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