@sabaiway/agent-workflow-kit 3.12.0 → 3.14.0

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'),
@@ -222,7 +229,7 @@ const CATALOG = [
     invocation: invocationOf('commit-guard'),
     group: 'Orchestrate',
     kind: READ_ONLY,
-    oneLine: 'The read-only pre-commit guard: binds the LATEST completed run-gates --final receipt to the CURRENT tree — refusing on any fingerprint, declaration, evidence-hash, or lcov drift, a dangling later attempt, or unsatisfied review obligations; re-runs no gate or test.',
+    oneLine: 'The read-only pre-commit guard: FIRST refuses an INDEX that lags the working tree — so the commit cannot ship less than was verified, which deliberately blocks a partial commit (--no-verify stays the residual) — then binds the LATEST completed run-gates --final receipt to the CURRENT tree, refusing on any fingerprint, declaration, evidence-hash, or lcov drift, a dangling later attempt, or unsatisfied review obligations; re-runs no gate or test.',
   },
   {
     key: 'doc-parity',

package/tools/commit-guard.mjs

@@ -2,6 +2,15 @@
 // commit-guard.mjs — the read-only pre-commit guard (strip-the-kit 2.5, D10). It re-runs NO
 // gate/test subprocess: the heavy D3(b)/(c)/(d) verification lives in `run-gates --final`, whose
 // receipt this guard binds. `--check`:
+//   0. refuses an INDEX that lags the verified working tree — FIRST, before the fingerprint is
+//      computed. The gates and the fingerprint describe the WORKING tree while `git commit` builds
+//      the commit from the INDEX alone, and the fingerprint domain is identical either way, so
+//      without this arm a lagging index ships a strict SUBSET of what was verified. Refuses on
+//      tracked paths differing index↔worktree or reviewable untracked-not-ignored paths (the same
+//      never-committable filter the fingerprint applies; ignored paths never refuse), naming them
+//      up to INDEX_LAG_PATH_CAP with the remainder stated. A dirty tracked SUBMODULE is named
+//      separately with its own recovery. Fail-closed on an undecidable probe. This BLOCKS the
+//      deliberate partial commit by design — `--no-verify` is the stated residual, not a flag;
 //   1. recomputes the CURRENT tree fingerprint (the review-state export — read-only git plumbing);
 //   2. reads the LATEST completed final-run record from the core-evidence store (only the latest
 //      attempt at a fingerprint is authoritative — a green receipt is DEAD once a later attempt at
@@ -18,11 +27,11 @@
 
 import { readFileSync, lstatSync } from 'node:fs';
 import { resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { pathToFileURL, fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { computeTreeFingerprint, buildState, decideCheck } from './review-state.mjs';
-import { resolveEvidencePath, readEvidence, authoritativeOfKind, canonicalKindSerialization } from './core-evidence.mjs';
+import { computeTreeFingerprint, buildState, decideCheck, quoteReportName, shellQuoteArg } from './review-state.mjs';
+import { resolveEvidencePath, readEvidence, authoritativeOfKind, canonicalKindSerialization, computeWorkingState } from './core-evidence.mjs';
 import { resolveLcovPath } from './coverage-check.mjs';
 import { GATES_REL, loadDeclaration } from './run-gates.mjs';
 
@@ -44,10 +53,130 @@ export const resolveGitHooksPath = (projectDir) => {
   return line == null ? null : resolve(projectDir, line);
 };
 
+// How many offending paths the index-lag refusal names before it states a remainder count: enough
+// to act on, bounded so a wide lag cannot bury a pre-commit hook's output.
+export const INDEX_LAG_PATH_CAP = 10;
+
+// The recovery must name the run-gates the CONSUMER actually has. A repo-relative literal is only
+// correct inside this monorepo; every installed deployment keeps the tool beside this file. Shell-
+// quoted, because an install path carrying a space or a metacharacter would otherwise render an
+// instruction that is unrunnable at best and dangerous to paste at worst.
+const FINAL_RUN_TOOL = shellQuoteArg(fileURLToPath(new URL('./run-gates.mjs', import.meta.url)));
+
+// ONE budget across every named category — a per-category cap would print 2× the stated number.
+const renderBudgeted = (paths, budget) => ({
+  text: paths.slice(0, Math.max(budget, 0)).map(quoteReportName).join(', '),
+  used: Math.min(paths.length, Math.max(budget, 0)),
+});
+
+// The ONE ordered recovery plan — text and executable `argv` built from the SAME structure, so a
+// test can run exactly what the operator is shown instead of reconstructing its own commands.
+// Order matters: the submodule step first (staging and re-running --final before it would stale the
+// fresh receipt at once), then the index bits, because `git add -A` CANNOT restage a skip-worktree
+// or assume-unchanged entry — printing it alone is a recovery that silently does nothing. The two
+// bits get SEPARATE commands: one `update-index` invocation carrying both flags applies only one.
+// The text points at `git ls-files -v` rather than pasting names — the displayed list is capped,
+// and a name safe to display is not automatically safe to paste into a shell.
+export const buildIndexLagRecovery = (state) => {
+  const flags = state.flaggedPaths ?? [];
+  const steps = [];
+  if (state.unstagedSubmodulePaths.length > 0) {
+    steps.push({ text: 'commit or clean INSIDE every dirty submodule named above and stage its gitlink — a root-level git add -A cannot reach a submodule\'s own worktree' });
+  }
+  for (const [bit, key] of [['--no-skip-worktree', 'skipWorktree'], ['--no-assume-unchanged', 'assumeUnchanged']]) {
+    const affected = flags.filter((flag) => flag[key]);
+    if (affected.length === 0) continue;
+    // Scoped to the LAGGING paths only, never to `git ls-files -v`: that set also holds every
+    // de-materialised sparse-checkout entry, and clearing THEIR bit before `git add -A` would stage
+    // their deletions. The cap is handled by iteration, not by a wider enumeration. The executable
+    // form is offered ONLY when every affected name survives a byte round-trip — a lossily decoded
+    // name would address a DIFFERENT path, so there the text stands alone and says so.
+    const exact = affected.every((flag) => flag.exactName);
+    steps.push({
+      text: `clear the ${bit.slice(5)} bit on the bit-carrying path(s) named above — it is what makes git add -A a no-op on them — with git update-index ${bit} -- <path>, for those paths ONLY (never every entry git ls-files -v reports: that set includes de-materialised sparse paths whose deletions would then be staged)${exact ? '' : '; at least one of these names carries bytes that do not decode cleanly, so the name shown above is LOSSY and this refusal cannot give you a runnable command for it — its record is visible in git ls-files -v -z, and clearing that one is a by-hand step'}`,
+      ...(exact ? { argv: ['update-index', bit, '--', ...affected.map((flag) => flag.rel)] } : {}),
+    });
+  }
+  steps.push({ text: 'run git add -A from the work-tree root', argv: ['add', '-A'] });
+  steps.push({ text: `re-run node ${FINAL_RUN_TOOL} --final` });
+  steps.push({ text: 'commit the WHOLE tree' });
+  return steps;
+};
+
+// decideIndexLag(state) → a refusal, or null when the index already carries the verified tree.
+// The gates and the fingerprint both describe the WORKING tree; `git commit` takes the INDEX, and
+// the fingerprint domain cannot tell the two apart — so without this arm a lagging index ships a
+// strict subset of what was verified (it did, on 2026-07-25). FAIL-CLOSED on an undecidable probe:
+// the guard's whole claim is that the committed bytes ARE the verified bytes, and it cannot make
+// that claim about a tree it failed to read.
+export const decideIndexLag = (state) => {
+  if (state == null) {
+    return { code: 1, lines: ['commit-guard: REFUSED — the index/worktree comparison could not be decided (a git probe failed); re-run inside the work tree and inspect `git status` by hand before committing'] };
+  }
+  // THREE categories, because they take DIFFERENT recoveries. A bit-carrying path folded into the
+  // plain list would be un-actionable: its clause is the only one whose recovery is not `git add -A`,
+  // and on cap overflow the plain paths could hide every one of them.
+  const flaggedSet = new Set((state.flaggedPaths ?? []).map((flag) => flag.rel));
+  const all = [...state.unstagedPaths, ...state.untrackedPaths];
+  const plain = all.filter((rel) => !flaggedSet.has(rel));
+  const bitCarrying = all.filter((rel) => flaggedSet.has(rel));
+  const submodules = state.unstagedSubmodulePaths;
+  const total = plain.length + bitCarrying.length + submodules.length;
+  if (total === 0) return null;
+  // Every non-empty category reserves a slot before the budget is spent — a clause that names no
+  // path cannot deliver the recovery it exists to state.
+  const groups = [plain, bitCarrying, submodules];
+  const rendered = [];
+  let spent = 0;
+  groups.forEach((group, index) => {
+    if (group.length === 0) {
+      rendered[index] = { text: '', used: 0 };
+      return;
+    }
+    const stillToReserve = groups.slice(index + 1).filter((later) => later.length > 0).length;
+    rendered[index] = renderBudgeted(group, INDEX_LAG_PATH_CAP - spent - stillToReserve);
+    spent += rendered[index].used;
+  });
+  const hidden = total - spent;
+  const remainder = hidden > 0 ? `, plus ${hidden} further path(s) not listed` : '';
+  const clauses = [];
+  if (plain.length > 0) {
+    clauses.push(`paths the index does not carry: ${rendered[0].text}`);
+  }
+  if (bitCarrying.length > 0) {
+    clauses.push(`path(s) held back by a skip-worktree / assume-unchanged index bit: ${rendered[1].text}`);
+  }
+  if (submodules.length > 0) {
+    clauses.push(`tracked submodule(s) not proven current: ${rendered[2].text}`);
+  }
+  // ONE ordered recovery, and every step must actually converge. The submodule step comes FIRST:
+  // staging and re-running --final before it would stale the fresh receipt at once. The index-bit
+  // step comes next, because `git add -A` CANNOT restage a skip-worktree / assume-unchanged entry —
+  // printing it alone would be a recovery that silently does nothing. It deliberately points at
+  // `git ls-files -v` rather than pasting names: the list above is capped, and a filename safe to
+  // display is not automatically safe to paste into a shell.
+  const steps = buildIndexLagRecovery(state);
+  // The iterate-until-silent hint must also fire when the CAP hid work — otherwise a truncated
+  // list of submodules with no index bits would send the operator to --final and commit while
+  // unnamed ones are still unhandled.
+  const converge = hidden > 0 || (state.flaggedPaths ?? []).length > 0
+    ? ' The listed paths are capped: re-run this guard after each pass and it names the next batch, until it names none — that is the completion signal.'
+    : '';
+  return {
+    code: 1,
+    lines: [`commit-guard: REFUSED — the index does NOT carry the whole CURRENT working tree, so this commit would leave part of it behind: ${clauses.join('; ')}${remainder}. To recover, in order: ${steps.map((step, i) => `(${i + 1}) ${step.text}`).join('; ')}. An intentional partial commit stays git commit --no-verify.${converge}`],
+  };
+};
+
 // runGuard({ cwd, env }) → { code, lines }. Every refusal names its recovery.
 export const runGuard = ({ cwd = process.cwd(), env = process.env } = {}) => {
   const rootTop = gitLine(['rev-parse', '--show-toplevel'], cwd);
   if (rootTop == null) return { code: 1, lines: ['commit-guard: not a git work tree — nothing to guard'] };
+  // FIRST: a pure tree property needing no store read. Its recovery re-stages the tree and re-mints
+  // the receipt, so every arm below is re-decided anyway — naming a stale fingerprint ahead of it
+  // would send the operator down a recovery they must redo.
+  const indexLag = decideIndexLag(computeWorkingState(cwd));
+  if (indexLag !== null) return indexLag;
   const fingerprint = computeTreeFingerprint(cwd);
   // The guard's OWN reads resolve FIXED git-dir paths — a stray AW_CORE_EVIDENCE / AW_LCOV_FILE
   // in the committing shell must never redirect the LAST line of defense to a forged artifact
@@ -128,11 +257,13 @@ const HELP = `commit-guard — the read-only pre-commit guard (agent-workflow fa
 Usage:
   node commit-guard.mjs --check [--cwd <dir>]
 
-Re-runs NOTHING: recomputes the current tree fingerprint and binds the LATEST completed
-run-gates --final receipt — refusing on { no receipt for this tree · a red latest attempt ·
-before≠after · declaration content drift · evidence-hash drift · lcov drift · unsatisfied review
-obligations (the review-state decision) }. Wire it into pre-commit; \`git commit --no-verify\`
-stays the stated residual (self-discipline, not a security boundary).
+Re-runs NOTHING: refuses an INDEX that lags the verified working tree (FIRST — unstaged tracked
+paths, reviewable untracked paths, or a dirty tracked submodule, each named with its recovery;
+this deliberately blocks a partial commit), then recomputes the current tree fingerprint and binds
+the LATEST completed run-gates --final receipt — refusing on { no receipt for this tree · a red
+latest attempt · before≠after · declaration content drift · evidence-hash drift · lcov drift ·
+unsatisfied review obligations (the review-state decision) }. Wire it into pre-commit;
+\`git commit --no-verify\` stays the stated residual (self-discipline, not a security boundary).
 
 Exit codes: 0 pass; 1 refused (reason named); 2 usage.`;