@thebassclef/lite 1.9.3 → 1.9.5

package/dist/lite/standards/session-start-banner-discipline.md

@@ -9,26 +9,39 @@ Session-start checks in `.claude/hooks/session-reflection.d/` emit banners that
 
 This standard names a four-level palette. Each check picks the level that matches its own state.
 
-## The four levels
+## The five levels
 
 | Level | Glyph | Text label | When to use |
 |---|---|---|---|
 | BLOCK | 🛑 | BLOCKED | The session cannot safely proceed with substantive work. Real defect. Missing prerequisite. Active drift that will corrupt state. |
+| GUARDRAIL | ⚙ | BASSCLEF DISCIPLINE GATE | The session must pause and apply discipline before proceeding. Not a defect. Chronicle stale, architect-review overdue, temperance marker missing, /decompose evidence owed. Per sunj-labs/bassclef-upstream#1930 Category A. |
 | ADVISORY | ⚠ | ADVISORY | Context worth reading. Session may proceed. The operator is informed; they choose whether to act now or later. |
 | INFO | ℹ | INFO | State report. No action needed. Fires only when the reader benefits from knowing the state. |
-| silent-on-clean | — | — | Check runs but reports nothing when state is nominal. Fires only on non-nominal state (which routes to one of the three above). |
+| silent-on-clean | — | — | Check runs but reports nothing when state is nominal. Fires only on non-nominal state (which routes to one of the four above). |
 
 Every check picks exactly one level. Ambiguous cases default to silent-on-clean.
 
+BLOCK and GUARDRAIL both stop the session on substantive work. The difference is tone. BLOCK signals a defect. GUARDRAIL signals a discipline pause. Machine readers grep the `BLOCKED:` prefix on message body lines regardless of header shape.
+
 ## How to pick
 
-Ask two questions in order.
+Ask three questions in order.
 
-1. **Does this check indicate the session cannot safely proceed?** If yes, BLOCK. Cannot-proceed means: writing code now will corrupt state, or will ship a broken change, or will silently defeat a safety mechanism. Missing bassclef-sync template drift. Failing pre-commit gate. Schema validation error. These block.
-2. **Does the reader gain value from knowing about this now?** If yes, ADVISORY or INFO. ADVISORY when the reader may want to act (read the artifact, address the drift). INFO when it is pure state (last save time, current branch). If no, silent-on-clean.
+1. **Does this check indicate a real defect that will corrupt state?** If yes, BLOCK. Schema validation failure, dangling reference, corrupt state file, missing bassclef-sync template drift. These block.
+2. **Does this check ask the agent to pause and apply discipline?** If yes, GUARDRAIL. Chronicle stale, architect-review overdue, temperance missing, /decompose evidence owed, pre-mortem light not fired. These are steering, not defects.
+3. **Does the reader gain value from knowing about this now?** If yes, ADVISORY or INFO. ADVISORY when the reader may want to act (read the artifact, address the drift). INFO when it is pure state (last save time, current branch). If no, silent-on-clean.
 
 Default to silent-on-clean when in doubt. Every advisory or info banner spends the reader's attention. Spend it on things they benefit from.
 
+## Helper functions
+
+Two shell helpers in `.claude/hooks/session-reflection.sh` render the banners.
+
+- `blocked_banner "$msg" [severity]` — renders BLOCK, ADVISORY, or INFO based on the second arg (default: blocking). Used by all four historical severities.
+- `guardrail_banner "$hook_name" "$step" "$retry"` — renders GUARDRAIL. Takes three args: hook name (goes in header), specific step, retry action. Reads `AI_NAME` from `${BASSCLEF_AI_NAME:-Claude}`. Per #1930 Category A design lock.
+
+Callers migrate from `blocked_banner` (blocking) to `guardrail_banner` one at a time when the check fits the discipline-gate shape (question 2 above). The additive-only path preserves the machine-reader contract.
+
 ## Signifier discipline (Norman)
 
 The glyph is a signifier — a perceivable cue that suggests state. The signifier fit is:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thebassclef/lite",
-  "version": "1.9.3",
+  "version": "1.9.5",
   "description": "Bassclef CLI — install and upgrade bassclef in your project with two commands.",
   "keywords": [
     "bassclef",