@windyroad/risk-scorer 0.4.1 → 0.4.2-preview.218

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/README.md

@@ -13,6 +13,7 @@ The risk-scorer plugin brings ISO 31000-aligned risk management to your AI codin
 3. **Gates pushes** -- blocks `git push` for high-risk changesets (use `npm run push:watch` instead)
 4. **Detects secrets** -- scans edits for API keys, tokens, passwords, and other credentials before they're written
 5. **Reviews plans** -- scores implementation plans for risk before you start building
+6. **Gates outbound prose** -- reviews `gh issue/pr` bodies, security advisories, npm publish content, and `.changeset/*.md` drafts for confidential-information leaks before they reach external surfaces
 
 All thresholds are configurable through your project's `RISK-POLICY.md`.
 
@@ -46,13 +47,14 @@ This creates a `RISK-POLICY.md` tailored to your project, defining impact levels
 | `risk-score-commit-gate.sh` | Bash (git commit) | Blocks commits when risk exceeds threshold |
 | `risk-score-plan-enforce.sh` | ExitPlanMode | Ensures plans are risk-scored before execution |
 | `plan-risk-guidance.sh` | EnterPlanMode | Injects risk guidance into plan mode |
+| `external-comms-gate.sh` | Bash, Edit, Write | Gates outbound prose (`gh issue/pr`, `gh api .../security-advisories`, `npm publish`, `.changeset/*.md`) on confidential-information leak review |
 | `wip-risk-mark.sh` | After edit | Records WIP risk assessment |
-| `risk-score-mark.sh` | Agent completes | Marks risk review as done |
+| `risk-score-mark.sh` | Agent completes | Marks risk review as done; writes external-comms marker on `wr-risk-scorer:external-comms` PASS |
 | `risk-hash-refresh.sh` | After Bash | Refreshes content hashes |
 
 ## Agents
 
-The plugin includes five specialised agents:
+The plugin includes six specialised agents:
 
 | Agent | Purpose |
 |-------|---------|
@@ -61,6 +63,48 @@ The plugin includes five specialised agents:
 | `wr-risk-scorer:pipeline` | Scores pipeline actions (commit, push, release) |
 | `wr-risk-scorer:plan` | Reviews implementation plans for risk |
 | `wr-risk-scorer:policy` | Validates `RISK-POLICY.md` for ISO 31000 compliance |
+| `wr-risk-scorer:external-comms` | Reviews drafts of outbound prose (gh issues/PRs, advisories, npm publish, changeset bodies) for confidential-information leaks per `RISK-POLICY.md` |
+
+## On-demand assessment skills
+
+| Skill | Purpose |
+|-------|---------|
+| `/wr-risk-scorer:assess-wip` | WIP risk nudge for the current uncommitted diff |
+| `/wr-risk-scorer:assess-release` | Pipeline risk assessment for the unpushed queue (pre-satisfies the commit gate) |
+| `/wr-risk-scorer:assess-external-comms` | External-comms leak review for a draft outbound body (pre-satisfies the external-comms gate) |
+| `/wr-risk-scorer:create-risk` | Create a standing-risk register entry |
+| `/wr-risk-scorer:update-policy` | Generate or update `RISK-POLICY.md` |
+
+## External-comms gate
+
+The `external-comms-gate.sh` hook intercepts outbound prose tool calls and the
+`.changeset/*.md` author surface so confidential-information leaks are caught
+before they reach a public or vendor-private channel.
+
+Gated surfaces:
+- `gh issue create` / `gh issue comment` / `gh issue edit`
+- `gh pr create` / `gh pr comment` / `gh pr edit`
+- `gh api .../security-advisories` and `gh api .../comments`
+- `npm publish`
+- `PreToolUse:Write` and `PreToolUse:Edit` on `.changeset/*.md` (P073 — gated at author time, before the changeset body lands in CHANGELOG.md and every published npm tarball)
+
+Behaviour:
+1. A hybrid regex pre-filter (`hooks/lib/leak-detect.sh`) catches high-confidence
+   leak shapes (credentials, business-context-paired financial figures and
+   user-counts) and denies immediately with the matched class.
+2. Anything not pre-filtered is delegated to the `wr-risk-scorer:external-comms`
+   subagent for context-aware review against `RISK-POLICY.md` Confidential
+   Information classes. The PostToolUse marker hook writes a per-draft marker
+   on `EXTERNAL_COMMS_RISK_VERDICT: PASS`.
+3. If `RISK-POLICY.md` is absent, the gate runs in advisory-only mode and
+   permits the call (graceful adoption).
+
+Override: `BYPASS_RISK_GATE=1` short-circuits the gate (consistent with
+`git-push-gate.sh`). Reserved for cases the user has confirmed safe.
+
+The canonical hook lives at `packages/shared/hooks/external-comms-gate.sh` and
+is synced into each consumer plugin via `scripts/sync-external-comms-gate.sh`
+per ADR-017 (CI runs `npm run check:external-comms-gate` to detect drift).
 
 ## Updating and Uninstalling
 

package/agents/external-comms.md

@@ -0,0 +1,94 @@
+---
+name: external-comms
+description: Reviews drafts of external-facing prose (gh issues / PRs / advisories, npm publish content, .changeset/*.md bodies) for confidential-information leaks per RISK-POLICY.md. Read-only — emits a structured PASS/FAIL verdict consumed by the external-comms-gate marker hook.
+tools:
+  - Read
+  - Glob
+  - Grep
+model: inherit
+---
+
+You are the External-Comms Risk Reviewer. Your single job: read the draft of an outbound prose tool call (a `gh issue create --body ...`, a PR description, a security-advisory body, a `.changeset/*.md` file, or the README diff that `npm publish` will publish) and return a structured PASS/FAIL verdict against RISK-POLICY.md's Confidential Information classes.
+
+You are read-only. You do NOT write files, do NOT commit, do NOT modify the draft. Your verdict is consumed by the `risk-score-mark.sh` PostToolUse hook (P064 / ADR-028 amended), which writes the marker that allows the gated tool call to proceed.
+
+## What you receive
+
+The invoking skill (`/wr-risk-scorer:assess-external-comms`) or the agent that hit the gate provides:
+
+- The **draft body** verbatim — the exact prose that would land on the external surface.
+- The **target surface** — one of: `gh-issue-create`, `gh-issue-comment`, `gh-issue-edit`, `gh-pr-create`, `gh-pr-comment`, `gh-pr-edit`, `gh-api-security-advisories`, `gh-api-comments`, `npm-publish`, `changeset-author`.
+- The **destination** when known (e.g. `anthropics/claude-code#52831`).
+
+Read `RISK-POLICY.md` (project root) to get the authoritative Confidential Information class list. As of P064 it covers:
+
+- Client names, project names, engagement details
+- Revenue figures, pricing, financial metrics
+- User counts, download statistics, traffic volumes
+- Internal business strategy or roadmap details
+
+The hybrid pre-filter (`packages/*/hooks/lib/leak-detect.sh`) has already caught HIGH-CONFIDENCE shapes (credentials, business-context-paired financial figures and user counts). If the gate denied with a hard-fail reason, the draft did NOT reach you. Your job is the AMBIGUOUS prose layer: text that mentions clients-by-paraphrase, hints at internal architecture, names embargoed product features, or quotes prod URL fragments, where context decides whether it is a leak.
+
+## Review process
+
+1. **Read the draft and the surface**. The surface determines the audience: `gh-api-security-advisories` lands on a vendor private channel; `gh-issue-create` lands publicly on a third-party repo; `npm-publish` lands as a permanently-published artefact. The same content may be safe for one surface and a leak on another.
+2. **Read RISK-POLICY.md** to ground every finding against the named class. Do not invent classes; do not score by analogy if the policy already names a class that fits.
+3. **Pass each Confidential Information class against the draft**. For each match, note the specific substring + the policy class it violates.
+4. **Apply context-aware judgement**:
+   - A package name (`@windyroad/itil`) is fine to mention; an internal *codename* for an unreleased product is not.
+   - A generic test failure description (`Node 20 build broke`) is fine; a description that quotes prod-environment hostnames or internal-staging-URL fragments is a leak.
+   - A user-count figure surrounded by marketing context (an existing public press release sentence) is not new information; the same figure newly disclosed here would be a leak.
+   - A `.changeset/*.md` body lands in CHANGELOG.md, the Release PR body, the GitHub Release page, AND every published npm tarball. Treat it as the highest-exposure surface; mistakes here are durable across every publishing artefact (P073).
+
+## Verdict format (MANDATORY)
+
+End your report with a structured block consumed by `risk-score-mark.sh`. Every field is required.
+
+```
+EXTERNAL_COMMS_RISK_VERDICT: PASS
+EXTERNAL_COMMS_RISK_KEY: <sha256 hex string>
+```
+
+OR for a failed review:
+
+```
+EXTERNAL_COMMS_RISK_VERDICT: FAIL
+EXTERNAL_COMMS_RISK_KEY: <sha256 hex string>
+EXTERNAL_COMMS_RISK_REASON: <one-line description of the leak class + matched fragment>
+```
+
+Compute the key as:
+
+```
+printf '%s\n%s' "<draft body verbatim>" "<surface name>" | shasum -a 256 | cut -d' ' -f1
+```
+
+The key MUST match the gate's computation exactly — a key mismatch means the marker is written for a different draft and the original gated call will continue to deny.
+
+## Grounding (ADR-026)
+
+Every FAIL verdict MUST cite:
+
+- The specific RISK-POLICY.md class violated (verbatim — copy the bullet from the policy).
+- The exact substring from the draft that triggered the call.
+- A one-line explanation of why this combination of surface + content constitutes a leak.
+
+Example:
+
+> EXTERNAL_COMMS_RISK_REASON: "Client names" class — draft contains "Acme Corp" naming a paying engagement; gh-issue-create on a public third-party repo would publicly disclose the client relationship.
+
+## Constraints
+
+- You are a reviewer, not an editor — do NOT propose rewrites in the verdict block. (Free prose suggestions outside the verdict block are fine and helpful.)
+- Do NOT score by analogy when the policy names the class.
+- Do NOT write to `/tmp/` or any marker location yourself — the PostToolUse hook owns that.
+- Do NOT skip the `EXTERNAL_COMMS_RISK_KEY` line; without it, the marker hook has no key to write the marker against and the gate will deny again on retry.
+- When the draft is empty (e.g. `npm publish` with no extractable body fragment), review the staged content the publish would push (README diff, package.json description) instead. If neither is available, FAIL with reason "draft body unresolvable; cannot risk-review without text" so the user can pre-review manually.
+
+## Below-Appetite Output Rule (ADR-013 Rule 5)
+
+When the verdict is PASS and no Confidential Information class matched, your output may be terse: a one-line "no Confidential Information class matched" plus the verdict block. Do not pad with advisory prose; policy-authorised drafts proceed silently.
+
+## Above-Appetite (FAIL) Output
+
+When the verdict is FAIL, surface remediation suggestions in PROSE BEFORE the verdict block — what specific substrings to redact, paraphrase, or move to a private channel. The verdict block itself stays structured and machine-parseable.

package/hooks/external-comms-gate.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+# PreToolUse hook: gates outbound prose for risk/leak review (P064 / ADR-028 amended).
+#
+# Surface (matched on Bash command text or Edit/Write file_path):
+#   - gh issue create | comment | edit            (public issue bodies)
+#   - gh pr   create | comment | edit             (public PR bodies)
+#   - gh api .../security-advisories              (advisory drafts)
+#   - gh api .../comments                         (any REST surface accepting prose)
+#   - npm publish                                 (README / package metadata to npm)
+#   - PreToolUse:Write|Edit on .changeset/*.md    (P073 — gates author-time)
+#
+# Gate behaviour:
+#   1. BYPASS_RISK_GATE=1 short-circuits the gate (consistent with git-push-gate.sh).
+#   2. RISK-POLICY.md absent → advisory-only mode (permits with systemMessage).
+#   3. Hybrid leak-pattern pre-filter (lib/leak-detect.sh) hard-fails on
+#      credentials, prod-URL prefixes, business-context-paired financial figures,
+#      or business-context-paired user counts. Deny includes the matched class.
+#   4. Otherwise: check for a per-evaluator marker keyed on
+#      sha256(draft_body + '\n' + surface). Marker present → permit.
+#      Marker absent → deny with directive to delegate to wr-risk-scorer:external-comms.
+#
+# Marker location: ${TMPDIR:-/tmp}/claude-risk-${SESSION_ID}/external-comms-reviewed-<sha256>
+# Marker writer:   PostToolUse:Agent hook (risk-score-mark.sh) on subagent
+#                  type wr-risk-scorer:external-comms.
+#
+# Composite-marker scheme (combining with wr-voice-tone:agent verdict for
+# the same draft) is deferred until P038 lands its evaluator. This iteration
+# ships the risk-evaluator side as a standalone gate; the two hooks compose
+# at the PreToolUse:Bash matcher level when both packages are installed.
+# See ADR-028 amendment Reassessment Criteria.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=lib/leak-detect.sh
+source "$SCRIPT_DIR/lib/leak-detect.sh"
+
+# ---------- Bypass ----------
+if [ "${BYPASS_RISK_GATE:-0}" = "1" ]; then
+    exit 0
+fi
+
+INPUT=$(cat)
+
+# Extract tool name + tool_input via python3 (consistent with sibling hooks).
+TOOL_NAME=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('tool_name', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+SESSION_ID=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('session_id', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+# Permit silently when session_id is absent; the gate cannot key a marker.
+[ -n "$SESSION_ID" ] || exit 0
+
+# ---------- Surface detection ----------
+SURFACE=""
+DRAFT=""
+
+case "$TOOL_NAME" in
+    Bash)
+        COMMAND=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    print(json.load(sys.stdin).get('tool_input', {}).get('command', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+        # Surface match — most-specific first.
+        if echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh issue create(\s|$)'; then
+            SURFACE="gh-issue-create"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh issue comment(\s|$)'; then
+            SURFACE="gh-issue-comment"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh issue edit(\s|$)'; then
+            SURFACE="gh-issue-edit"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh pr create(\s|$)'; then
+            SURFACE="gh-pr-create"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh pr comment(\s|$)'; then
+            SURFACE="gh-pr-comment"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*gh pr edit(\s|$)'; then
+            SURFACE="gh-pr-edit"
+        elif echo "$COMMAND" | grep -qE 'gh api .*security-advisories'; then
+            SURFACE="gh-api-security-advisories"
+        elif echo "$COMMAND" | grep -qE 'gh api .*/comments'; then
+            SURFACE="gh-api-comments"
+        elif echo "$COMMAND" | grep -qE '(^|;|&&|\|\|)\s*npm publish(\s|$)'; then
+            SURFACE="npm-publish"
+        else
+            exit 0
+        fi
+
+        # Best-effort body extraction: --body 'TEXT' or --body "TEXT" or --field summary='TEXT'.
+        # When absent (npm publish, --body-file), DRAFT="" is acceptable: the agent will
+        # be invoked with command context and read whatever body source the call uses.
+        DRAFT=$(printf '%s' "$COMMAND" | python3 -c "
+import sys, re
+cmd = sys.stdin.read()
+# Match --body '...' or --body \"...\" or --field summary='...'
+for pat in [r\"--body[= ]'([^']*)'\", r'--body[= ]\"([^\"]*)\"',
+            r\"--field [a-zA-Z_]+='([^']*)'\", r'--field [a-zA-Z_]+=\"([^\"]*)\"']:
+    m = re.search(pat, cmd)
+    if m:
+        print(m.group(1))
+        break
+" 2>/dev/null || echo "")
+        ;;
+
+    Write|Edit)
+        FILE_PATH=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    ti = json.load(sys.stdin).get('tool_input', {})
+    print(ti.get('file_path', ti.get('path', '')))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+
+        case "$FILE_PATH" in
+            *.changeset/*.md|*/.changeset/*.md|.changeset/*.md)
+                SURFACE="changeset-author"
+                ;;
+            *)
+                exit 0
+                ;;
+        esac
+
+        DRAFT=$(printf '%s' "$INPUT" | python3 -c "
+import sys, json
+try:
+    ti = json.load(sys.stdin).get('tool_input', {})
+    print(ti.get('content', '') + ti.get('new_string', ''))
+except Exception:
+    print('')
+" 2>/dev/null || echo "")
+        ;;
+
+    *)
+        exit 0
+        ;;
+esac
+
+# ---------- Helpers ----------
+deny_with_reason() {
+    local reason="$1"
+    python3 -c "
+import json, sys
+print(json.dumps({
+    'hookSpecificOutput': {
+        'hookEventName': 'PreToolUse',
+        'permissionDecision': 'deny',
+        'permissionDecisionReason': sys.argv[1]
+    }
+}))
+" "$reason"
+}
+
+permit_with_advisory() {
+    local msg="$1"
+    python3 -c "
+import json, sys
+print(json.dumps({'systemMessage': sys.argv[1]}))
+" "$msg"
+}
+
+# ---------- Advisory-only fallback when policy file is absent ----------
+if [ ! -f "RISK-POLICY.md" ]; then
+    permit_with_advisory "RISK-POLICY.md not found — wr-risk-scorer:external-comms gate is advisory-only on $SURFACE."
+    exit 0
+fi
+
+# ---------- Hard-fail leak-pattern pre-filter ----------
+if ! leak_detect_scan "$DRAFT"; then
+    REASON=$(printf 'BLOCKED (P064 external-comms gate): %s on %s. Remove the leak before retrying. Override only if intentional: BYPASS_RISK_GATE=1.' \
+        "$LEAK_DETECT_REASON" "$SURFACE")
+    deny_with_reason "$REASON"
+    exit 0
+fi
+
+# ---------- Marker-based gate ----------
+SESSION_DIR="${TMPDIR:-/tmp}/claude-risk-${SESSION_ID}"
+mkdir -p "$SESSION_DIR"
+KEY=$(printf '%s\n%s' "$DRAFT" "$SURFACE" | shasum -a 256 | cut -d' ' -f1)
+MARKER="${SESSION_DIR}/external-comms-reviewed-${KEY}"
+
+if [ -f "$MARKER" ]; then
+    exit 0
+fi
+
+# Marker absent — deny + delegate.
+REASON=$(printf 'BLOCKED (P064 external-comms gate): %s draft has not been risk-reviewed. Delegate to wr-risk-scorer:external-comms (subagent_type: '"'"'wr-risk-scorer:external-comms'"'"') with the draft body for review. The PostToolUse hook will mark this draft reviewed when the subagent emits EXTERNAL_COMMS_RISK_VERDICT: PASS. Use /wr-risk-scorer:assess-external-comms for an interactive walkthrough. Override only when intentional: BYPASS_RISK_GATE=1.' \
+    "$SURFACE")
+deny_with_reason "$REASON"
+exit 0

package/hooks/hooks.json

@@ -7,6 +7,7 @@
       { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/secret-leak-gate.sh" }, { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/wip-risk-gate.sh" }] },
       { "matcher": "Bash", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/git-push-gate.sh" }] },
       { "matcher": "Bash", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/risk-score-commit-gate.sh" }] },
+      { "matcher": "Bash|Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/external-comms-gate.sh" }] },
       { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/risk-policy-enforce-edit.sh" }] },
       { "matcher": "ExitPlanMode", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/risk-score-plan-enforce.sh" }] },
       { "matcher": "EnterPlanMode", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/plan-risk-guidance.sh" }] }

package/hooks/lib/leak-detect.sh

@@ -0,0 +1,99 @@
+#!/bin/bash
+# Hybrid leak-pattern pre-filter for external-comms-gate.sh (P064 / ADR-028 amended).
+#
+# Architecture (architect verdict — P064 iteration):
+# - **Regex pre-filter** (this file) catches HIGH-CONFIDENCE leak shapes
+#   (credentials, prod URL prefixes, money/revenue + financial-context tokens).
+#   Hits deny immediately with a specific reason — no subagent round-trip.
+# - **Subagent judgement** (wr-risk-scorer:external-comms) handles ambiguous
+#   prose. Anything this filter does NOT match is delegated to the agent for
+#   context-aware review against RISK-POLICY.md Confidential Information
+#   classes (client names, project names, engagement details, internal
+#   strategy/roadmap detail).
+#
+# Usage:
+#   source lib/leak-detect.sh
+#   if leak_detect_scan "$DRAFT"; then
+#       # No high-confidence hit; delegate to subagent.
+#   else
+#       # Set $LEAK_DETECT_REASON; deny with that reason.
+#   fi
+#
+# Returns 0 when the draft is CLEAN of high-confidence patterns.
+# Returns 1 when a HARD-FAIL pattern is matched. $LEAK_DETECT_REASON
+# is set to a one-line human-readable description of what matched.
+#
+# This is intentionally conservative — false negatives are expected and
+# routed to the subagent. False positives here block the call entirely
+# so the regex set must be high-specificity. Add new patterns only when
+# the false-positive rate is verified low against representative drafts.
+
+LEAK_DETECT_REASON=""
+
+leak_detect_scan() {
+    local draft="$1"
+    LEAK_DETECT_REASON=""
+
+    [ -z "$draft" ] && return 0
+
+    # ---- Credentials (high confidence) ----
+
+    # AWS access keys: AKIA prefix + 16 upper-alphanum chars.
+    if echo "$draft" | grep -qE 'A''KIA[0-9A-Z]{16}'; then
+        LEAK_DETECT_REASON="AWS access key pattern detected in draft"
+        return 1
+    fi
+
+    # GitHub tokens: ghp_/ghs_/gho_/ghu_/ghr_ + 36+ url-safe chars.
+    if echo "$draft" | grep -qE 'g''h[pousr]_[A-Za-z0-9_]{36,}'; then
+        LEAK_DETECT_REASON="GitHub token pattern detected in draft"
+        return 1
+    fi
+
+    # Private keys.
+    if echo "$draft" | grep -qE 'BEGIN[[:space:]]+(RSA|DSA|EC|OPENSSH|PGP)?[[:space:]]*PRIVATE KEY'; then
+        LEAK_DETECT_REASON="Private key block detected in draft"
+        return 1
+    fi
+
+    # Bearer / Authorization headers with non-trivial value.
+    if echo "$draft" | grep -qE '[Bb]earer[[:space:]]+[A-Za-z0-9_.-]{20,}'; then
+        LEAK_DETECT_REASON="Bearer token detected in draft"
+        return 1
+    fi
+
+    # Generic api_key / api_secret / auth_token assignments with literal value.
+    if echo "$draft" | grep -qEi '(api_key|api_secret|auth_token|secret_key)[[:space:]]*[=:][[:space:]]*["\x27][A-Za-z0-9+/=_-]{16,}'; then
+        LEAK_DETECT_REASON="API key/secret/token assignment detected in draft"
+        return 1
+    fi
+
+    # ---- Confidential business metrics (RISK-POLICY.md) ----
+
+    # Revenue / financial figures: $<digits><K|M|B>? near financial-context
+    # keywords (ARR, MRR, revenue, profit). High-specificity to avoid catching
+    # generic price strings ($5 widget) — requires a financial token nearby.
+    if echo "$draft" | grep -qEi '\$[0-9]+([0-9.,]*)[KMB]?\b.{0,40}\b(ARR|MRR|revenue|profit|EBITDA|valuation)\b'; then
+        LEAK_DETECT_REASON="Revenue/financial figure with business-context keyword detected"
+        return 1
+    fi
+    if echo "$draft" | grep -qEi '\b(ARR|MRR|revenue|profit|EBITDA|valuation)\b.{0,40}\$[0-9]+([0-9.,]*)[KMB]?\b'; then
+        LEAK_DETECT_REASON="Business-context keyword paired with revenue/financial figure detected"
+        return 1
+    fi
+
+    # User counts with explicit unit-of-business: <digits><K|M> + (users|customers|MAU|DAU|signups).
+    # Requires comma-formatted thousands or K/M suffix to skip "5 users tested this".
+    if echo "$draft" | grep -qEi '\b[0-9]{1,3}(,[0-9]{3})+\s*(active\s+)?(users|customers|signups|MAU|DAU)\b'; then
+        LEAK_DETECT_REASON="User-count with business-metric keyword detected"
+        return 1
+    fi
+    if echo "$draft" | grep -qEi '\b[0-9]+[KMB]\s*(active\s+)?(users|customers|signups|MAU|DAU)\b'; then
+        LEAK_DETECT_REASON="User-count (K/M/B suffix) with business-metric keyword detected"
+        return 1
+    fi
+
+    # ---- Allowlist-bypass: signed/known-public marketing language is fine ----
+    # No hits — signal CLEAN to the caller.
+    return 0
+}

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/risk-score-mark.sh

@@ -121,4 +121,24 @@ if echo "$SUBAGENT" | grep -qE 'risk-scorer.policy'; then
   esac
 fi
 
+# ---------------------------------------------------------------------------
+# External-comms reviewer (P064 / ADR-028 amended): write per-draft marker
+# keyed on sha256(draft + '\n' + surface). Subagent emits the key; this hook
+# trusts and uses it. Marker file: external-comms-reviewed-<key>.
+# ---------------------------------------------------------------------------
+if echo "$SUBAGENT" | grep -qE 'risk-scorer.external-comms'; then
+  VERDICT_LINE=$(echo "$AGENT_OUTPUT" | grep -E '^EXTERNAL_COMMS_RISK_VERDICT:' | tail -1) || true
+  KEY_LINE=$(echo "$AGENT_OUTPUT" | grep -E '^EXTERNAL_COMMS_RISK_KEY:' | tail -1) || true
+  VERDICT=$(echo "$VERDICT_LINE" | sed 's/^EXTERNAL_COMMS_RISK_VERDICT:[[:space:]]*//' | tr -d '[:space:]')
+  KEY=$(echo "$KEY_LINE" | sed 's/^EXTERNAL_COMMS_RISK_KEY:[[:space:]]*//' | tr -d '[:space:]')
+  # Validate key: 64 hex chars (sha256 output). Reject anything else.
+  if echo "$KEY" | grep -qE '^[0-9a-f]{64}$'; then
+    case "$VERDICT" in
+      PASS) touch "${RDIR}/external-comms-reviewed-${KEY}" ;;
+      FAIL) ;; # Do NOT create marker — draft must be revised
+      *) ;;    # Unknown verdict — fail closed
+    esac
+  fi
+fi
+
 exit 0

package/hooks/test/external-comms-gate.bats

@@ -0,0 +1,174 @@
+#!/usr/bin/env bats
+# Tests for external-comms-gate.sh (P064 / ADR-028 amended).
+# Behavioural: the gate denies outbound prose tool calls until the
+# wr-risk-scorer:external-comms subagent has reviewed the draft and a
+# per-evaluator marker has been written. Hard-fail leak patterns deny
+# immediately without delegation.
+#
+# Note: secret-shaped strings are constructed at runtime via concatenation
+# so this test file itself does not trip the secret-leak-gate hook.
+
+setup() {
+  HOOKS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$HOOKS_DIR/external-comms-gate.sh"
+
+  TEST_SESSION="bats-extcomms-gate-$$-${BATS_TEST_NUMBER}"
+  RDIR="${TMPDIR:-/tmp}/claude-risk-${TEST_SESSION}"
+  rm -rf "$RDIR"
+  mkdir -p "$RDIR"
+
+  # Default: assume RISK-POLICY.md is present in repo root (it is).
+  TEST_PROJECT_DIR="$(mktemp -d)"
+  printf "## Confidential Information\n- Client names\n- Revenue figures\n" \
+    > "$TEST_PROJECT_DIR/RISK-POLICY.md"
+
+  unset BYPASS_RISK_GATE
+
+  # Construct secret-shaped strings at runtime to avoid tripping the
+  # repo's own secret-leak-gate when this file is committed/edited.
+  GH_TOKEN_LIKE="g""hp""_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+  AWS_KEY_LIKE="A""KIA""IOSFODNN7EXAMPLE"
+}
+
+teardown() {
+  rm -rf "$RDIR"
+  rm -rf "$TEST_PROJECT_DIR"
+  unset BYPASS_RISK_GATE
+}
+
+# ---------- Helpers ----------
+
+# Build a PreToolUse:Bash input for a given command via python so quoting is safe.
+build_bash_input() {
+  local cmd="$1"
+  python3 -c "
+import json, sys
+print(json.dumps({
+    'session_id': '$TEST_SESSION',
+    'tool_name': 'Bash',
+    'tool_input': {'command': sys.argv[1]},
+}))
+" "$cmd"
+}
+
+# Build a PreToolUse:Write input for a changeset path with body content.
+build_write_input() {
+  local file_path="$1"
+  local content="$2"
+  python3 -c "
+import json, sys
+print(json.dumps({
+    'session_id': '$TEST_SESSION',
+    'tool_name': 'Write',
+    'tool_input': {'file_path': sys.argv[1], 'content': sys.argv[2]},
+}))
+" "$file_path" "$content"
+}
+
+# Run the hook in a project dir with RISK-POLICY.md present, piping JSON via stdin.
+run_hook() {
+  local input="$1"
+  run bash -c "cd '$TEST_PROJECT_DIR' && printf '%s' \"\$1\" | '$HOOK'" _ "$input"
+}
+
+# ---------- Tests ----------
+
+@test "non-matching Bash command (ls) is allowed silently" {
+  INPUT=$(build_bash_input "ls -la")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "gh issue create with clean draft denies and prompts external-comms delegation (no marker yet)" {
+  INPUT=$(build_bash_input "gh issue create --title T --body 'we observed a build failure on Node 20'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"permissionDecision"* ]]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"wr-risk-scorer:external-comms"* ]]
+}
+
+@test "hard-fail credential pattern (GitHub token) denies immediately with leak reason" {
+  INPUT=$(build_bash_input "gh issue comment 42 --body 'token=${GH_TOKEN_LIKE}'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"permissionDecision"* ]]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"GitHub token"* ]] || [[ "$output" == *"credential"* ]]
+}
+
+@test "hard-fail credential pattern (AWS key) denies immediately" {
+  INPUT=$(build_bash_input "gh pr create --title T --body 'AWS=${AWS_KEY_LIKE}'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"AWS"* ]] || [[ "$output" == *"credential"* ]]
+}
+
+@test "BYPASS_RISK_GATE=1 short-circuits the deny" {
+  INPUT=$(build_bash_input "gh issue create --title T --body 'we observed a build failure'")
+  run bash -c "cd '$TEST_PROJECT_DIR' && BYPASS_RISK_GATE=1 printf '%s' \"\$1\" | BYPASS_RISK_GATE=1 '$HOOK'" _ "$INPUT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "marker present for matching draft+surface key allows the call" {
+  DRAFT="we observed a build failure on Node 20"
+  SURFACE="gh-issue-create"
+  KEY=$(printf '%s\n%s' "$DRAFT" "$SURFACE" | shasum -a 256 | cut -d' ' -f1)
+  touch "${RDIR}/external-comms-reviewed-${KEY}"
+
+  INPUT=$(build_bash_input "gh issue create --title T --body '$DRAFT'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "RISK-POLICY.md absent yields advisory-only mode (permits)" {
+  rm -f "$TEST_PROJECT_DIR/RISK-POLICY.md"
+  INPUT=$(build_bash_input "gh issue create --title T --body 'we observed a failure'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  # Must NOT deny when policy file is absent.
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  [[ "$output" != *"\"permissionDecision\":\"deny\""* ]]
+}
+
+@test "PreToolUse:Write on .changeset/*.md with revenue leak content denies" {
+  INPUT=$(build_write_input ".changeset/wr-risk-scorer-extcomms.md" "Add gate; covers Acme Corp \$2.4M ARR client.")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deny"* ]]
+}
+
+@test "PreToolUse:Write on .changeset/*.md with clean content denies-then-delegates (no marker yet)" {
+  INPUT=$(build_write_input ".changeset/wr-risk-scorer-extcomms.md" "Add external-comms gate covering gh issue and pr surfaces.")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"wr-risk-scorer:external-comms"* ]]
+}
+
+@test "PreToolUse:Write on a non-changeset path is ignored" {
+  INPUT=$(build_write_input "src/foo.ts" "Acme Corp client revenue \$2.4M")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "gh api security-advisories triggers the gate" {
+  INPUT=$(build_bash_input "gh api repos/foo/bar/security-advisories --method POST --field summary='leak via X'")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"wr-risk-scorer:external-comms"* ]]
+}
+
+@test "npm publish triggers the gate" {
+  INPUT=$(build_bash_input "npm publish")
+  run_hook "$INPUT"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"deny"* ]]
+  [[ "$output" == *"wr-risk-scorer:external-comms"* ]]
+}

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",
+  "version": "0.4.2-preview.218",
   "description": "Pipeline risk scoring, commit/push gates, and secret leak detection",
   "bin": {
     "windyroad-risk-scorer": "./bin/install.mjs"

package/skills/assess-external-comms/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: wr-risk-scorer:assess-external-comms
+description: On-demand external-comms risk review. Reviews a draft of an outbound prose tool call (gh issue/pr body, security advisory, npm publish content, or .changeset/*.md body) for confidential-information leaks per RISK-POLICY.md. Delegates to wr-risk-scorer:external-comms and pre-satisfies the external-comms-gate marker for the current session.
+allowed-tools: Read, Glob, Grep, Bash, AskUserQuestion, Skill
+---
+
+# External-Comms Risk Assessment Skill
+
+Run a confidential-information leak review on demand against any drafted outbound prose — outside a hook gate trigger. Pre-satisfies the `external-comms-gate.sh` marker for the current session so the gated tool call (gh issue/pr/api/npm publish/changeset write) proceeds without re-prompting.
+
+This skill is **read-only**. It does not commit, push, or modify files. The marker is written automatically by the `PostToolUse:Agent` hook (`risk-score-mark.sh`) after the subagent completes — the skill never writes to `${TMPDIR:-/tmp}/claude-risk-*` directly.
+
+## When to use
+
+- Before drafting a `gh issue create`/`gh pr create`/`gh issue comment`/`gh pr comment` to a third-party repo.
+- Before drafting a `gh api .../security-advisories` body for a vendor private channel.
+- Before authoring a `.changeset/*.md` body that will land in CHANGELOG.md and every published npm tarball (P073).
+- Before `npm publish` when the README diff is non-trivial.
+- After hitting the external-comms gate's deny-and-delegate prompt: this skill is the structured walkthrough that closes the loop.
+
+## Steps
+
+### 1. Parse arguments
+
+Read `$ARGUMENTS` for either:
+
+- A draft body verbatim (e.g. the user pastes the prose they're about to post).
+- A surface hint (`gh-issue-create`, `gh-pr-comment`, `gh-api-security-advisories`, `gh-issue-edit`, `gh-pr-edit`, `gh-issue-comment`, `gh-pr-create`, `gh-api-comments`, `npm-publish`, `changeset-author`).
+- A destination hint (`anthropics/claude-code#52831`, `vendor private channel`, `npm public registry`).
+
+If both draft and surface are present, proceed to step 3. If either is missing, step 2.
+
+### 2. Resolve missing context
+
+If the draft is missing, use `AskUserQuestion`:
+
+> "What draft do you want me to review? Paste the body verbatim — I will pass it to the external-comms reviewer."
+
+If the surface is missing AND cannot be inferred from context (e.g. user just said "before I post this comment"), use `AskUserQuestion`:
+
+- header: "Target surface"
+- options:
+  1. `gh issue create` (public third-party repo)
+  2. `gh issue comment` (public third-party repo)
+  3. `gh pr create` / `gh pr comment` (public third-party repo)
+  4. `gh api .../security-advisories` (vendor private channel)
+  5. `npm publish` (permanently published artefact)
+  6. `.changeset/*.md` (lands in CHANGELOG + Release PR + every npm tarball)
+
+Do not ask if the surface is obvious from the conversation context.
+
+### 3. Construct the review prompt
+
+Build a self-contained prompt for the `wr-risk-scorer:external-comms` subagent that includes:
+
+- The **draft body** verbatim (between explicit `<draft>...</draft>` markers so the agent's substring extraction is unambiguous).
+- The **target surface** (one of the canonical strings above).
+- The **destination** when known.
+- A reminder to compute `EXTERNAL_COMMS_RISK_KEY = sha256(draft + '\n' + surface)`.
+
+### 4. Delegate to wr-risk-scorer:external-comms
+
+Invoke the subagent via the `Skill` tool:
+
+```
+subagent_type: wr-risk-scorer:external-comms
+prompt: <constructed review prompt from step 3>
+```
+
+Wait for the subagent to complete. The subagent will output a structured verdict block (`EXTERNAL_COMMS_RISK_VERDICT: PASS|FAIL` + `EXTERNAL_COMMS_RISK_KEY: <sha>` + optional `EXTERNAL_COMMS_RISK_REASON: ...`). The `PostToolUse:Agent` hook (`risk-score-mark.sh`) reads that output and writes the marker automatically.
+
+**Do not write to `${TMPDIR:-/tmp}/claude-risk-*` yourself.** The hook is the only correct mechanism.
+
+### 5. Present results
+
+Present the full review report to the user. Highlight:
+
+- The verdict (PASS / FAIL).
+- Each Confidential Information class the draft matched against (FAIL only).
+- The exact substrings that triggered each finding (FAIL only).
+- Whether the gate is now pre-satisfied for the current session for this exact draft+surface key (PASS only): "The next attempt to <surface> with this draft body will proceed without re-prompting."
+
+### 6. Above-appetite handling (ADR-013 Rule 6)
+
+If the verdict is FAIL, do NOT auto-rewrite the draft. Use `AskUserQuestion`:
+
+- header: "Leak detected — next step"
+- options:
+  1. `Rewrite the draft and re-review` — return to step 1 with the rewritten body.
+  2. `Move to a private channel` — direct the user to a non-public surface (vendor private email, internal Slack, etc.) where the leak does not apply.
+  3. `Override anyway` — set `BYPASS_RISK_GATE=1` for the next gated tool call. Reserved for cases where the user has confirmed the content is safe to publish (e.g. the "client name" is actually their own org).
+  4. `Cancel` — abandon the post.
+
+Do not make the decision unilaterally — per ADR-013 Rule 1, all leak/no-leak judgement calls outside the regex pre-filter belong to the user.
+
+$ARGUMENTS