@sabaiway/agent-workflow-kit 3.14.0 → 3.15.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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.15.0 — a shipped opt-in now advertises itself (AD-076)
+
+`/agent-workflow-kit upgrade` and `recommendations` now offer the closing-block detector that 3.14.0
+shipped.
+
+They did not, and that was the whole defect. 3.14.0 added the detector with a mode doc, a catalog row
+and a README row — every surface an agent reads — and no advisor entry. So a user who installed the
+update and ran `upgrade` was told «nothing is broken — process is optimal» while the capability from
+that very version sat unwired and unmentioned. Both statements were true alone. Together they meant
+the only route to the new feature was reading this file or interrogating the agent.
+
+The new item fires when no `Stop` hook runs the detector's runtime, states what goes unseen without
+it, and carries a hand-apply pointer to the mode doc — there is still no writer for this hook, and the
+doc carries the exact block plus the three merge cases. It matches on the runtime FILE NAME rather
+than an exact command, because with no writer every user pastes their own path: an exact comparison
+would keep nagging someone who already wired it.
+
+The reason this was structurally invited is worth stating. Every other surface of a new mode is
+drift-guarded — omit the `SKILL.md` row, the catalog entry or the mode doc and a test fails. The
+advisor is the one surface with no such guard, and the only one a user receives without asking. The
+guard that would close it needs an accurate claim for all 28 modes, so it is the next slice's first
+item rather than a hurried addition here.
+
 ## 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

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.14.0'
+  version: '3.15.0'
 ---
 
 # agent-workflow-kit

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "3.14.0",
+  "version": "3.15.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/modes/state-block-guard.md

@@ -131,7 +131,7 @@ form this family already sanctions. When the detector has earned a writer in rea
            "hooks": [
              {
                "type": "command",
-               "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state-block-guard.mjs\" --require-block",
+               "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/state-block-guard.mjs\"",
                "timeout": 10
              }
            ]
@@ -141,10 +141,12 @@ form this family already sanctions. When the detector has earned a writer in rea
    }
    ```
 
-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.
+**Add `--require-block` to that command IF your project requires the three-part block on every
+message** — then a turn that drops the block entirely is reported too. It is left OFF above on
+purpose: this kit does not mandate the block, so switching it on for a project that never adopted it
+would warn after nearly every turn. `--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.

package/tools/recommendations.mjs

@@ -104,6 +104,7 @@ export const SEVERITIES = Object.freeze({
   'read-lane': SEVERITY_OPTIONAL,
   'read-lane.stale': SEVERITY_ATTENTION,
   'read-lane.missing': SEVERITY_ATTENTION,
+  'state-block': SEVERITY_OPTIONAL,
   'family-freshness': SEVERITY_ATTENTION,
   'sandbox-masks': SEVERITY_OPTIONAL,
   'agy-adddir': SEVERITY_OPTIONAL,
@@ -161,6 +162,7 @@ export const WHATS = Object.freeze({
   'read-lane': 'the gate hook is wired but the read-only compound lane is off — pipes/chains of seeded reads still prompt one by one',
   'read-lane.stale': 'the read-lane is ON but the placed gate hook is stale — an old hook never reads lanes.json, so the lane is silently dark; reseed it',
   'read-lane.missing': 'the gate hook is wired but its placed file is missing — every Bash call errors and the read-lane is dark; re-place it',
+  'state-block': 'nothing checks the closing state block — a turn that ends on «nothing needed from you», or on a promise it never started, passes unseen',
   'family-freshness': '{parts}',
   'sandbox-masks': '{n} sandbox device mask(s) clutter git status — the managed exclude block is absent or stale',
   'sandbox-masks.stale-real': '{n} sandbox device mask(s) clutter git status — the exclude block is stale; {m} fenced entr(ies) are REAL paths (a fresh apply drops them)',
@@ -214,6 +216,7 @@ export const BENEFITS = Object.freeze({
   'gate-hook': 'velocity — your own declared gate commands auto-approve byte-exactly (opt-in PreToolUse hook)',
   'commit-guard': 'integrity — commits require the ONE green --final receipt at the exact staged fingerprint (consented pre-commit arm)',
   'read-lane': 'velocity — pipes/chains of your seeded read-only commands auto-approve instead of prompting (opt-in, conservatively classified)',
+  'state-block': 'no silent stalls — a turn ending on «you are not needed», or on work it never started, warns at once instead of waiting to be spotted',
   'family-freshness': 'currency — placed family members carry the latest shipped fixes and features',
   'sandbox-masks': 'zero clutter — git status shows only your changes (the review domain already ignores the masks by construction)',
   'agy-adddir': 'large reviews — an oversized agy code review offloads to a staging dir instead of refusing',
@@ -439,6 +442,26 @@ const probeReadLane = ({ root, deps, add, skip }) => {
   }
 };
 
+// The state-block-guard offer (AD-075 · OPT-IN-SHIPS-INVISIBLE). This item exists because its absence
+// fired: 3.14.0 shipped the detector with a mode doc, a catalog row and a README row — and no advisor
+// entry — so `upgrade` reported «nothing is broken» to a user who did not have it. There is no writer
+// for this hook, so the apply is a HAND-APPLY pointer at the mode doc, which carries the exact block
+// and the three merge cases.
+const probeStateBlockHook = ({ root, deps, add, skip }) => {
+  try {
+    const project = readSettingsFile(join(root, SETTINGS_FILE), { ...deps, cwd: root });
+    const local = readSettingsFile(join(root, SETTINGS_LOCAL_FILE), { ...deps, cwd: root });
+    if (isStateBlockGuardWired(project.data) || isStateBlockGuardWired(local.data)) return; // converged
+    add(
+      'state-block',
+      fillTemplate(WHATS['state-block'], {}),
+      `HAND-APPLY: add a Stop hook running ${STATE_BLOCK_HOOK_COMMAND} to ${SETTINGS_FILE} — the exact block and the three merge cases are in references/modes/state-block-guard.md`,
+    );
+  } catch (err) {
+    skip('state-block', err);
+  }
+};
+
 const probeFamilyFreshness = ({ deps, add, skip }) => {
   try {
     const survey = deps.surveyFamily ?? surveyFamily;
@@ -617,6 +640,29 @@ export const READ_LANE_KEY = 'readLane';
 const GATE_HOOK_REL = '.claude/hooks/agent-workflow-gates.mjs';
 const BUNDLED_HOOK_ABS = join(HERE, '..', 'references', 'hooks', 'gate-approve.mjs');
 
+// The state-block-guard wiring the advisor looks for. Matched on the RUNTIME FILE NAME inside the
+// command, not on an exact string: the hook has no writer, so every user pastes their own path —
+// a copy under `.claude/hooks/`, a kit-source path, `--require-block` or not. Any Stop entry that
+// runs this runtime counts as wired, which is the honest question ("is it watching?").
+export const STATE_BLOCK_HOOK_RUNTIME = 'state-block-guard.mjs';
+// NO `--require-block` in the offered command. That flag turns on the absent-block report, and this
+// kit does not mandate the three-part closing block — recommending it to every project would hand
+// them a hook that warns after nearly every turn. The mode doc explains when to add it. (Offering the
+// strict flag by default would also contradict the very reason the report was made opt-in.)
+export const STATE_BLOCK_HOOK_COMMAND = `node "$CLAUDE_PROJECT_DIR/.claude/hooks/${STATE_BLOCK_HOOK_RUNTIME}"`;
+const runsStateBlockGuard = (hook) => typeof hook?.command === 'string' && hook.command.includes(STATE_BLOCK_HOOK_RUNTIME);
+// Both entry shapes count. The matcher-group form (an object carrying its own `hooks` array) is what
+// this family ships and what was observed firing; a flat entry is accepted too, because the question
+// this probe answers is "is anything watching?" — and guessing NO for a wiring that works would nag
+// someone who already did the work.
+const isStateBlockGuardWired = (data) => {
+  const entries = data?.hooks?.Stop;
+  if (!Array.isArray(entries)) return false;
+  return entries.some((entry) => (Array.isArray(entry?.hooks)
+    ? entry.hooks.some(runsStateBlockGuard)
+    : runsStateBlockGuard(entry)));
+};
+
 // Byte-compare the placed gate hook against the bundled runtime. A read error (an unreadable placed
 // hook, a broken kit bundle) propagates → the probe states a skip, never a wrong currency verdict.
 const isPlacedHookCurrent = (root, deps) => {
@@ -879,6 +925,7 @@ const PROBES = Object.freeze([
   probeGates,
   probeCommitGuard,
   probeReadLane,
+  probeStateBlockHook,
   probeFamilyFreshness,
   probeMasksItem,
   probeAgyAdddir,