release: v3.1.1 — a question no longer burns the session's one triage nudge

The UserPromptSubmit nudge fires at most once per session. The native-mechanism
audit named the consequence precisely and it sat there unfixed: a session whose
first prompt is "what does this do?" spent the reminder on a question, and the
real change request that followed got nothing.

A prompt of at most 200 characters ending in `?` now returns BEFORE the marker is
written — the session stays armed, at the ~9 ms early exit rather than the ~89 ms
eligibility path. The test is deliberately narrow, because "is this a change
request?" is not decidable in a hook: only a SHORT prompt ending in `?` counts, and
a long one that happens to end in `?` is a description with a question attached and
still nudges. The direction of the error is chosen — a missed nudge costs a
reminder, a spent one costs the session's only reminder.

Six regression tests, and the guard was watched failing: removed from a copy of the
hook, exactly three checks go red.

The audit row stays ⚠ and the reason is unchanged: a model that ignores the line
still leaves no triage record, and the Stop gate that would catch that is still off
by default. The reminder got more accurate; it did not become a mechanism.

Also fixes the auto-generated release title, which was the CHANGELOG's date — the
first two releases the repaired gate published on its own both shipped as
"vX.Y.Z — 2026-09-02". Both retitled.

Verified: 8 shell tests (65 native-points checks), shellcheck, lint, lockstep.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: copeus

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers-v",
       "description": "Compound V for Superpowers: triple parallel pre-flight (code archaeology + domain-expert + Context7 library validator), disjoint partitioning, manifest-driven multi-backend dispatch (Claude + Codex + Antigravity + Cursor), git-diff scope enforcement, crash-resumable runs, adaptive tier-based routing, epic mode, research-grounded brainstorming (gated pre-brainstorm recon + batched elicitation), V-memory local-first semantic+lexical recall over docs/superpowers (opt-in pure-python embeddings + a deterministic recall→action bridge), and batched parallel dispatch (Opus default, narrow Sonnet exception)",
-      "version": "3.1.0",
+      "version": "3.1.1",
       "source": "./",
       "author": {
         "name": "Oleg",

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-v",
   "description": "Compound V for Superpowers: triple parallel pre-flight (code archaeology + domain-expert advisor + library/doc validator via Context7), disjoint file partitioning, manifest-driven multi-backend dispatch (Claude + headless Codex + Antigravity + Cursor workers), git-diff scope enforcement, crash-resumable runs, adaptive tier-based routing, epic mode for multi-feature builds, V-memory local-first semantic+lexical recall over docs/superpowers (opt-in pure-python embeddings + a deterministic recall\u2192action bridge), and batched parallel dispatch (Opus default, Sonnet for narrow junior-task carve-out), plus /v:onboard — a project-onboarding command that builds a citation-verified knowledge base + AGENTS.md/CLAUDE.md bridge behind a human gate. Auto-intercepts four transitions: pre-brainstorm recon \u2192 brainstorming \u2192 writing-plans \u2192 execution.",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "author": {
     "name": "Oleg",
     "email": "copeus@gmail.com"

CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to **superpowers-v (Compound V)** are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project uses semantic versioning.
 
+## [3.1.1] - 2026-09-02
+
+### Fixed — a question no longer burns the session's one triage nudge
+
+The `UserPromptSubmit` nudge fires **at most once per session**. The native-mechanism audit named the consequence precisely and it sat there unfixed: a session whose first prompt is *"what does this do?"* spent the reminder on a question, and the real change request that followed got nothing.
+
+A prompt of at most 200 characters ending in `?` now returns **before** the marker is written — the session stays armed, and the cost is the ~9 ms early exit rather than the ~89 ms eligibility path.
+
+The test is deliberately narrow, because "is this a change request?" is not decidable in a hook. Only a *short* prompt ending in `?` counts as a question; a long prompt that happens to end in `?` is a description with a question attached and still nudges. The direction of the error is chosen: a missed nudge costs a reminder, a spent one costs the session's **only** reminder.
+
+Six regression tests, and the guard was watched failing — removed from a copy of the hook, exactly three checks go red. A guard nobody has seen fail is a guard nobody should trust.
+
+**The audit row stays ⚠, and the reason is unchanged:** a model that ignores the line still leaves no triage record at all, and the Stop gate that would catch that is still off by default (`enforcement.triage_gate // false`). The reminder got more accurate. It did not become a mechanism.
+
+### Fixed — the auto-generated release title was a date
+
+The CHANGELOG heading is `## [X.Y.Z] - YYYY-MM-DD`, so the text after the dash is the date. v3.0.6 and v3.1.0 — the first two releases the repaired gate published on its own, and the first two where nobody passed `--title` by hand — both shipped as *"vX.Y.Z — 2026-09-02"*. The title now comes from the entry's first `###` heading, where a release actually names itself, and falls back to no suffix rather than to a date. Both releases retitled.
+
 ## [3.1.0] - 2026-09-02
 
 Three maintainer requirements, set 2026-09-02. Each one turned out to be a mechanism that already existed and was defaulted, named, or gated wrong.

docs/superpowers/architecture/native-mechanisms.md

@@ -15,7 +15,7 @@
 
 | Гарантия | Нативный механизм | Есть? | Исп. 2.x | Исп. 3.0 | Почему своё |
 |---|---|---|---|---|---|
-| Триаж на приходе запроса | `UserPromptSubmit` | ✅ | ❌ | ⚠ | Не смотрели; описательные триггеры срабатывают уже после момента решения. **Понижено с ✅ до ⚠ проверкой по коду 2026-09-01.** Событие занято, но триаж им не обеспечивается: `hooks/triage-prompt-nudge.sh` — это НАПОМИНАНИЕ, и его собственный заголовок говорит это заглавными («никогда не пишет запись, не коммитит и не запускает `/v:triage`», `:27-28`, повторено `:36`). Оно срабатывает **не более одного раза за сессию** (маркер, `:286-309`), так что сессия, чей первый промпт — вопрос, расходует напоминание впустую. Модель, проигнорировавшая строку, не оставляет записи триажа вообще, а Stop-гейт, который поймал бы это, **выключен по умолчанию**: `epic-goal-stop.sh:566` читает `.enforcement.triage_gate // false`. Механически закрыт только путь диспатча — `--require-triage` у валидатора манифеста, — а он срабатывает на `/v:dispatch`, то есть снова ПОСЛЕ момента решения о размере. Ровно тот разрыв, ради которого строка существует |
+| Триаж на приходе запроса | `UserPromptSubmit` | ✅ | ❌ | ⚠ | Не смотрели; описательные триггеры срабатывают уже после момента решения. **Понижено с ✅ до ⚠ проверкой по коду 2026-09-01.** Событие занято, но триаж им не обеспечивается: `hooks/triage-prompt-nudge.sh` — это НАПОМИНАНИЕ, и его собственный заголовок говорит это заглавными («никогда не пишет запись, не коммитит и не запускает `/v:triage`», `:27-28`, повторено `:36`). Оно срабатывает **не более одного раза за сессию** (маркер, `:286-309`), так что сессия, чей первый промпт — вопрос, расходует напоминание впустую. Модель, проигнорировавшая строку, не оставляет записи триажа вообще, а Stop-гейт, который поймал бы это, **выключен по умолчанию**: `epic-goal-stop.sh:566` читает `.enforcement.triage_gate // false`. Механически закрыт только путь диспатча — `--require-triage` у валидатора манифеста, — а он срабатывает на `/v:dispatch`, то есть снова ПОСЛЕ момента решения о размере. Ровно тот разрыв, ради которого строка существует **3.1.1 закрыло одну названную здесь дыру, но не строку целиком.** Напоминание больше не тратится на вопрос: промпт до 200 символов, оканчивающийся на `?`, выходит ДО записи маркера, и сессия остаётся взведённой — тест снимает guard и показывает, что три проверки краснеют, то есть он не декоративен. Оставшаяся причина ⚠ прежняя и механическая: модель, проигнорировавшая строку, не оставляет записи триажа вообще, а Stop-гейт, который поймал бы это, по-прежнему выключен по умолчанию (`enforcement.triage_gate // false`). Напоминание стало точнее; механизмом оно не стало |
 | Решение о размере записано | — | ❌ | ⚠ | ✅ | Движок на 7 883 строки, **артефактов ноль за всю историю** |
 | Полосы файлов объявлены | — | ❌ | ✅ | ✅ | Понятия «полоса» в рантайме нет |
 | Воркер не пишет вне полосы | `PreToolUse` + `permissionDecision: deny` | ✅ | ❌ | ✅ | Проба (`0982ce0`): хук **срабатывает** для агентов воркфлоу и несёт `agent_id`, `agent_type`, `cwd` — вызов атрибутируется конкретному воркеру. Но матчер `Write\|Edit` обходится записью через шелл, поэтому deny **дополняет** git-вердикт, а не заменяет |

hooks/triage-prompt-nudge.sh

@@ -40,6 +40,9 @@
 #   1. the payload parses and is a UserPromptSubmit event
 #   2. the prompt does not begin with `/` (a slash command is an invocation, not
 #      a change request — and `/v:triage` itself is one)
+#   2b. the prompt is not a SHORT QUESTION (<=200 chars ending in `?`). A question
+#      is not a change request, and spending the session's one nudge on it is the
+#      hole the audit named. Skipping here leaves the session ARMED.
 #   3. a `session_id` is present (without it there is nothing to deduplicate on,
 #      and a nudge on every prompt is worse than no nudge)
 #   4. the project looks Compound-V-enabled: `docs/superpowers/` or
@@ -104,7 +107,7 @@
 #
 # COST, measured on the development machine (macOS, /usr/bin/python3, mean of
 # 10 runs against this repository):
-#   early exit (slash command, or the marker already set)   ~9 ms
+#   early exit (slash command, short question, or marker set) ~9 ms
 #   full eligibility path (records scan + resume query)     ~89 ms
 # The full path runs at most once per session — except while a run is active,
 # when no marker is written and conditions 6-7 are re-evaluated on each prompt.
@@ -246,16 +249,21 @@ hook_main() {
     ((.hook_event_name // "") | tostring | gsub("[^A-Za-z]"; "")),
     (((.prompt // "") | tostring)[0:1] | gsub("[^/]"; "")),
     (((.session_id // "") | tostring) | gsub("[^A-Za-z0-9._:-]"; "")),
-    (((.cwd // "") | tostring) | gsub("[\n\r]"; ""))
+    (((.cwd // "") | tostring) | gsub("[\n\r]"; "")),
+    (((.prompt // "") | tostring) | ascii_downcase
+       | gsub("^[[:space:]]+"; "") | gsub("[[:space:]]+$"; "")
+       | if (length > 0 and length <= 200 and (.[-1:] == "?"))
+         then "q" else "" end)
   ' 2>/dev/null)" || return 1
   [ -n "$fields" ] || return 1
 
-  local ev slash sid cwdv
+  local ev slash sid cwdv question
   {
     read -r ev
     read -r slash
     read -r sid
     read -r cwdv
+    read -r question
   } <<EOF
 ${fields}
 EOF
@@ -270,6 +278,26 @@ EOF
   # `/v:status` and `/clear` all arrive here.
   [ -z "${slash:-}" ] || return 1
 
+  # A SHORT QUESTION IS NOT A CHANGE REQUEST, AND MUST NOT SPEND THE NUDGE.
+  #
+  # The nudge is once per session, and the audit named the hole precisely: a
+  # session whose first prompt is "what does this do?" burns the reminder on a
+  # question and the real change request that follows gets nothing. Returning
+  # here — BEFORE the marker is written and before the ~89 ms eligibility path —
+  # leaves the session armed and costs the ~9 ms early exit.
+  #
+  # The test is deliberately narrow, because the general problem (is this a
+  # change request?) is not decidable in a hook: a prompt of at most 200
+  # characters that ENDS IN A QUESTION MARK. Nothing else is treated as a
+  # question. "Rename getUser to fetchUser, ok?" is 33 characters and ends in
+  # `?` and will be skipped — that is the deliberate direction of the error: a
+  # missed nudge costs a reminder, a spent one costs the session's only reminder.
+  # A long prompt that happens to end in `?` is a description with a question
+  # attached, and still nudges.
+  if [ "${question:-}" = "q" ]; then
+    return 1
+  fi
+
   # No session id ⇒ nothing to deduplicate on ⇒ stay silent.
   [ -n "${sid:-}" ] || return 1
 

tests/test-native-points.sh

@@ -169,6 +169,35 @@ check "a second prompt in the SAME session is silent (idempotent)" \
 out3="$(run_nudge sess-B 'rename the config key')"
 check "a different session fires again" "$([ -n "$out3" ] && echo 1 || echo 0)"
 
+# --- 3.1.0: a QUESTION must not spend the session's one nudge -----------------
+# The audit named this hole precisely: the nudge fires at most once per session,
+# so a session whose first prompt is "what does this do?" burned the reminder and
+# the real change request that followed got nothing. A short question now returns
+# BEFORE the marker is written, leaving the session armed.
+q_out="$(run_nudge sess-Q 'what does this do?')"
+check "a short question does not nudge" "$([ -z "$q_out" ] && echo 1 || echo 0)"
+q_after="$(run_nudge sess-Q 'add a retry to the uploader')"
+check "the question did NOT burn the session's nudge" \
+  "$([ -n "$q_after" ] && echo 1 || echo 0)"
+q_third="$(run_nudge sess-Q 'and bump the timeout too')"
+check "the nudge is still once-per-session after a question" \
+  "$([ -z "$q_third" ] && echo 1 || echo 0)"
+markers_before="$(find "$TMPDIR" -name 'nudged-*' 2>/dev/null | wc -l | tr -d ' ')"
+_="$(run_nudge sess-Q2 'why is this failing?')"
+markers_after="$(find "$TMPDIR" -name 'nudged-*' 2>/dev/null | wc -l | tr -d ' ')"
+check "a question leaves NO marker behind (the session stays armed)" \
+  "$([ "$markers_before" = "$markers_after" ] && echo 1 || echo 0)"
+# The test is narrow on purpose: only a SHORT prompt ending in `?` is a question.
+long_q="refactor the pricing module and propagate the new type to every caller, \
+then re-check the callers in the billing package and the reporting package, and \
+make sure the VAT rounding still matches the fixtures, right?"
+lq_out="$(run_nudge sess-LQ "$long_q")"
+check "a long prompt that merely ends in '?' still nudges" \
+  "$([ -n "$lq_out" ] && echo 1 || echo 0)"
+nq_out="$(run_nudge sess-NQ 'rename getUser to fetchUser')"
+check "a plain change request is unaffected" \
+  "$([ -n "$nq_out" ] && echo 1 || echo 0)"
+
 # --------------------------------------------------------------------------- #
 # 2. Exemptions.
 # --------------------------------------------------------------------------- #