From f58b89243653b8207f006460e75d4a39bc8348a1 Mon Sep 17 00:00:00 2001
From: Kjell Tore Guttormsen <hello@fromaitochitta.com>
Date: Mon, 4 May 2026 16:40:11 +0200
Subject: [PATCH] =?UTF-8?q?fix(ultraplan-local):=20Bug=202=20=E2=80=94=20e?=
 =?UTF-8?q?liminate=20state-file-path=20template;=20Read=20tool=20+=20conc?=
 =?UTF-8?q?rete=20arg?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 5 of v3.4.1 hot-fix plan. Phase 2 of
commands/ultracontinue-local.md is rewritten to remove every curly-
brace template placeholder. The {state-file-path} substitution failure
caused the path-guard hook to crash on unresolved templates.

New Phase 2 structure:

  2.a — Read the file with the Read tool (no Bash). Deterministic and
        not subject to shell-substitution errors.
  2.b — Schema-validate via the existing CLI shim, with the resolved
        absolute path emitted as a literal string token by the model
        at the time of the Bash call. Anti-substitution invariant:
        STOP if about to emit any unresolved placeholder.
  2.c — Interpret validator result (preserved verbatim from the
        previous Phase 2 — three-way branch on valid + status).

Verification: grep -c "{state-file-path}" returns 0; full Phase 2
section contains no {lowercase-template} curly-brace placeholders.
Suite 322 -> 335 passing (+13: 7 from Step 1, 4 from Step 2, 2 from
Step 4).
---
 .../commands/ultracontinue-local.md           | 44 ++++++++++++++-----
 1 file changed, 34 insertions(+), 10 deletions(-)

diff --git a/plugins/ultraplan-local/commands/ultracontinue-local.md b/plugins/ultraplan-local/commands/ultracontinue-local.md
index 2159c79..85f154e 100644
--- a/plugins/ultraplan-local/commands/ultracontinue-local.md
+++ b/plugins/ultraplan-local/commands/ultracontinue-local.md
@@ -119,21 +119,45 @@ resumable state wins.
 
 ## Phase 2 — Validate the state file
 
-Run the validator from a Bash invocation:
+Phase 1 resolved a concrete state-file path. That path is a real string in
+your working context — never a template. Phase 2 must read and validate the
+state file without any placeholder substitution.
 
-```bash
-!`node lib/validators/session-state-validator.mjs --json {state-file-path}`
+### Step 2.a — Read the file with the Read tool (no Bash)
+
+Use the **Read tool** on the resolved state-file path from Phase 1. Do NOT use
+Bash for the read. The Read tool is deterministic and not subject to
+shell-substitution errors. Parse the returned JSON body programmatically.
+
+### Step 2.b — Schema-validate the parsed object
+
+Verify the schema by invoking the existing validator CLI shim. Emit the
+resolved absolute path as a literal string token in the Bash command — the
+exact same string you just passed to the Read tool. The validator accepts
+`--json <path>` and prints a `{valid, errors, warnings}` JSON record:
+
+```
+node lib/validators/session-state-validator.mjs --json <RESOLVED-ABSOLUTE-PATH-FROM-PHASE-1>
 ```
 
-Interpret the result:
+Replace `<RESOLVED-ABSOLUTE-PATH-FROM-PHASE-1>` with the actual path string at
+the time you issue the Bash call. There is no template engine; the string is
+substituted by you, the model, before the Bash tool sees the command.
+
+**Anti-substitution invariant.** If you ever find yourself about to emit a
+literal angle-bracket placeholder, or any other unresolved variable name, to
+the Bash tool — STOP. The resolved path is a concrete value you already have
+from Phase 1; emit the value, not a placeholder for it.
+
+### Step 2.c — Interpret the result
 
 - **Validator exit code != 0 OR `valid: false` in JSON output:** print the
-  structured `errors[]` (each `[code] message` on its own line) and exit. Do not
-  proceed to narration. Suggest running the validator directly for follow-up:
-  `node lib/validators/session-state-validator.mjs <path>`.
-- **`valid: true` AND any warning has `code: SESSION_STATE_NOT_RESUMABLE`** (i.e.
-  `status: completed`): print "no further sessions to resume; project complete"
-  and exit cleanly.
+  structured `errors[]` (each `[code] message` on its own line) and exit. Do
+  not proceed to narration. Suggest running the validator directly for
+  follow-up: `node lib/validators/session-state-validator.mjs <path>`.
+- **`valid: true` AND any warning has `code: SESSION_STATE_NOT_RESUMABLE`**
+  (i.e. `status: completed`): print "no further sessions to resume; project
+  complete" and exit cleanly.
 - **`valid: true` AND status is one of `in_progress | partial | failed | stopped`:**
   proceed to Phase 3.