@spexcode/spec-cli 0.7.0-next.14 → 0.7.0-next.15

package/dist/hook-prompts.js

@@ -25,7 +25,7 @@ const STOP_GATE_VARIANTS = Object.freeze({
         '(This full explanation shows once per session; later undeclared stops get a one-line reminder. `{cli} help session` re-explains the choices any time.)',
     ].join('\n'),
     terse: 'undeclared stop — declare the ONE true state as your LAST call: `{cli} session <done --propose merge (review; ONLY clickable merge)|close (close-pending; settled, no human decision/follow-up or posted artifact waiting)|park (parked; real wake-up + next action) / ask (asking; human reply/direction/decision, including reported finding/recommendation or handoff)>`. `done --propose nothing` is a trap: it writes no state and names these choices. Conditions: `{cli} help session`.',
-    artifact: 'a posted file/web artifact still needs human inspection; declare `spex session ask --note ...`, and declare it last.',
+    artifact: 'a posted file/web artifact still needs human inspection; declare `{cli} session ask --note ...`, and declare it last.',
     commit: 'Not ready to declare done: {reason}. The dogfood ritual lands every change as a git commit on your node branch BEFORE you propose. Commit your spec.md + code on this node branch (spec: <id> — <reason>, with a Session: trailer), then re-run `{cli} session done --propose {proposal}`.',
     eval: 'eval — the loss signal the optimizer reads — flags {count} gap(s) in nodes you changed: {ids}. A node whose score went stale/unmeasured: re-measure it — PRODUCE the measurement YOURSELF with a real run of the scenario\'s actual surface (its tag on the `spex eval lint --changed` line tells you WHICH surface to run), compare to expected, and file it with `spex eval add <node>`; don\'t desk-check it, and don\'t defer to reviewing a recording after the fact. A FRONTEND node with no eval.md: give it one (a scenario — description + expected), since an obvious UI change should carry a loss signal. `spex eval lint --changed` lists them. (Advisory — fires once, not a gate.)',
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spexcode/spec-cli",
-  "version": "0.7.0-next.14",
+  "version": "0.7.0-next.15",
   "type": "module",
   "description": "SpexCode CLI + server. The root spexcode package delegates to this compiled package; dashboard assets live in @spexcode/spec-dashboard.",
   "bin": {
@@ -35,12 +35,12 @@
     "test": "tsx --import ../scripts/test-home.mjs --test src/*.test.ts"
   },
   "dependencies": {
-    "@spexcode/session-application": "0.7.0-next.14",
-    "@spexcode/session-selflaunch": "0.7.0-next.14",
-    "@spexcode/spec-core": "0.7.0-next.14",
-    "@spexcode/spec-eval": "0.7.0-next.14",
-    "@spexcode/spec-forge": "0.7.0-next.14",
-    "@spexcode/transcript": "0.7.0-next.14",
+    "@spexcode/session-application": "0.7.0-next.15",
+    "@spexcode/session-selflaunch": "0.7.0-next.15",
+    "@spexcode/spec-core": "0.7.0-next.15",
+    "@spexcode/spec-eval": "0.7.0-next.15",
+    "@spexcode/spec-forge": "0.7.0-next.15",
+    "@spexcode/transcript": "0.7.0-next.15",
     "smol-toml": "^1.8.0"
   },
   "devDependencies": {

package/templates/spec/project/.plugins/core/session-listen/session-listen.sh

@@ -62,6 +62,19 @@ if printf ' 0a ' | grep -Eq "$control_pattern"; then capability_error 'grep exte
 [ "$(printf 'A\nB\n' | awk "$escape_awk")" = 'A\nB' ] || capability_error 'awk JSON text escaping'
 [ "$(printf A | cat)" = A ] || capability_error 'cat byte emission'
 
+# @@@ a failed delivery must not eat the person's own prompt - this hook runs ON UserPromptSubmit, so exiting 2
+# BLOCKS what the person just typed. Two different harms came out of that. A transient dequeue failure consumed
+# nothing, yet the person lost their own unrelated prompt for it. And a failure AFTER a successful dequeue lost
+# the peer message for good (the queue is at-most-once) and then took the person's prompt as a second casualty
+# — blocking cannot bring the message back, it only doubles the loss. So a delivery failure reports itself
+# through the SAME channel the message would have used and lets the prompt through. The notice is ASCII only
+# (an id and base64), so it needs no escaping pass of its own.
+notify_failure() {
+  printf '{"hookSpecificOutput":{"hookEventName":"UserPromptSubmit","additionalContext":"%s"}}\n' "$1"
+  printf '%s\n' "$1" >&2
+  exit 0
+}
+
 . "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
 payload=$(cat 2>/dev/null || true)
 sid=$(hp_field "$payload" session_id)
@@ -73,47 +86,37 @@ case "$event" in
     "$cli" initialize --session-id "$sid" >/dev/null || exit 2
     ;;
   UserPromptSubmit)
-    decoded=$(mktemp "${TMPDIR:-/tmp}/spex-session-listen.XXXXXX") || {
-      printf '%s\n' 'session-listen: could not allocate a temporary body file; repair TMPDIR and retry' >&2
-      exit 2
-    }
+    decoded=$(mktemp "${TMPDIR:-/tmp}/spex-session-listen.XXXXXX") \
+      || notify_failure 'session-listen could not allocate a temporary body file, so it read nothing this turn. Repair TMPDIR. Any queued message is still queued.'
     escaped_file="$decoded.escaped"
     output_file="$decoded.output"
     if ! : >"$escaped_file" || ! : >"$output_file"; then
-      rm -f "$decoded"
-      rm -f "$escaped_file" "$output_file"
-      printf '%s\n' 'session-listen: could not prepare temporary delivery files; repair TMPDIR and retry' >&2
-      exit 2
+      rm -f "$decoded" "$escaped_file" "$output_file"
+      notify_failure 'session-listen could not prepare its temporary delivery files, so it read nothing this turn. Repair TMPDIR. Any queued message is still queued.'
     fi
     cleanup() { rm -f "$decoded" "$escaped_file" "$output_file"; }
     trap cleanup EXIT
-    raw=$("$cli" dequeue --session-id "$sid") || exit 2
+    raw=$("$cli" dequeue --session-id "$sid") || notify_failure 'session-listen could not read the message queue this turn. Nothing was consumed, so any queued message is still there and arrives on the next turn.' 
     [ "$raw" = 'null' ] && exit 0
     body64=$(printf '%s' "$raw" | sed -n "$body64_sed")
     message_id=$(printf '%s' "$raw" | sed -n 's/.*"messageId":"\([^"]*\)".*/\1/p')
     [ -n "$body64" ] || {
-      printf '%s\n' 'session-listen: spex-session dequeue returned invalid JSON (missing bodyBase64)' >&2
-      exit 2
+      notify_failure "$(printf 'session-listen dequeued a message it could not deliver, and the queue is at-most-once, so the message is gone from it. Recover it from this line. reason=%s messageId=%s bodyBase64=%s' "invalid-json-missing-bodyBase64" "$message_id" "$body64")"
     }
     if ! printf '%s' "$body64" | base64 -d >"$decoded" 2>/dev/null; then
-      printf '%s\n' 'session-listen: spex-session dequeue returned invalid bodyBase64' >&2
-      exit 2
+      notify_failure "$(printf 'session-listen dequeued a message it could not deliver, and the queue is at-most-once, so the message is gone from it. Recover it from this line. reason=%s messageId=%s bodyBase64=%s' "invalid-bodyBase64" "$message_id" "$body64")"
     fi
     if ! iconv -f UTF-8 -t UTF-8 "$decoded" >/dev/null 2>/dev/null; then
-      printf 'session-listen: refusing non-UTF-8 body; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
-      exit 2
+      notify_failure "$(printf 'session-listen dequeued a message it could not deliver, and the queue is at-most-once, so the message is gone from it. Recover it from this line. reason=%s messageId=%s bodyBase64=%s' "non-utf8-body" "$message_id" "$body64")"
     fi
     if od -An -v -tx1 "$decoded" | grep -Eq "$control_pattern"; then
-      printf 'session-listen: refusing control-byte body; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
-      exit 2
+      notify_failure "$(printf 'session-listen dequeued a message it could not deliver, and the queue is at-most-once, so the message is gone from it. Recover it from this line. reason=%s messageId=%s bodyBase64=%s' "control-byte-body" "$message_id" "$body64")"
     fi
     if ! awk "$escape_awk" "$decoded" >"$escaped_file"; then
-      printf 'session-listen: could not encode body for harness input; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
-      exit 2
+      notify_failure "$(printf 'session-listen dequeued a message it could not deliver, and the queue is at-most-once, so the message is gone from it. Recover it from this line. reason=%s messageId=%s bodyBase64=%s' "encode-failed" "$message_id" "$body64")"
     fi
     if [ -s "$decoded" ] && [ ! -s "$escaped_file" ]; then
-      printf 'session-listen: non-empty body encoded to empty additionalContext; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
-      exit 2
+      notify_failure "$(printf 'session-listen dequeued a message it could not deliver, and the queue is at-most-once, so the message is gone from it. Recover it from this line. reason=%s messageId=%s bodyBase64=%s' "encoded-to-empty" "$message_id" "$body64")"
     fi
     last_byte=$(tail -c 1 "$decoded" | od -An -tx1 | tr -d '[:space:]')
     if ! {
@@ -122,12 +125,10 @@ case "$event" in
       [ "$last_byte" = 0a ] && printf '\\n'
       printf '"}}\n'
     } >"$output_file"; then
-      printf 'session-listen: could not assemble harness input; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
-      exit 2
+      notify_failure "$(printf 'session-listen dequeued a message it could not deliver, and the queue is at-most-once, so the message is gone from it. Recover it from this line. reason=%s messageId=%s bodyBase64=%s' "assemble-failed" "$message_id" "$body64")"
     fi
     if ! cat "$output_file"; then
-      printf 'session-listen: could not emit harness input; messageId=%s bodyBase64=%s\n' "$message_id" "$body64" >&2
-      exit 2
+      notify_failure "$(printf 'session-listen dequeued a message it could not deliver, and the queue is at-most-once, so the message is gone from it. Recover it from this line. reason=%s messageId=%s bodyBase64=%s' "emit-failed" "$message_id" "$body64")"
     fi
     ;;
 esac

package/templates/spec/project/.plugins/core/session-listen/spec.md

@@ -27,6 +27,17 @@ is decoded to a temporary file, validated as UTF-8, and rejected loudly (with it
 toolchain without command substitution, preserving embedded and trailing newlines; a non-empty body can never become
 an empty additionalContext success.
 
+**A delivery failure never costs the person their own prompt.** This hook runs ON prompt submission, so blocking
+is not a way of being loud — it deletes what someone just typed. Two different failures did that. A dequeue that
+errors consumes nothing, and yet the prompt was thrown away for it. And a failure AFTER a successful dequeue had
+already lost the peer message, because the queue is at-most-once; blocking cannot bring it back and only takes a
+second casualty. So every failure inside the delivery path reports itself through the SAME channel the message
+would have used — an `additionalContext` notice, and the same line on stderr — and lets the prompt through. A
+failure before the dequeue says that nothing was consumed and the message is still queued. A failure after it
+carries the `messageId` and the `bodyBase64`, because at that point the notice IS the recovery path. What stays
+blocking is the environment: a configured-but-broken adopter, and the capability probes that run before the
+dequeue precisely so a message is never consumed by a shell that cannot deliver it.
+
 The CLI is resolved at runtime through one explicit seam: a non-empty `SPEX_SESSION_CLI` wins, otherwise PATH is
 searched for `spex-session`. If either protocol database environment variable is configured and no CLI can be
 resolved, the hook fails loudly with an installation or `SPEX_SESSION_CLI` repair entrypoint. With neither database

package/templates/spec/project/.plugins/core/spec-first/spec-first.sh

@@ -1,9 +1,15 @@
 #!/usr/bin/env bash
-# @@@ spec-first - a one-shot governed READ gate. It advances only when the adapter resolves a read path AND
-# the spec graph resolves a real `code:` governor for that path. Irrelevant tools, unresolvable reads, and
-# uncovered/related-only files leave the sentinel absent, so any number of ungoverned reads cannot mute the
-# first later governed read. That read spends the gate and blocks once with its actual governor; retries pass.
-# @@@ event vs matcher - materialized shims bind PreToolUse event-wide on every harness. hp_code_path ... read
+# @@@ spec-first - a one-shot governed ACCESS gate. It advances only when the adapter resolves a path the
+# agent is about to READ OR MUTATE AND the spec graph resolves a real `code:` governor for that path.
+# Irrelevant tools, unresolvable paths, and uncovered/related-only files leave the sentinel absent, so any
+# number of ungoverned touches cannot mute the first later governed one. That touch spends the gate and blocks
+# once with its actual governor; retries pass.
+# @@@ why BOTH read and mutate - this gate has been narrowed twice and both narrowings reopened the same hole
+# from opposite sides. Mutation-only let a pure analysis session reason straight from the code without ever
+# opening the contract; read-only lets a session whose first governed touch is an Edit or Write do the same
+# thing while writing. The rule in [[core]] is read the contract FIRST, and a blind write is its strongest
+# case, so the trigger is any governed access. Narrowing it again needs a reason written down here.
+# @@@ event vs matcher - materialized shims bind PreToolUse event-wide on every harness. hp_code_path ... access
 # is the ONE adapter matcher that reduces Claude/Codex payload differences to a path. This handler owns the
 # harness-agnostic state transition and governor lookup; it has no tool-name, harness, or filename branches.
 # @@@ all sessions, global sentinel - file governance is independent of a record's `governed` bit, so the
@@ -17,7 +23,7 @@ sdir=$(hp_store_dir "$sid") || exit 0
 sent="$sdir/spec-checked"
 [ -f "$sent" ] && exit 0
 
-paths=$(hp_code_path "$payload" read)
+paths=$(hp_code_path "$payload" access)
 [ -n "$paths" ] || exit 0
 repo=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
 
@@ -36,8 +42,15 @@ $paths
 EOF
 [ -n "$owner" ] || exit 0
 
+# @@@ spend the gate only on a demand that was actually made - the sentinel used to be written BEFORE the
+# reason was rendered, so a render failure burned the session's one chance and the agent was never told
+# anything: the gate reported nothing and then stayed silent for the rest of the session. Render first; the
+# sentinel records that a demand reached the agent, not that one was attempted.
+reason=$($S internal hook-prompt spec-first --path "$path" --owner "$owner") || {
+  printf 'spec-first: could not render its demand for %s (%s); leaving the gate armed for the next governed touch\n' "$path" "$owner" >&2
+  exit 0
+}
 mkdir -p "$sdir"; : > "$sent"
-reason=$($S internal hook-prompt spec-first --path "$path" --owner "$owner") || exit 1
 esc=$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g' | awk 'BEGIN{ORS=""} NR>1{print "\\n"} {print}')
 printf '{"decision":"block","reason":"%s"}\n' "$esc"
 exit 0

package/templates/spec/project/.plugins/core/spec-first/spec.md

@@ -8,10 +8,18 @@ events:
 order: 20
 block: true
 ---
-A one-shot, governed-aware READ gate. Its state advances only when the agent is about to read code that has a real governor (`code:` ownership). The first such read creates the session sentinel and blocks once, naming the resolved governing spec and directing the agent through the relevant parent, sibling, and child contracts before retrying. Once that contract-read path has been demanded, later code reads pass.
+A one-shot, governed-aware ACCESS gate. Its state advances only when the agent is about to read OR mutate code that has a real governor (`code:` ownership). The first such touch creates the session sentinel and blocks once, naming the resolved governing spec and directing the agent through the relevant parent, sibling, and child contracts before retrying. Once that contract-read path has been demanded, later code touches pass.
 
-The state machine has no transition for an irrelevant tool, an unresolvable path, or an uncovered/related-only file. In particular, any number of ungoverned reads remain allowed without consuming or muting the gate; a later governed read must still block. This is file governance, distinct from a session record's `governed` field: spec-awareness still serves dashboard-launched and user-self-launched agents alike, with the sentinel created on demand in the session's global store directory.
+The state machine has no transition for an irrelevant tool, an unresolvable path, or an uncovered/related-only file. In particular, any number of ungoverned touches remain allowed without consuming or muting the gate; a later governed one must still block.
 
-Event delivery and semantic matching have separate responsibilities. The hook subscribes to the shared `PreToolUse` lifecycle event because Claude and Codex shims deliver that event broadly. The harness adapter's single `read` matcher decides whether the payload represents a file read and extracts its path; the hook then asks the spec graph whether that path has a governor. Harness payload differences stay inside the adapter, while the gate and its state transitions stay one mechanism.
+**Both halves of access are in the trigger, and the reason is written down because it has been lost twice.** Gating mutation alone let a pure analysis session reason straight from the code without ever opening the contract — the grounding gap. Gating reads alone lets a session whose first governed touch is an Edit or Write do exactly the same thing while writing, which is the same hole entered from the other side and the worse one, since the rule this enforces is read the contract FIRST and a blind write is its strongest case. Narrowing the trigger again requires a stated reason; the governed-awareness above is what keeps it quiet, not the choice of verb. This is file governance, distinct from a session record's `governed` field: spec-awareness still serves dashboard-launched and user-self-launched agents alike, with the sentinel created on demand in the session's global store directory.
+
+**The gate is spent by a demand that reached the agent, not by one that was attempted.** The sentinel used to
+be written before the reason was rendered, so a render failure burned the session's single chance and said
+nothing — the agent was never told, and the gate stayed silent for the rest of the session. The reason is
+rendered first; a failure leaves the gate armed, reports itself on stderr, and lets the touch through, because
+a gate that cannot say what it wants has nothing to demand.
+
+Event delivery and semantic matching have separate responsibilities. The hook subscribes to the shared `PreToolUse` lifecycle event because Claude and Codex shims deliver that event broadly. The harness adapter's single `access` matcher decides whether the payload represents a file read or mutation and extracts its path; the hook then asks the spec graph whether that path has a governor. Harness payload differences stay inside the adapter, while the gate and its state transitions stay one mechanism.
 
 This enforces the read-the-contract-first rule of [[core]] only where a contract actually exists, at the moment before understanding hardens around governed code.

package/templates/spec/project/.plugins/core/stop-gate/spec.md

@@ -8,6 +8,22 @@ events:
 order: 10
 block: true
 ---
+**An artifact is a note ON the demand, not a replacement for it.** The artifact reminder used to be its own
+branch taken INSTEAD of the full menu, with the taught sentinel stamped before it, so a session that had
+posted anything never saw the four states at all. It also looked at files only, while `session web add` writes
+its own store beside them, so a web-only artifact was invisible to the check. The teaching level is chosen
+first — full on the first stop, terse afterwards — and the artifact line is appended to whichever level
+applies, from either store.
+
+**A gate that cannot render its own text still blocks.** Rendering the reason goes through the CLI, and a
+failure there used to exit non-zero — which, for a Stop hook, means ALLOW. The one gate whose entire job is to
+stop an undeclared stop was disarmed by its own text failing to load. It now blocks with a self-contained
+fallback that names the four states without needing the CLI to produce them. Because a genuinely broken CLI
+would also stop the agent from declaring, that fallback blocks at most once per session and then steps aside
+loudly, so failing closed cannot trap anyone. And one escaper serves every emission: the escaping was written
+three times and only one of them folded newlines, so a multi-line reason — a node stack, a git message — put
+raw newlines inside a JSON string and the harness dropped the block entirely.
+
 The blocking stop gate, with two jobs, each holding a hard loop-break so it never blocks twice on the same cause and never lets a dishonest stop through.
 
 The COMMIT gate keeps a done/merge proposal honest: such a proposal is rejected while the branch still carries uncommitted work or is zero commits ahead of main, because the ritual commits the spec and code BEFORE proposing. Clean work is allowed to stop; a dirty proposal blocks once with the reason, and if the agent ignores it the gate escapes by downgrading to `asking` so a false "ready to merge" can never stand. `done --propose nothing` is a porcelain trap, not a declaration: it writes no state and names merge, close, ask, and park as the real destinations; legacy `nothing` records remain readable.

package/templates/spec/project/.plugins/core/stop-gate/stop-gate.sh

@@ -17,6 +17,36 @@
 # CLI read; this shell never treats runtime.json as a second lifecycle database.
 . "${SPEXCODE_HARNESS_LIB:?harness.sh not exported by dispatch.sh}"
 S="${SPEX:-spex}"
+# @@@ the block must survive its own text - three ways a decision was lost. (1) A `hook-prompt` failure exited
+# non-zero, which for a Stop hook means ALLOW: the one gate whose job is to stop an undeclared stop was
+# disarmed by its own text failing to load. (2) The escaping was written three times and only one folded
+# newlines, so a multi-line reason put raw newlines inside a JSON string and the harness dropped the block.
+# (3) `render` must only PRINT — a helper that emits the decision itself cannot be called inside `$( )`,
+# because `exit` there ends the substitution and its output is captured as the caller's text. So rendering
+# returns a status, and every decision is taken in the main shell.
+esc_json() { printf '%s' "$1" | sed 's/\\/\\\\/g; s/"/\\"/g' | awk 'BEGIN{ORS=""} NR>1{print "\\n"} {print}'; }
+block_with() { printf '{"decision":"block","reason":"%s"}\n' "$(esc_json "$1")"; exit 0; }
+render() {
+  local text
+  text=$("$@" 2>/dev/null) || return 1
+  [ -n "$text" ] || return 1
+  printf '%s' "$text"
+}
+# A genuinely broken CLI would also stop the agent from declaring, so the fail-closed fallback blocks at most
+# once per session and then steps aside loudly: failing closed must not trap anyone.
+fallback_or_allow() {
+  local once="$sdir/stop-gate-render-failed"
+  if [ -f "$once" ]; then
+    printf 'stop-gate: cannot render its own reason and has already blocked once for that; allowing this stop. Repair the spex CLI.\n' >&2
+    exit 0
+  fi
+  # the bound only works if the mark can be written: without the mkdir a store dir that does not exist yet
+  # left the sentinel uncreated, and "block at most once" quietly became "block every time"
+  mkdir -p "$sdir" 2>/dev/null || true
+  touch "$once" 2>/dev/null || true
+  block_with "undeclared stop, and stop-gate could not render its own text (the spex CLI failed). Declare the ONE true state as your LAST call: session done --propose merge | done --propose close | ask --note <what you await> | park --note <what you await>. Run it through the same CLI this project launched you with; if that CLI is broken, say so and stop."
+}
+
 input=$(cat 2>/dev/null || true)
 sid=$(hp_session_id "$input"); [ -n "$sid" ] || exit 0
 sdir=$(hp_store_dir "$sid") || exit 0
@@ -89,10 +119,8 @@ if [ "${status:-active}" = awaiting ] && { [ "$proposal" = merge ] || [ "$propos
     $S internal session-state asking --session "$sid" --note "stopped with uncommitted work — commit your spec+code on the node branch, then re-declare done" >/dev/null 2>&1 || true
     exit 0
   fi
-  reason=$($S internal hook-prompt stop-gate --variant commit --reason "$gatemsg" --cli "$S" --propose "$proposal") || exit 1
-  esc=$(printf '%s' "$reason" | sed 's/[\\"]/\\&/g')
-  printf '{"decision":"block","reason":"%s"}\n' "$esc"
-  exit 0
+  reason=$(render $S internal hook-prompt stop-gate --variant commit --reason "$gatemsg" --cli "$S" --propose "$proposal") || fallback_or_allow
+  block_with "$reason"
 fi
 
 # Any other declared state (parked / error / asking / awaiting+close, plus legacy awaiting+nothing) stops.
@@ -117,30 +145,25 @@ fi
 # declare-LAST discipline, and the `help session` entry that re-explains each choice's condition — every bit
 # of the full-to-terse information gap is recoverable from the entry, none of it from memory.
 taught="$sdir/stop-gate-taught"
+# @@@ an artifact is a NOTE ON the demand, not a replacement for it - the artifact line used to be its own
+# branch taken instead of the full menu, and the taught sentinel was stamped before it, so a session that had
+# posted anything never saw the four states at all. It is also not only files: `session web add` writes
+# web.json beside files.json, and checking one of them made a web-only artifact invisible here. So the
+# teaching level is chosen first, and the artifact line is appended to whichever level applies.
+artifact_note=""
+for kind in files web; do
+  store="$sdir/$kind.json"
+  if [ -s "$store" ] && grep -qE '"[^"]+"' "$store"; then
+    artifact_note=$(render $S internal hook-prompt stop-gate --variant artifact --cli "$S") || artifact_note=""
+    break
+  fi
+done
 if [ -f "$taught" ]; then
-  reason=$($S internal hook-prompt stop-gate --variant terse --cli "$S") || exit 1
-  esc=$(printf '%s' "$reason" | sed 's/[\\"]/\\&/g')
-  printf '{"decision":"block","reason":"%s"}\n' "$esc"
-  exit 0
-fi
-touch "$taught" 2>/dev/null || true
-# The full reason names the PATH-independent CLI ($S) ONCE as a shared `<CLI> session <choice>` prefix, then
-# lists the four real states plus the `nothing` trap as a compact newline menu of bare subcommands — so the
-# terminal output stays legible instead of repeating the long abs path per option. It EMPHASIZES that each
-# state is a CLAIM others act on (not a box to tick to end the turn) and gives the precise APPLICATION CONDITION
-# for each — so the agent picks the TRUE one. park is policed hardest because a false park (no real background task) reads on the
-# board as "fine, self-resuming" when the agent actually needs the human, which is the most damaging mislabel.
-# It ends with the ORDERING discipline — declare LAST, then stop — because a declaration followed by more
-# tool calls honestly re-flips the record to active (mark-active, by design) and re-blocks the next stop;
-# this block text is the one place every undeclared stopper is guaranteed to read, so the teaching that
-# kills the park->block->re-park loop at its source lives here.
-if [ -s "$sdir/files.json" ] && grep -qE '"[^"]+"' "$sdir/files.json"; then
-  reason=$($S internal hook-prompt stop-gate --variant artifact) || exit 1
-  esc=$(printf '%s' "$reason" | sed 's/[\\"]/\\&/g')
-  printf '{"decision":"block","reason":"%s"}\n' "$esc"
-  exit 0
+  reason=$(render $S internal hook-prompt stop-gate --variant terse --cli "$S") || fallback_or_allow
+else
+  reason=$(render $S internal hook-prompt stop-gate --variant full --cli "$S") || fallback_or_allow
+  mkdir -p "$sdir" 2>/dev/null || true
+  touch "$taught" 2>/dev/null || true
 fi
-reason=$($S internal hook-prompt stop-gate --variant full --cli "$S") || exit 1
-esc=$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g' | awk 'BEGIN{ORS=""} NR>1{print "\\n"} {print}')
-printf '{"decision":"block","reason":"%s"}\n' "$esc"
-exit 0
+[ -n "$artifact_note" ] && reason=$(printf '%s\n\n%s' "$reason" "$artifact_note")
+block_with "$reason"