@windyroad/risk-scorer 0.4.1-preview.215 → 0.4.2-preview.217

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-risk-scorer",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Pipeline risk scoring, commit/push/release gates for Claude Code"
 }

package/hooks/lib/session-marker.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# Shared session-announcement marker helpers (P095 / ADR-038).
+#
+# Used by UserPromptSubmit hooks to gate verbose MANDATORY instruction
+# prose behind a once-per-session check. First prompt of a session emits
+# the full block AND calls mark_announced; subsequent prompts see the
+# marker via has_announced and emit only a terse reminder.
+#
+# Why no TTL or drift check (unlike review-gate.sh): announcement is
+# bookkeeping for prose verbosity, not enforcement. PreToolUse gates
+# still block unauthorised edits regardless of announcement state; the
+# delegated agent re-reads policy when it runs. Extending the marker's
+# lifetime across policy changes mid-session is safe — the gate, not
+# the announcement, is load-bearing.
+#
+# Marker path convention: /tmp/${SYSTEM}-announced-${SESSION_ID}
+# (mirrors the /tmp/${SYSTEM}-reviewed-${SESSION_ID} convention from
+# style-guide/voice-tone/risk-scorer review-gate.sh; the -announced-
+# suffix distinguishes announcement markers from clearance markers).
+#
+# Empty SESSION_ID fallback: has_announced returns 1 (not announced,
+# full block emits) and mark_announced is a no-op (no file written).
+# This covers manual hook invocation, test harnesses, and any rare
+# case where Claude Code does not pass a session_id on stdin.
+
+# Returns 0 if the hook for SYSTEM has already announced in SESSION_ID,
+# 1 otherwise. Empty SESSION_ID => returns 1 (never announced).
+#
+# Usage: has_announced "architect" "$SESSION_ID"
+has_announced() {
+  local SYSTEM="$1"
+  local SESSION_ID="$2"
+  [ -n "$SESSION_ID" ] || return 1
+  [ -f "/tmp/${SYSTEM}-announced-${SESSION_ID}" ]
+}
+
+# Writes the announcement marker for SYSTEM in SESSION_ID. Empty
+# SESSION_ID => no-op. Safe to call more than once per session.
+#
+# Usage: mark_announced "architect" "$SESSION_ID"
+mark_announced() {
+  local SYSTEM="$1"
+  local SESSION_ID="$2"
+  [ -n "$SESSION_ID" ] || return 0
+  : > "/tmp/${SYSTEM}-announced-${SESSION_ID}"
+}

package/hooks/plan-risk-guidance.sh

@@ -7,6 +7,7 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/gate-helpers.sh"
+source "$SCRIPT_DIR/lib/session-marker.sh"
 _enable_err_trap
 
 _parse_input
@@ -39,13 +40,32 @@ if [ -f "RISK-POLICY.md" ]; then
   fi
 fi
 
-# --- Emit guidance (allow — advisory only, not a gate) ---
+# --- P096 Phase 2 — once-per-session gating (ADR-038 progressive disclosure) ---
+# First EnterPlanMode of a session emits the full advisory body; subsequent
+# entries within the same session emit a terse reminder (≤150 bytes per the
+# ADR-038 budget). Pipeline state and appetite are unchanged across plan-mode
+# entries within one session, so re-emitting full prose is repetition.
+if has_announced "risk-scorer-plan-guidance" "$SESSION_ID"; then
+  cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "allow",
+    "systemMessage": "MANDATORY release-risk gate active (RISK-POLICY.md present). Release risk: ${RELEASE_SCORE}; appetite: ${APPETITE}. ExitPlanMode will FAIL plans projected above appetite. See first-EnterPlanMode emission for full guidance."
+  }
+}
+EOF
+  exit 0
+fi
+
+# --- First emission: full advisory (compressed per audit recommendation) ---
+mark_announced "risk-scorer-plan-guidance" "$SESSION_ID"
 cat <<EOF
 {
   "hookSpecificOutput": {
     "hookEventName": "PreToolUse",
     "permissionDecision": "allow",
-    "systemMessage": "RELEASE RISK GUIDANCE FOR PLANNING:\nThe unreleased queue currently contains:\n${UNRELEASED_SUMMARY}\n\nCurrent release risk score: ${RELEASE_SCORE}.\nRisk appetite threshold: ${APPETITE} (Medium).\n\nYour plan MUST account for projected release risk. If the plan's proposed changes would push projected release risk above appetite when combined with the existing unreleased queue, the plan MUST include one or more of:\n- Release the current unreleased queue first (before implementing the plan)\n- Split the plan into smaller batches that keep projected release risk within appetite\n- Include specific risk-reducing steps (additional tests, rollback procedures)\n\nThe risk-scorer will assess projected release risk at ExitPlanMode and FAIL plans that exceed appetite without a release strategy."
+    "systemMessage": "RELEASE RISK GUIDANCE FOR PLANNING:\nUnreleased queue:\n${UNRELEASED_SUMMARY}\n\nRelease risk: ${RELEASE_SCORE}. Appetite threshold: ${APPETITE} (Medium).\n\nIf projected release risk would exceed appetite, the plan MUST include a release strategy (release queue first, split into smaller batches, or risk-reducing steps). See RISK-POLICY.md for option details. ExitPlanMode runs the risk-scorer and FAILS plans above appetite without a strategy."
   }
 }
 EOF

package/hooks/test/plan-risk-guidance-once-per-session.bats

@@ -0,0 +1,95 @@
+#!/usr/bin/env bats
+
+# P096 Phase 2: plan-risk-guidance.sh applies once-per-session gating
+# (ADR-038 progressive disclosure pattern) so the advisory body emits
+# in full only on the first EnterPlanMode of a session. Subsequent
+# EnterPlanMode events within the same session emit a terse reminder
+# (≤150 bytes payload after the systemMessage prefix).
+#
+# Reuses the shared session-marker.sh helper synced from
+# packages/shared/hooks/lib/session-marker.sh.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  HOOK="$REPO_ROOT/packages/risk-scorer/hooks/plan-risk-guidance.sh"
+
+  WORKDIR="$(mktemp -d)"
+  # Minimal RISK-POLICY.md so the appetite extraction has something to read.
+  cat > "$WORKDIR/RISK-POLICY.md" <<'POLICY'
+# Risk Policy
+Threshold: 4
+POLICY
+
+  SID="plan-risk-guidance-test-$$-$RANDOM"
+}
+
+teardown() {
+  rm -f "/tmp/risk-scorer-plan-guidance-announced-${SID}"
+  rm -f "/tmp/risk-scorer-plan-guidance-announced-${SID}-alt"
+  rm -rf "$WORKDIR"
+}
+
+run_hook() {
+  local sid="$1"
+  (cd "$WORKDIR" && \
+    echo "{\"session_id\":\"$sid\",\"tool_name\":\"EnterPlanMode\"}" | \
+    bash "$HOOK")
+}
+
+@test "plan-risk-guidance: first invocation emits the full RELEASE RISK GUIDANCE body" {
+  run run_hook "$SID"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"RELEASE RISK GUIDANCE FOR PLANNING"* ]]
+  [[ "$output" == *"Release risk:"* ]]
+  [[ "$output" == *"Appetite threshold"* ]]
+  [[ "$output" == *"release strategy"* ]] || [[ "$output" == *"release queue first"* ]]
+}
+
+@test "plan-risk-guidance: first invocation writes the announcement marker" {
+  run_hook "$SID" >/dev/null
+  [ -f "/tmp/risk-scorer-plan-guidance-announced-${SID}" ]
+}
+
+@test "plan-risk-guidance: second invocation in the same session emits a terse reminder" {
+  run_hook "$SID" >/dev/null
+  run run_hook "$SID"
+  [ "$status" -eq 0 ]
+  # Terse reminder MUST carry imperative signal word + gate name + cross-ref.
+  [[ "$output" == *"MANDATORY"* ]] || [[ "$output" == *"REQUIRED"* ]] || [[ "$output" == *"NON-OPTIONAL"* ]]
+  [[ "$output" == *"release-risk gate"* ]] || [[ "$output" == *"risk"* ]]
+  # Must NOT re-emit the full prose (release-strategy listing, projected-risk paragraph).
+  [[ "$output" != *"RELEASE RISK GUIDANCE FOR PLANNING"* ]]
+}
+
+@test "plan-risk-guidance: second invocation reminder payload is ≤300 bytes" {
+  run_hook "$SID" >/dev/null
+  run run_hook "$SID"
+  # Total response is JSON wrapper + systemMessage; reminder body must be
+  # short enough that the full response fits well under the ADR-038 budget.
+  [ "${#output}" -lt 600 ]
+}
+
+@test "plan-risk-guidance: different session_id re-emits the full body" {
+  run_hook "$SID" >/dev/null
+  local SID2="${SID}-alt"
+  run run_hook "$SID2"
+  [[ "$output" == *"RELEASE RISK GUIDANCE FOR PLANNING"* ]]
+  rm -f "/tmp/risk-scorer-plan-guidance-announced-${SID2}"
+}
+
+@test "plan-risk-guidance: empty session_id emits the full body and writes no marker" {
+  run run_hook ""
+  [[ "$output" == *"RELEASE RISK GUIDANCE FOR PLANNING"* ]]
+  # Empty SESSION_ID fallback per shared session-marker contract.
+  [ ! -f "/tmp/risk-scorer-plan-guidance-announced-" ]
+}
+
+@test "plan-risk-guidance: emits valid JSON with permissionDecision allow on both first and subsequent invocations" {
+  run run_hook "$SID"
+  [[ "$output" == *'"permissionDecision": "allow"'* ]]
+  [[ "$output" == *'"hookEventName": "PreToolUse"'* ]]
+
+  run run_hook "$SID"
+  [[ "$output" == *'"permissionDecision": "allow"'* ]]
+  [[ "$output" == *'"hookEventName": "PreToolUse"'* ]]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/risk-scorer",
-  "version": "0.4.1-preview.215",
+  "version": "0.4.2-preview.217",
   "description": "Pipeline risk scoring, commit/push gates, and secret leak detection",
   "bin": {
     "windyroad-risk-scorer": "./bin/install.mjs"