@sabaiway/agent-workflow-kit 3.13.0 → 3.14.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 3.14.0 — the closing state block gets a checker (AD-075)
+
+A new opt-in `Stop` hook reads the turn's final assistant message and warns when the closing state
+block lies about the turn that just ended.
+
+Every mechanised bar in this kit gates FILES — the gate declaration, release-scan, doc-parity, the
+commit guard. The closing state block is CHAT output, which no file gate can see, and that is the
+structural reason one contract recurred five times across three sessions while every file-level bar
+held. This closes the gap for two shapes that a `Stop` hook can judge as FALSE rather than merely
+discouraged, because at Stop time the turn is over: a «what I need from you» slot answering
+*nothing* — a turn that has ended always needs a resume, so the slot must name it — and a
+first-person promise of imminent work in a turn that produced none.
+
+**It is detection, never prevention, and that is stated on every surface.** A `Stop` hook cannot
+un-send the message it judges. What it buys is that a recurrence stops being silent.
+
+The warning rides `systemMessage` on stdout at exit 0, because a `Stop` hook's stderr at exit 0
+reaches the debug log and nobody else — a guard warning down an invisible channel would be
+decoration. It never emits a blocking field and exits 0 on every path, including every failure path;
+a guard that cannot see the turn says so rather than going quiet.
+
+The absent-block report is opt-in behind `--require-block`: this kit does not mandate the
+three-part block, and a hook that runs on every turn must not warn on every turn. An unrecognised
+argument refuses the turn loudly instead of silently running weaker than you asked for.
+
+`references/modes/state-block-guard.md` carries the check-first wiring block, the trust posture, and
+every residual by name — including the ones that are limits of a lexical layer rather than bugs
+awaiting a fix. There is **no writer** yet, and the reason is in that doc rather than hidden: a
+second placement path through the gate-approval writer would grow a flag matrix on the component
+that wires command auto-approval, and a dedicated second writer would duplicate hardened placement
+logic.
+
 ## 3.13.0 — the commit guard proves the INDEX carries the verified tree (AD-074)
 
 `commit-guard --check` now refuses an index that lags the working tree, so «verified» and «about to

package/README.md

@@ -248,6 +248,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit velocity` | Claude Code · opt-in | **onboarding velocity profile** — seeds a fixed, audited **read-only** allowlist into `.claude/settings.json` so routine read-only commands stop idling on approval prompts while you're away; opt-in `acceptEdits`; plus a **read-only advisory** of likely project gate commands to add by hand. Writes **only** `.claude/settings.json` — **never** allowlists commit/push/publish, never writes `settings.local.json`, never commits. A seeded entry is a **trust posture, not a sandbox** (a runtime residual remains at the settings level — its guard ships as the opt-in `hook` command); a direct commit/push/publish still asks. `--dry-run` first. |
 | `/agent-workflow-kit agents` | Claude Code · opt-in | **cheap-lane subagents** — places bundled subagent definitions (`.claude/agents/`) pinned to a **cheap model** (haiku, low effort, read-only tools) for mechanical work: extraction sweeps, changelog fact-skeletons, gate-failure triage. Judgment, review, and real code stay on your main lane — these vehicles only extract and draft, and their output is verified. Preview by default (`--apply` writes); an existing customized file is **preserved, never overwritten**; never touches `settings*.json`, never commits. |
 | `/agent-workflow-kit hook` | Claude Code · opt-in | **gate-approval hook** — places a self-contained PreToolUse hook (`.claude/hooks/`) and wires it into `.claude/settings.json`: a Bash command **byte-identical** to a gate you declared in `docs/ai/gates.json` (run from the project root) is auto-approved — no prompt, no idle; a seeded read-only command carrying a runtime residual (output redirection, command substitution, `--output` writes) now **asks** even where an allow rule would have silently passed it (proven live — hook `ask` overrides an allow rule). Exact matches only, never patterns; never `deny`; a broken `gates.json` only disables auto-approval, never the guard. An opt-in **read-lane** (`--read-lane` → `docs/ai/lanes.json`, a **separate** file from `gates.json`) additionally auto-approves *compounds* of seeded read-only commands carrying no shell metaprogramming; `--apply --read-lane` verifies the placed hook is current first (delete-to-reseed otherwise). Preview by default; never writes `settings.local.json`; never commits. |
+| `/agent-workflow-kit state-block-guard` | Claude Code · opt-in | **closing-block detector** — a `Stop` hook that reads the turn's final assistant message and warns when the closing state block is defective: the «what I need from you» slot answering *nothing* (a turn that ENDS always needs a resume, so the answer is false, not merely unhelpful), or a first-person promise of imminent work in a turn that is over. Judged on the slot's first clause, so a real ask followed by a clause break and "nothing else" passes, and a promise gated on something named passes; matching is word-bounded and Unicode-aware, quoted and fenced examples are stripped, and the last STARTED block decides — an incomplete tail counts as no block rather than falling back to an earlier one. A message carrying no block at all is silent unless you pass `--require-block` — this kit does not mandate the block, and a hook that runs every turn must not warn every turn. The judgement is lexical and the mode doc names every residual it leaves. **Detection, never prevention** — a `Stop` hook cannot un-send the message it judges; what it buys is that a silent recurrence becomes a visible one. Warns via `systemMessage` and **exits 0 on every path**: never `deny`, never blocks the stop, never re-enters the model. Reads nothing but the message, makes no network call, approves nothing. This mode is **read-only and has no writer** — it ships the self-contained hook and a paste-ready wiring block you merge into `.claude/settings.json` yourself. |
 | `/agent-workflow-kit bridge-settings` | opt-in, any time | **host-level bridge settings** — read or change the bridges' `KEY=VALUE` config file (`${XDG_CONFIG_HOME:-~/.config}/agent-workflow/bridge-settings.conf`), the **one place a knob survives kit upgrades** (it lives outside every kit tree; a refresh never touches it, and now states loudly if it ever overwrote a local edit). First knobs: the **codex Fast tier** (`CODEX_SERVICE_TIER=priority` — ~1.5× speed at a **2.5× credit rate**, quality-neutral, default off — a consented spend), the codex/agy hard timeouts, the review byte cap, the oversized-review add-dir toggle. Allowed keys + value rules come from the bundled bridge manifests; **model/effort are never settable** (the quality guard is untouched). **Previews by default**; refuses an unknown key, an out-of-range value, or a duplicate-carrying file; writes atomically (symlink/TOCTOU-safe). Never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit autonomy-doctor` | opt-in, any time | **guarded sandbox provisioner "doctor"** — can this machine run the Claude sandbox, and (only with your consent) fix it: macOS Seatbelt built-in / Linux+WSL2 needs `bwrap`+`socat` / native Windows → WSL2. Flagless = **FS-only preview** (the diagnosis, the exact absolute-path command it WOULD run, the exact `--apply <pm>:<pkgs>` consent tuple — runs nothing, never claims ready); `--verify` runs the unprivileged proof (a `bwrap` user-namespace smoke + `socat -V`) — the **only** source of a Linux "ready (verified)" claim; `--apply <pm>:<pkgs>` is the consent-gated privileged install (the tuple must equal the previewed plan; everything executed resolves to absolute paths inside `/usr/bin:/bin:/usr/sbin:/sbin`; the exact command is re-printed immediately before execution), then verifies. Honest loud degrades (unknown PM, untrusted location, nested-sandbox INDETERMINATE, root-unproven) and a stated restart step. Sits **outside every velocity auto-approve tier**; never auto-runs, never writes repo files, never commits. |
 

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '3.13.0'
+  version: '3.14.0'
 ---
 
 # agent-workflow-kit
@@ -159,6 +159,10 @@ writer — read `${CLAUDE_SKILL_DIR}/references/modes/agents.md` before acting.
 
 writer — read `${CLAUDE_SKILL_DIR}/references/modes/hook.md` before acting.
 
+### Mode: state-block-guard
+
+read-only — read `${CLAUDE_SKILL_DIR}/references/modes/state-block-guard.md` before acting.
+
 ### Mode: bridge-settings
 
 guarded — read `${CLAUDE_SKILL_DIR}/references/modes/bridge-settings.md` before acting.

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "3.13.0",
+  "version": "3.14.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/hooks/state-block-guard.mjs

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+// state-block-guard.mjs — the CONTINUATION-STALL detector, wired as a `Stop` hook.
+//
+// Why a hook and not a rule: every mechanised bar in this family gates FILES (the gate declaration,
+// release-scan, doc-parity, the commit guard). The closing state block is CHAT output, which no gate
+// can see — which is exactly why that contract recurred five times while file-level bars held.
+//
+// At Stop time the turn is ENDING. That single fact turns two closing shapes from "discouraged" into
+// FALSE, so they can be judged mechanically:
+//   • the «what I need from you» slot answering "nothing" — a stopped turn always needs a resume, so
+//     the slot must NAME it. "Nothing needed" is honest only while work is actually running;
+//   • a first-person promise of imminent work in the closing block — the turn is over, so the work
+//     is not starting. This is the announce-and-stop shape.
+// A promise GATED on something named (after your yes, when CI finishes) is honest and passes.
+//
+// The judgement is LEXICAL, and that is a layer with limits rather than a temporary weakness: it
+// approximates "this condition gates that promise" by token order, and it can neither recognise a
+// freshly invented wording for "nothing needed" nor parse a sentence. Where a rule to close one edge
+// required a second classifier to decide what counts as a real ask, the rule was DELETED and its
+// residual written down instead — twice. The mode contract lists every residual by name.
+//
+// HONEST LIMIT, stated because it bounds what this can claim: a Stop hook cannot un-send the turn it
+// judges. This is DETECTION — it converts a silent recurrence into a loud one. It never blocks, and
+// every anomaly path exits 0: a hook that fires on every turn must not become the blocker or the
+// noise. Self-contained by contract (a placed copy runs on machines without the kit): no imports
+// beyond node built-ins, dependency-free, Node >= 22, no side effects on import.
+//
+// THE CHANNEL IS PART OF THE CONTRACT. At exit 0 a Stop hook's stderr reaches the debug log and
+// nobody else; the one user-visible lane is JSON on stdout carrying `systemMessage`. So the warning
+// rides that field — a guard warning down an invisible channel would be decoration. The blocking
+// fields (`decision`, `continue`, `stopReason`, `hookSpecificOutput`) are deliberately never emitted:
+// blocking the stop would re-enter the model on a message already sent to the reader.
+
+import { pathToFileURL } from 'node:url';
+
+export const HOOK_EVENT_NAME = 'Stop';
+const EXIT_OK = 0;
+
+// The three slots, matched on their LABEL and ANCHORED TO A LINE START. The anchor is not cosmetic:
+// a message that DISCUSSES this contract — which the sessions this guard was built for do constantly
+// — mentions the labels inline, and an unanchored match would judge that prose instead of the real
+// closing block. Russian is the dialogue language this contract was written for; the English twins
+// keep the guard usable in an English-dialogue deployment.
+const LINE_LEAD = '^[ \\t\\-•]*';
+const SLOT_PATTERNS = Object.freeze({
+  now: new RegExp(`${LINE_LEAD}(?:что сейчас|where we are|state now)\\s*[:：]`, 'gim'),
+  fromYou: new RegExp(`${LINE_LEAD}(?:что нужно от вас|что от вас|what i need from you|from you)\\s*[:：]`, 'gim'),
+  next: new RegExp(`${LINE_LEAD}(?:что дальше|what(?:'s| is)? next|next)\\s*[:：]`, 'gim'),
+});
+
+// Quoted and fenced material is EXAMPLE text, not the turn's own closing block. Stripped before any
+// label search — otherwise pasting the very specimen this guard catches would make the guard judge
+// the paste. Emphasis marks are stripped after, so `**Что сейчас:**` still parses.
+// Scanned line by line rather than matched as one regex: an UNCLOSED fence must run to the end of
+// the message. A pattern that only removes CLOSED fences would take an unfinished example's labels
+// for a real block — judging a demonstration as if it were the turn, which is precisely the mistake
+// this stripper exists to prevent. A closing fence must be at least as long as its opener and carry
+// nothing but whitespace after it.
+const FENCE_OPEN = /^[ \t]*(`{3,}|~{3,})/;
+// The trailing `\r` is not an edge case: the text is split on `\n`, so on a CRLF host EVERY line
+// ends in one. A close pattern that forbids it leaves every fence open, the stripper swallows the
+// real closing block, and the guard goes blind on that whole platform — silently.
+const FENCE_CLOSE = /^[ \t]*(`{3,}|~{3,})[ \t\r]*$/;
+const closesFence = (line, open) => {
+  const close = line.match(FENCE_CLOSE);
+  return close !== null && close[1][0] === open[0] && close[1].length >= open.length;
+};
+// One pass, appending in place. A reduce that rebuilt the kept array per line was quadratic in the
+// message length, and this hook runs on EVERY turn end under a documented 10-second timeout.
+const stripFences = (text) => {
+  const kept = [];
+  const state = { open: null };
+  for (const line of text.split('\n')) {
+    if (state.open !== null) {
+      if (closesFence(line, state.open)) state.open = null;
+      continue;
+    }
+    const opened = line.match(FENCE_OPEN);
+    if (opened === null) kept.push(line);
+    else state.open = opened[1];
+  }
+  return kept.join('\n');
+};
+
+const BLOCKQUOTE_LINE = /^[ \t]*>.*$/gm;
+const EMPHASIS_MARKS = /[*_`]/g;
+// A model writes «What’s next» and «I’ll» with a typographic apostrophe far more often than with the
+// ASCII one, so matching only ASCII made the English half fail silently on ordinary output.
+const APOSTROPHES = /[’‘ʼ‛]/g;
+const toProse = (text) => stripFences(text)
+  .replace(BLOCKQUOTE_LINE, '')
+  .replace(EMPHASIS_MARKS, '')
+  .replace(APOSTROPHES, "'");
+
+// A "nothing" answer, judged ONLY over the slot's FIRST CLAUSE — the answer proper. A slot that
+// names a real ask and then adds "nothing else is needed" is honest and must stay passing, or the
+// contract becomes unwritable. A dot ends a clause only before whitespace or the end of the slot:
+// `README.md` is a file name, and treating its dot as a sentence end both hid banned forms behind a
+// short prefix and split honest sentences in half. There is no character cap — a cap decides where
+// an answer ends by counting, and a long preamble would carry a banned form past it unseen.
+const CLAUSE_END = /;|[.!?](?=\s|$)/;
+const openingAnswer = (slot) => {
+  const at = slot.search(CLAUSE_END);
+  return at === -1 ? slot : slot.slice(0, at);
+};
+// A rule excusing «…, ничего другого не нужно» was built, tightened twice, and then DELETED. Every
+// version let a banned answer through behind some harmless prefix, and the next version would have
+// needed an "is this a real ask" recogniser — a second lexical classifier with its own edge set. The
+// residual is stated instead of coded: a comma-joined qualifier IS flagged, and the writer's fix is
+// a clause break, which the first-clause rule already passes.
+
+const NOTHING_FORMS = Object.freeze([
+  'ничего',
+  'ничем',
+  'не требуется',
+  'не нужно',
+  'не нужен',
+  'нет необходимости',
+  'nothing',
+  'none',
+  'n/a',
+  'no action',
+]);
+
+// First-person promises of imminent work. Present tense counts: at Stop it describes work that is
+// NOT running.
+// Action verbs only. «считаю» and «смотрю» were dropped rather than qualified: they are as often
+// stative («считаю задачу завершённой», «смотрю на вопрос как на закрытый») as they are promises, and
+// a form that cannot tell the two apart buys detection with false flags.
+// The English markers are pronoun+modal rather than action verbs, so they cannot tell «I'll start» from
+// «I'll wait». Waiting is not work: it is what a turn that ENDS actually does, and it needs no gate to
+// be honest. So a modal followed by a waiting verb is excluded rather than the modal being dropped —
+// dropping it would need an open-ended list of every action verb English can put after it.
+const WAITING_CONTINUATIONS = Object.freeze([
+  "i'll wait", 'i will wait', "i'll be waiting", "i'll stand by", 'i will stand by',
+  "i'll hold", 'i will hold', "i'll stay", 'i will stay', "i'll remain", 'i will remain',
+]);
+
+const PROMISE_FORMS = Object.freeze([
+  'беру', 'начинаю', 'перехожу', 'сажусь', 'продолжаю', 'иду', 'проверяю', 'пишу', 'строю',
+  'планирую', 'разбираюсь',
+  "i'll", 'i will', "i'm going to", 'i am going to', 'i start', 'i begin', 'next i',
+]);
+
+// A gate the promise may depend on. What is actually checked is TOKEN ORDER inside one segment: a
+// gate is treated as excusing a promise when it appears in the same segment and earlier in it. That
+// is a lexical approximation of dependency, not dependency itself, and it carries two named
+// residuals — an honest TRAILING gate («беру, когда вы скажете») is flagged, and a gate belonging to
+// an earlier comma-clause («если тест упадёт, сообщу, а сейчас начинаю…») wrongly excuses a promise
+// that follows it. Both are accepted limits of a lexical layer, documented in the mode contract.
+const CONDITIONAL_FORMS = Object.freeze([
+  'после', 'когда', 'если', 'как только',
+  'after', 'when', 'if', 'as soon as', 'once', 'pending',
+]);
+
+// Segment boundaries for the promise/gate rule. Deliberately NOT the comma: «если вы согласны, беру
+// класс» is one honest thought, and splitting it would flag the shape the rule exists to permit.
+const PROMISE_SEGMENT_BREAK = /;|\n|[.!?](?=\s|$)/;
+
+// Word-bounded matching, Unicode-aware. JavaScript's `\b` is ASCII-only and therefore useless here:
+// with raw substring matching «не нужно» hides inside the honest «мне нужно ваше подтверждение»
+// («м|не нужно»), so the most natural way to name a real ask was read as answering "nothing".
+// The trailing exclusion covers the interrogative particle: «не нужно ЛИ добавить тест» asks a
+// question, it does not decline help.
+const WORD_CHAR = '\\p{L}\\p{N}';
+const escapeForRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
+const boundedPattern = (phrase) => new RegExp(
+  `(?<![${WORD_CHAR}])${escapeForRegExp(phrase)}(?![${WORD_CHAR}])(?!\\s+ли(?![${WORD_CHAR}]))`,
+  'iu',
+);
+const firstMatchAt = (haystack, needles) => needles.reduce((best, needle) => {
+  const at = haystack.search(boundedPattern(needle));
+  if (at === -1) return best;
+  return best === -1 ? at : Math.min(best, at);
+}, -1);
+const containsAny = (haystack, needles) => firstMatchAt(haystack, needles) !== -1;
+
+const normalise = (value) => (typeof value === 'string'
+  ? value.replace(EMPHASIS_MARKS, '').replace(APOSTROPHES, "'").toLowerCase()
+  : '');
+
+const SLOT_COUNT = Object.keys(SLOT_PATTERNS).length;
+
+const collectLabels = (prose) => Object.entries(SLOT_PATTERNS)
+  .flatMap(([slot, pattern]) => [...prose.matchAll(pattern)]
+    .map((match) => ({ slot, start: match.index, bodyAt: match.index + match[0].length })))
+  .sort((a, b) => a.start - b.start);
+
+// Labels are grouped into candidate BLOCKS rather than picked per slot: picking each slot's last
+// occurrence independently splices a trailing incomplete block onto an earlier one and fabricates a
+// block nobody wrote. A repeated slot abandons the candidate and RESTARTS it at that label, because
+// the repeat is itself the plausible first label of a new block.
+const groupLabels = (labels) => labels.reduce((state, label) => {
+  const candidate = state.current.some((held) => held.slot === label.slot) ? [label] : [...state.current, label];
+  return candidate.length === SLOT_COUNT
+    ? { current: [], completed: candidate }
+    : { current: candidate, completed: state.completed };
+}, { current: [], completed: null });
+
+// findStateBlock(text) → { now, fromYou, next } or null. The LAST STARTED candidate decides: if the
+// message ends mid-block, the turn did not end on a block at all, and falling back to an earlier
+// complete one would judge text the turn already moved past.
+export const findStateBlock = (text) => {
+  if (typeof text !== 'string' || text.trim() === '') return null;
+  const prose = toProse(text);
+  const { current, completed } = groupLabels(collectLabels(prose));
+  if (current.length > 0 || completed === null) return null;
+  const block = {};
+  completed.forEach((entry, index) => {
+    const end = index + 1 < completed.length ? completed[index + 1].start : prose.length;
+    block[entry.slot] = prose.slice(entry.bodyAt, end).trim();
+  });
+  return block;
+};
+
+// decideStop({ closingText, requireBlock }) → { ok, reasons }. Never throws: junk input decides
+// "no block", which is a reportable state rather than a crash. An ABSENT block is reported only
+// under `requireBlock`: this kit does not mandate the three-part block, so warning about its absence
+// by default would fire on nearly every turn of a project that never adopted it — noise, from a hook
+// that runs on every single turn.
+export const decideStop = (options) => {
+  const { closingText, requireBlock = false } = options ?? {};
+  const block = findStateBlock(closingText);
+  if (block === null) {
+    return requireBlock
+      ? {
+        ok: false,
+        reasons: ['no state block: the closing message must end with «что сейчас · что нужно от вас · что дальше»'],
+      }
+      : { ok: true, reasons: [] };
+  }
+  const reasons = [];
+  const answer = openingAnswer(normalise(block.fromYou));
+  if (answer.trim() === '' || containsAny(answer, NOTHING_FORMS)) {
+    reasons.push(
+      'from-you slot answers "nothing": the turn is ENDING, so a resume from the maintainer IS required — name the real unblocker instead',
+    );
+  }
+  if (hasUngatedPromise(normalise(block.next))) {
+    reasons.push(
+      'announce-and-stop: the what-next slot promises imminent first-person work while the turn ends — either do it in this turn, or state what the work waits on',
+    );
+  }
+  return { ok: reasons.length === 0, reasons };
+};
+
+const hasUngatedPromise = (nextSlot) => nextSlot.split(PROMISE_SEGMENT_BREAK).some((segment) => {
+  const promiseAt = firstMatchAt(segment, PROMISE_FORMS);
+  if (promiseAt === -1) return false;
+  if (containsAny(segment, WAITING_CONTINUATIONS)) return false;
+  const gateAt = firstMatchAt(segment, CONDITIONAL_FORMS);
+  return !(gateAt !== -1 && gateAt < promiseAt);
+});
+
+// "Exit 0 on every path" and "say nothing on every path" are DIFFERENT promises, and only the first
+// was ever earned. A guard that cannot see the turn is BLIND, which is a real failure, and this
+// family forbids silent ones — so a failure is reported like any other finding. Having nothing to
+// judge is not a failure and stays silent: a hook that fires every turn would otherwise warn every
+// turn on a host that simply delivers no closing text.
+// A FAILURE and a FINDING are different claims and must not share a headline: reporting "the closing
+// state block is defective" when no block was ever read would blame the writer for the guard's own
+// blindness.
+export const FAILURE = 'failure';
+export const FINDING = 'finding';
+const guardFailure = (detail) => ({ ok: false, kind: FAILURE, reasons: [detail] });
+
+const parsePayload = (rawInput) => {
+  try {
+    return { input: JSON.parse(rawInput) };
+  } catch (error) {
+    return { error: `the Stop payload could not be parsed as JSON (${error.message})` };
+  }
+};
+
+// An ABSENT field means the host delivers nothing (silent, above). A PRESENT field of the wrong type
+// is a CORRUPT payload and is reported — the two are only indistinguishable if you never look.
+//
+// `last_assistant_message` is the ONLY source. A transcript fallback was built and then DELETED: the
+// transcript file is written asynchronously, so a lagging one can END on the previous turn's
+// assistant entry with nothing after it, and no tail check can tell that apart from the current
+// turn. A fallback that can be confidently wrong about WHICH TURN it read is worse than no fallback,
+// because being confidently wrong is the one failure a detector must not have. A host that does not
+// deliver the field therefore gets no detection — stated in the mode contract, and silent rather
+// than warning on every single turn.
+//
+// An EMPTY string is delivered text, not an absent one: a turn that ended with no prose really did
+// end without a closing block, and `--require-block` should be able to say so.
+// runHook(raw, {requireBlock}) → a decision, or null when there is genuinely nothing to judge.
+// Never throws.
+export const runHook = (rawInput, deps) => {
+  const requireBlock = (deps ?? {}).requireBlock === true;
+  const parsed = parsePayload(rawInput);
+  if (parsed.error !== undefined) return guardFailure(parsed.error);
+  const input = parsed.input;
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    return guardFailure('the Stop payload is not a JSON object');
+  }
+  if (!Object.prototype.hasOwnProperty.call(input, 'last_assistant_message')) return null;
+  const delivered = input.last_assistant_message;
+  if (typeof delivered !== 'string') {
+    return guardFailure(`the payload's last_assistant_message is ${delivered === null ? 'null' : typeof delivered}, not a string`);
+  }
+  return decideStop({ closingText: delivered, requireBlock });
+};
+
+// The stream is a parameter so the read path itself is exercisable, not just its caller.
+export const readStdin = async (stream = process.stdin) => {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(chunk);
+  return Buffer.concat(chunks).toString('utf8');
+};
+
+const FINDING_HEADER = 'state-block-guard — the closing state block is defective (CONTINUATION-STALL):';
+const FAILURE_HEADER = 'state-block-guard — this turn was NOT judged; the guard could not see it:';
+const formatWarning = (decision) => [
+  decision.kind === FAILURE ? FAILURE_HEADER : FINDING_HEADER,
+  ...decision.reasons.map((reason) => `• ${reason}`),
+].join('\n');
+
+// The ONE flag. A misspelling must never be read as "run in the default mode": that would silently
+// downgrade the strictness the user deliberately opted into, which is the failure an opt-in must not
+// have. So an unrecognised argument refuses the turn's judgement LOUDLY — and still exits 0.
+export const REQUIRE_BLOCK_FLAG = '--require-block';
+export const parseArgs = (argv = []) => ({
+  requireBlock: argv.includes(REQUIRE_BLOCK_FLAG),
+  unknown: argv.filter((arg) => arg !== REQUIRE_BLOCK_FLAG),
+});
+
+export const main = async ({
+  argv = process.argv.slice(2),
+  readInput = readStdin,
+  write = (line) => process.stdout.write(line),
+} = {}) => {
+  // Exit 0 on EVERY path, always. This guard reports; it is never the thing that stops a session.
+  try {
+    const { requireBlock, unknown } = parseArgs(argv);
+    if (unknown.length > 0) {
+      write(`${JSON.stringify({
+        systemMessage: `state-block-guard: unrecognised argument ${unknown.join(' ')} — refusing to judge this turn rather than silently falling back to the default mode; ${REQUIRE_BLOCK_FLAG} is the only argument accepted`,
+      })}\n`);
+      return EXIT_OK;
+    }
+    const decision = runHook(await readInput(), { requireBlock });
+    if (decision !== null && decision.ok === false) {
+      write(`${JSON.stringify({ systemMessage: formatWarning(decision) })}\n`);
+    }
+  } catch (error) {
+    // Never silent, never fatal: the failure is reported and the exit code stays 0.
+    try {
+      write(`${JSON.stringify({
+        systemMessage: formatWarning({ kind: FAILURE, reasons: [error?.message ?? String(error)] }),
+      })}\n`);
+    } catch {
+      // The reporting channel itself is gone; there is nowhere left to report it to.
+    }
+  }
+  return EXIT_OK;
+};
+
+// `process.exitCode`, never `process.exit()`: an immediate exit can truncate a pending stdout write
+// to a pipe, and that single warning is the entire product of this hook.
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) main().then((code) => { process.exitCode = code; });

package/references/modes/hook.md

@@ -5,7 +5,7 @@ The opt-in **gate-approval PreToolUse hook** — the family's third `.claude/` w
 - **Auto-approve** a command **byte-identical** (leading/trailing trim only — no whitespace collapsing, no quote/glob/variable interpretation, no prefix or pattern matching, ever: patterns are what made AD-021 auto-seeding rejected) to a gate `cmd` declared in `docs/ai/gates.json` — read **LIVE on every call** (editing gates.json never needs re-wiring; one declaration, two consumers with `${CLAUDE_SKILL_DIR}/references/modes/gates.md`) — invoked **from the project root** (gates run from the root by contract; the same bytes from a subdirectory are NOT approved) and under `default`/`acceptEdits` permission mode (an approval never loosens `plan`/`bypassPermissions`).
 - **Ask** on a command whose leading tokens match the velocity **seeded read-only core** when it carries the documented runtime residual — output redirection, command substitution, or the bounded `--output` write-flag family — surfacing a human prompt even where a seeded allow rule would have silently approved (**hook `ask` overrides an allow rule — proven live**: on Claude Code 2.1.185 a seeded `Bash(git log:*)` silently wrote a file via `git log --output=…`; with the hook wired the same call prompts). Detection is string-level and conservative: a quoted metacharacter may over-ask, never under-allow.
 - **Auto-approve a read-only COMPOUND** (opt-in — dark unless enabled): when `docs/ai/lanes.json` sets `{ "readLane": true }` (read **LIVE on every call**), a command whose EVERY separator-split segment is a plain seeded read-only core command, carrying **zero shell metaprogramming** anywhere (no `$`/expansion, quoting, backslash, brace, glob, redirection, substitution, `--output`, env-assignment prefix, or backgrounding), is auto-approved — a conservative **closed-world** allow (any doubt falls through, never a widening). Mode-fenced like gate auto-approval; **cwd-agnostic** (a read is a read from any directory). It runs AFTER the residual ask, so a core command that carries a residual still prompts (most-restrictive-wins). The lane is **bounded by the frozen audited read-only core** (the set velocity seeds) — a **standalone opt-in grant**, never a command OUTSIDE that audited core; enabling it auto-approves compounds (and singles) of that audited core **regardless of which of those commands you seeded** as individual settings rules (that is the trust the opt-in consent covers — not strictly a subset of your current settings).
-- **Stay silent otherwise** — the normal permission flow proceeds unchanged. The hook **never emits `deny`**; nothing is hard-blocked.
+- **Stay silent otherwise** — the normal permission flow proceeds unchanged. The gate-approval hook **never emits `deny`**; nothing is hard-blocked.
 
 **Honest residual status (AD-037):** current engine builds already intercept `>` redirection and `$()` substitution upstream (observed headless on 2.1.185); the **`--output` family was proven open** and is the seam this hook demonstrably closes. The guard still covers all three documented classes (defense-in-depth — engine behavior may vary across surfaces/versions). **Fail-safe, decoupled:** a missing/broken/invalid `gates.json` disables ONLY gate auto-approval — the residual guard keeps running; every anomaly path exits 0 (the hook is never the blocker or the noise — the `gates` runner reports a broken declaration at its own point of use). **Not a sandbox:** it closes the named residual for the seeded core and auto-approves declared gates; it does not police arbitrary commands or user-added rules.
 
@@ -27,3 +27,5 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/gate-hook.mjs [--dry-run | --apply] [--cwd <
 **Invariants:** the base flow writes ONLY `.claude/hooks/agent-workflow-gates.mjs` + `.claude/settings.json`; `--read-lane` writes ONLY `docs/ai/lanes.json` (never settings, never `gates.json`) · never `settings.local.json` · never commits · exact-match approval only (no patterns) · never `deny` · never auto-wired by `init`/`upgrade` (placement stays opt-in — the AD-011/AD-034 boundary: init/upgrade may refresh placed things, never place new ones).
 
 **Exit codes:** `0` done / dry-run (incl. the reported diverged-but-wired state); `1` a precondition STOP; `2` bad arguments.
+
+**The kit's other hook.** `state-block-guard` (see `${CLAUDE_SKILL_DIR}/references/modes/state-block-guard.md`) is a separate, unrelated `Stop` hook that judges the closing state block of a turn. It has no writer (you paste its wiring), it never approves or denies anything, and nothing here places or wires it — the two hooks share only the `.claude/` directory they live in.

package/references/modes/state-block-guard.md

@@ -0,0 +1,188 @@
+### Mode: state-block-guard
+
+The opt-in **closing-state-block detector**, wired as a Claude Code `Stop` hook. It ships as a
+**self-contained** runtime at `references/hooks/state-block-guard.mjs` (no kit imports — a placed
+copy keeps working if the kit is uninstalled) and it **writes nothing**: this mode is read-only, and
+the wiring is yours to paste (see *No writer yet*, below).
+
+**Read this first — what it is and is not.** A `Stop` hook runs when a turn has already ENDED, so it
+**cannot un-send the message it judges**. This is **DETECTION, not prevention**. What it buys is
+exactly one thing, and the thing is worth a release: a defect that previously depended on a human
+re-reading every closing message becomes an immediate, visible warning. Any surface that describes
+this as preventing the defect is describing it wrongly.
+
+**What it detects.** Two shapes, both of which are not merely *discouraged* at Stop time but
+**provably false** — which is what makes them mechanically judgeable at all:
+
+- **The «what I need from you» slot answering "nothing".** A turn that ends is by definition idle, so
+  a resume from the reader IS required; a slot saying otherwise states something untrue. Judged over
+  the slot's **first clause only** — a slot that names a real ask and then, after a `;` or a full
+  stop, adds «ничего другого не нужно» is honest and passes. A COMMA does not open a new clause, so
+  the comma-joined version of that sentence is flagged; see the residuals. Hedged forms count: «не
+  требуется», «ваше присутствие не требуется прямо сейчас», «nothing right now», «n/a».
+- **Announce-and-stop.** The «what next» slot promising first-person imminent work («беру…»,
+  «начинаю…», «I'll start…») while the turn ends. A promise **gated on something named** («после
+  вашего да — беру…», «once CI finishes…») states a dependency instead of a false start, and passes.
+
+**A message with no recognisable block at all is SILENT by default.** This kit does not mandate the
+three-part closing block — it is a per-project dialogue contract — so warning whenever a block is
+absent would fire on nearly every turn of a project that never adopted it, and a hook that runs on
+every single turn must not become that noise. Pass `--require-block` in the wiring to turn the
+absent-block report on; the honest residual of the default is stated plainly below.
+
+**What it does NOT judge.** Quoted material (`>` lines) and fenced code blocks are stripped before
+anything is matched, and each slot label must start its own line. Otherwise a message that *discusses*
+this contract — pasting the very specimen the guard catches — would be judged on the paste instead of
+its own closing block. Labels are then grouped into whole blocks — never picked one slot at a time,
+which would splice a stray trailing label onto an earlier block and judge a block nobody wrote. The
+**last started** group decides: if the message ends mid-block, the turn did not end on a block at
+all, and `--require-block` says so rather than falling back to an earlier one the turn had moved past.
+
+**How it reports (the channel is part of the contract).** At exit 0 a `Stop` hook's **stderr goes to
+the debug log and is seen by nobody**; the one user-visible lane is JSON on stdout carrying
+`systemMessage`. The guard emits exactly that:
+
+```json
+{"systemMessage": "state-block-guard — the closing state block is defective (CONTINUATION-STALL):\n• …"}
+```
+
+The same channel carries FAILURES, under their own headline — reporting «the closing state block is
+defective» when no block was ever read would blame the writer for the guard's own blindness.
+«Exit 0 on every path» and «say nothing on every path» are different promises, and only the first is
+kept: if the guard cannot see the turn — the payload will not parse, is not a JSON object, or
+carries a `last_assistant_message` that is present but not a string — it is blind, and it says so
+instead of going quiet. An ABSENT field is different: that is a host delivering nothing, and it stays
+silent.
+
+It **never** emits `decision`, `continue`, `stopReason`, or `hookSpecificOutput`, and it **exits 0 on
+every path** — including every failure path. A hook that runs on every single turn must never become
+the blocker or the noise. Blocking the stop would re-enter the model on a message the reader has
+already seen, which is not what a detector is for; the payload does carry `stop_hook_active`, so a
+future intervening variant has the loop guard it would need, but that variant is deliberately not
+this one.
+
+**Where it reads the closing message — one source, deliberately.** The `last_assistant_message` field
+of the `Stop` payload, and nothing else. A `transcript_path` fallback was built and then **removed**:
+the transcript file is written asynchronously, so a lagging one can END on the previous turn's
+assistant entry with nothing after it, and no check on the file can tell that apart from the current
+turn. A fallback that may be confidently wrong about WHICH TURN it read is worse than no fallback,
+because being confidently wrong is the single failure a detector must not have.
+
+The consequence is stated rather than hidden: **a host that does not deliver `last_assistant_message`
+gets no detection at all**, silently — not a warning on every turn, which is what a host-shaped
+condition would produce. An EMPTY delivered message is different: it is text, so a turn that ended
+with no prose is judged as having no block, which `--require-block` will report.
+
+**Language.** The slot labels and both banned sets carry Russian and English twins, because the
+contract this enforces was written for a Russian-dialogue deployment. A deployment in another
+dialogue language gets no detection until its labels are added — that is a real limit, not a
+configuration you can set today.
+
+**No writer yet — and why, plainly.** Every other placed thing in this kit arrives through a
+consent-gated writer. This one does not, deliberately:
+
+- extending the gate-approval writer (`tools/gate-hook.mjs`) would grow a second placement path
+  through the family's **highest-blast-radius** component — the one that wires command
+  auto-approval — for the benefit of a detector;
+- a second dedicated writer would duplicate that writer's hardened placement discipline (symlink
+  refusal, malformed-settings refusal, unknown-script refusal, merge-don't-clobber), which this
+  project's own DRY rule forbids.
+
+The wiring is eight lines of JSON, and hand-editing `settings.json` from a paste-ready block is the
+form this family already sanctions. When the detector has earned a writer in real use, it gets one.
+
+**Wiring it (paste-ready, two steps).**
+
+1. Copy the runtime into your project (it is self-contained; the copy keeps working without the kit).
+   **Check before you copy** — this is a plain copy, not a guarded writer, so the safety is yours:
+
+   ```
+   ls -ld .claude .claude/hooks
+   ls -l .claude/hooks/state-block-guard.mjs
+   ```
+
+   Stop if `.claude` or `.claude/hooks` is a **symlink** (a copy would write through it to somewhere
+   you did not choose), and stop if the target already exists — including a dangling symlink. Only
+   then:
+
+   ```
+   mkdir -p .claude/hooks
+   cp "${CLAUDE_SKILL_DIR}/references/hooks/state-block-guard.mjs" .claude/hooks/state-block-guard.mjs
+   ```
+
+   To UPDATE an existing copy, `diff` it against the bundled file first and replace it deliberately.
+   No `cp` flag makes this safe for you: `-n` is not portable in the same way everywhere, and none of
+   them refuse a symlinked parent directory.
+
+2. Merge this into `.claude/settings.json` — **merge, do not clobber.** Three cases, and getting the
+   third wrong silently disables someone else's hook:
+   - no `hooks` key → add the whole object below;
+   - a `hooks` key WITHOUT `Stop` (for example only the gate-approval `PreToolUse` entry) → add the
+     `Stop` key beside it;
+   - a `hooks.Stop` array that ALREADY EXISTS → **append one element to that array**, never replace
+     it and never write a second `Stop` key. If `hooks.Stop` is present but is not an array, stop and
+     fix that by hand first — pasting into it would destroy whatever is there.
+
+   ```json
+   {
+     "hooks": {
+       "Stop": [
+         {
+           "hooks": [
+             {
+               "type": "command",
+               "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state-block-guard.mjs\" --require-block",
+               "timeout": 10
+             }
+           ]
+         }
+       ]
+     }
+   }
+   ```
+
+Drop `--require-block` if your project has not adopted the three-part closing block and you only want
+the two lying-slot checks. `--require-block` is the **only** argument accepted: an unrecognised one
+makes the guard refuse to judge the turn and say so, rather than quietly running in the weaker mode
+you did not choose.
+
+A `Stop` hook is read at session start, so it becomes live in the **next** session, not the current
+one.
+
+**Trust posture (state it plainly when asking consent):** the guard reads the closing assistant
+message of each turn and writes one warning line. It runs a Node process on every turn end, it does
+not read your repository, it makes no network call, and it can approve nothing — its blast radius is
+the warning text. It is not a sandbox and not a permission control.
+
+**Honest residuals:**
+
+- **Detection, not prevention** — restated because it is the one thing that must not blur.
+- **The judgement is LEXICAL, and that is a layer with limits, not a temporary weakness.** It matches
+  slot labels and phrase sets on Unicode-aware word boundaries, so an honest «мне нужно ваше
+  подтверждение» is not read as «не нужно» and an interrogative «не нужно ли…» is not read as a
+  refusal. It cannot parse a sentence, and it cannot recognise a wording it has never been told
+  about. Two rules that tried to close an edge here were **deleted rather than tightened a third
+  time**, because each next version needed a second classifier — the residuals below are what
+  replaced them. A named specimen of the cost: «подтвердите, что ничего не упущено» is a real ask
+  and is FLAGGED, because the banned word sits inside it. Phrase the ask without the word.
+- **A comma-joined qualifier is flagged.** «одно да, ничего другого не нужно» warns; the same
+  sentence with a `;` or a full stop passes. The rule that tried to exempt the comma form kept
+  letting a real "nothing" through behind a harmless prefix, so it was removed and the false flag is
+  accepted instead. It costs one line and names its own fix.
+- **A condition is bound to a promise by TOKEN ORDER inside one segment, which is an approximation.**
+  «после вашего да — беру класс» passes; «беру класс, а если тест упадёт, сообщу» is flagged. Two
+  known misreadings follow from the approximation, both accepted: an honest TRAILING gate («беру,
+  когда вы скажете») is flagged, and a gate belonging to an earlier comma-clause («если тест упадёт,
+  сообщу, а сейчас начинаю…») wrongly excuses the promise after it. Leading with the gate avoids the
+  first; the second is a miss this layer cannot close without parsing.
+- **The English side is weaker than the Russian side, structurally.** Russian promises are action
+  verbs («беру», «начинаю»); English ones are pronoun+modal («I'll», «I will»), which cannot tell
+  starting from waiting. Waiting is explicitly excluded — «I'll wait for your approval» passes,
+  because waiting is what a turn that ends actually does — but the exclusion is a list, and an
+  unusual way of saying "I am waiting" will be flagged.
+- **A host that does not deliver `last_assistant_message` gets no detection**, silently. There is no
+  transcript fallback, on purpose — see above.
+- **Without `--require-block`, a turn that drops the block entirely is not detected.** That is the
+  cost of not warning every turn in projects that never adopted the block.
+- **Removing the wiring silently removes the detector.** There is no rung that notices a hook that
+  stopped being wired.

package/tools/commands.mjs

@@ -140,6 +140,13 @@ const CATALOG = [
     kind: WRITER,
     oneLine: 'Auto-approve your own declared gate commands (docs/ai/gates.json) via a Claude Code hook — exact matches only, previews first (opt-in).',
   },
+  {
+    key: 'state-block-guard',
+    invocation: invocationOf('state-block-guard'),
+    group: 'Configure',
+    kind: READ_ONLY,
+    oneLine: 'Warn when a turn ends on a defective closing state block — a "nothing needed from you" answer or a promise of work that never started (Claude Code Stop hook; detection, never prevention; you paste the wiring).',
+  },
   {
     key: 'bridge-settings',
     invocation: invocationOf('bridge-settings'),