@windyroad/risk-scorer 0.5.0 → 0.6.0-preview.283

package/.claude-plugin/plugin.json

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

package/README.md

@@ -51,6 +51,7 @@ This creates a `RISK-POLICY.md` tailored to your project, defining impact levels
 | `wip-risk-mark.sh` | After edit | Records WIP risk assessment |
 | `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 |
+| `risk-slide-marker.sh` | Agent or Bash | Slides the review marker forward across non-edit operations so an active review session is not invalidated by intervening Bash or sub-agent calls |
 
 ## Agents
 
@@ -72,7 +73,8 @@ The plugin includes six specialised agents:
 | `/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:create-risk` | Create a standing-risk register entry (interactive authoring; orchestrator-driven prefilled invocation via `--slug` / `--prefill` flags per ADR-059) |
+| `/wr-risk-scorer:bootstrap-catalog` | Bootstrap `docs/risks/` register from existing `.risk-reports/` corpus per ADR-059 — walks reports, dedupes by ADR-056 slug, emits one `R<NNN>-<slug>.active.md` per unique slug. Idempotent. Auto-triggers from `/install-updates` Step 6.5.1 when register is empty + `RISK-POLICY.md` present + `.risk-reports/` non-empty |
 | `/wr-risk-scorer:update-policy` | Generate or update `RISK-POLICY.md` |
 
 ## External-comms gate
@@ -106,6 +108,24 @@ 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).
 
+## Jobs to be Done
+
+This plugin serves the [Jobs to be Done](../../docs/jtbd/) below. Per [ADR-051](../../docs/decisions/051-jtbd-anchored-readme-with-drift-advisory.proposed.md), the persona-grouped JTBD anchor is the canonical source of truth for the README's value framing.
+
+### Tech lead / consultant
+
+- **[JTBD-202 Run Pre-Flight Governance Checks Before Release or Handover](../../docs/jtbd/tech-lead/JTBD-202-pre-flight-governance-check.proposed.md)** — `/wr-risk-scorer:assess-release` produces a structured release-readiness score (commit, push, release layers) that is attachable to a release note or handover doc.
+
+### Solo developer
+
+- **[JTBD-001 Enforce Governance Without Slowing Down](../../docs/jtbd/solo-developer/JTBD-001-enforce-governance.proposed.md)** — pipeline risk is scored on every edit, commit, and push without manual invocation; secret-leak detection runs in the same gate.
+- **[JTBD-002 Ship AI-Assisted Code with Confidence](../../docs/jtbd/solo-developer/JTBD-002-ship-with-confidence.proposed.md)** — every release passes through ISO 31000-aligned criteria defined in the project's own `RISK-POLICY.md` so the safety bar is the team's, not the agent's.
+- **[JTBD-005 Invoke Governance Assessments On Demand](../../docs/jtbd/solo-developer/JTBD-005-assess-on-demand.proposed.md)** — `/wr-risk-scorer:assess-wip`, `assess-release`, and `assess-external-comms` give an on-demand assessment surface outside the hook gate cycle.
+
+### Plugin user
+
+- **[JTBD-302 Trust That the README Describes the Plugin I Just Installed](../../docs/jtbd/plugin-user/JTBD-302-trust-readme-describes-installed-behaviour.proposed.md)** — this README is anchored on current JTBD job IDs; drift between prose and shipped behaviour is detectable at retro time per ADR-051.
+
 ## Updating and Uninstalling
 
 ```bash

package/agents/pipeline.md

@@ -42,6 +42,32 @@ You receive structured pipeline state context with these sections:
 - **UNRELEASED CHANGES**: Changeset count and cumulative diff
 - **STALE FILES**: Modified files uncommitted for over 24h
 
+## Catalog Consumption Protocol (ADR-059)
+
+Before scoring, READ the standing-risk catalog at `docs/risks/` and filter to risks applicable to THIS action. The catalog is the persistent record of risk classes the project has surfaced; consuming it eliminates the wasted-effort cost of re-deriving risk classes on every assessment AND closes the missed-risk-class hazard (forgetting a class the agent surfaced before because it didn't think of it this time). Per `RISK-POLICY.md` `## Risk Catalog` section.
+
+**Filter mechanism — hybrid (slug-token-match primary, judgement fallback):**
+
+1. **Slug-token-match (primary, deterministic)** — for each `R<NNN>-<slug>.active.md` entry in `docs/risks/`, extract the slug from the filename. Tokenise the slug (split on hyphens). If any token appears in the diff content, commit message, or recent prompt context, the entry is **slug-matched** for this action.
+2. **Free-form judgement (fallback)** — for entries the slug-match path missed, READ the entry's `## Description` section and judge applicability against the diff/commit/prompt context. If the description names a risk shape that THIS action plausibly triggers, the entry is **judgement-matched**.
+3. **Logging** — record the match path on each matched risk-item so the next agent can carry it forward (see Risk Item Format below).
+
+**Residual reconciliation:**
+
+- The catalog entry's residual is the **lifetime baseline** under documented controls (the controls present in the project as a whole).
+- THIS action's residual is the baseline modulated by the controls present (or absent) in this specific change.
+- The pipeline's `RISK_SCORES:` output MUST carry the per-action residual, NOT the catalog's lifetime baseline. Gates fire on per-action thresholds.
+- The catalog's residual is meaningful CONTEXT: log it as `Catalog baseline:` in the risk-item block so reviewers can compare the lifetime baseline against this-action's residual.
+
+**Empty catalog handling:**
+
+- If `docs/risks/` is empty (no `R*-*.active.md` files) BUT `RISK-POLICY.md` is present AND `.risk-reports/` is non-empty, emit a one-line nudge in the report body (NOT the `RISK_SCORES:` line): `"Risk register is empty; run /install-updates or /wr-risk-scorer:bootstrap-catalog to bootstrap from .risk-reports/ corpus."` Do NOT halt; do NOT block; do NOT inflate the per-action residual to compensate.
+- If `docs/risks/` is empty AND `RISK-POLICY.md` is absent, the project hasn't opted into the catalog framing. Silent skip the catalog protocol; proceed with regeneration-from-scratch as before this protocol landed.
+
+**Per-run hit-rate observability:**
+
+After scoring, emit a `CATALOG_HIT_RATE: matched=N missed=M` line to the report (where `matched` counts catalog-matched risks AND `missed` counts risks the agent surfaced this run that weren't in the catalog — those become `RISK_REGISTER_HINT:` candidates per ADR-056). Below ~30% sustained hit rate is a Reassessment signal per ADR-059.
+
 ## Cumulative Risk Report
 
 The report MUST assess risk cumulatively, building up from the release queue:
@@ -81,11 +107,15 @@ Commit score >= push score >= release score (risk accumulates upward).
 - Inherent impact: N/5 (Label) - [why]
 - Inherent likelihood: N/5 (Label) - [why]
 - Inherent risk: N/25 (Label)
+- Catalog match: [slug-token | judgement | none]
+- Catalog baseline: R<NNN> residual=N/25 (Label) — [if matched, cite the catalog entry's lifetime residual; omit line entirely when match=none]
 - Controls:
   - [Specific test file/scenario or hook name] - reduces [dimension] from N to N because [rationale]
 - **Residual risk: N/25 (Label)**
 ```
 
+The `Catalog match:` and `Catalog baseline:` lines (ADR-059) make the catalog consumption auditable per risk-item. `slug-token` indicates the primary deterministic match; `judgement` indicates the fallback applicability judgement; `none` indicates the risk wasn't in the catalog (and the agent should consider whether to emit a `RISK_REGISTER_HINT:` for it per ADR-056).
+
 ### Score File Values
 
 - Commit score: Layer 3 cumulative (highest)

package/agents/test/risk-scorer-catalog-consumption.bats

@@ -0,0 +1,138 @@
+#!/usr/bin/env bats
+# Doc-lint guard: pipeline scorer MUST define the catalog consumption protocol
+# per ADR-059 — read docs/risks/ first, hybrid filter (slug-token primary,
+# judgement fallback), residual reconciliation (per-action residual in
+# RISK_SCORES, catalog lifetime baseline in risk-item block), per-run
+# CATALOG_HIT_RATE observability line.
+#
+# Structural assertions — Permitted Exception to the source-grep ban (ADR-005 / P011).
+# Agent prompts are specification documents; behavioural verification of an LLM's
+# output is out of scope for bats — the contract document is what consuming
+# orchestrators and reviewers rely on. This pattern matches existing tests in
+# this directory (see risk-scorer-register-hint.bats).
+#
+# Cross-reference:
+#   ADR-059: docs/decisions/059-pipeline-consume-catalog-and-bootstrap-from-reports.proposed.md
+#   ADR-056: docs/decisions/056-risk-register-back-channel-write-contract.proposed.md (slug primitive consumed)
+#   ADR-015: docs/decisions/015-on-demand-assessment-skills.proposed.md (pure-scorer contract preserved)
+#   ADR-026: docs/decisions/026-agent-output-grounding.proposed.md
+#   P168:    docs/problems/168-risk-scorer-doesnt-consume-catalog-or-bootstrap.known-error.md
+#   P167:    docs/problems/167-risk-register-aggregate-reads-as-dont-ship.known-error.md
+#   @jtbd JTBD-001 (enforce governance without slowing down — closes missed-risk-class hazard)
+#   @jtbd JTBD-202 (pre-flight governance — catalog as ISO 31000/27001 audit-trail artefact)
+
+setup() {
+  AGENTS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  PIPELINE="${AGENTS_DIR}/pipeline.md"
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Contract surface: Catalog Consumption Protocol section exists
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "pipeline.md defines Catalog Consumption Protocol section" {
+  run grep -q "## Catalog Consumption Protocol" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+@test "pipeline.md cites ADR-059 in the catalog protocol section" {
+  run grep -q "ADR-059" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+@test "pipeline.md names docs/risks/ as the catalog read source" {
+  run grep -qE "READ.*docs/risks/|read.*standing-risk catalog at .docs/risks/" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Hybrid filter: slug-token-match primary, judgement fallback
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "pipeline.md describes slug-token-match as primary filter path" {
+  run grep -qE "[Ss]lug-token-match.*primary|[Ss]lug-token-match \(primary" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+@test "pipeline.md describes judgement as fallback filter path" {
+  run grep -qE "[Jj]udgement.*fallback|[Ff]ree-form judgement.*fallback" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Risk Item Format: Catalog match + Catalog baseline lines
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "pipeline.md Risk Item Format includes Catalog match line" {
+  run grep -q "Catalog match:" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+@test "pipeline.md Risk Item Format includes Catalog baseline line" {
+  run grep -q "Catalog baseline:" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+@test "pipeline.md names the three Catalog match values" {
+  # slug-token | judgement | none — matches the ADR-059 verdict E3 contract.
+  run grep -qE "slug-token.*judgement.*none|slug-token \| judgement \| none" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Residual reconciliation: per-action residual in RISK_SCORES, baseline contextual
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "pipeline.md names per-action residual as RISK_SCORES output" {
+  run grep -qE "RISK_SCORES.*per-action residual|per-action residual.*RISK_SCORES" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+@test "pipeline.md describes catalog lifetime baseline as context not RISK_SCORES" {
+  run grep -qE "lifetime baseline|Catalog baseline:" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Hit-rate observability: CATALOG_HIT_RATE line emitted per run
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "pipeline.md defines CATALOG_HIT_RATE observability line" {
+  run grep -q "CATALOG_HIT_RATE:" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+@test "pipeline.md names the CATALOG_HIT_RATE matched + missed columns" {
+  run grep -qE "matched=N missed=M|CATALOG_HIT_RATE: matched" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Empty catalog handling: nudge but do NOT halt or inflate residual
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "pipeline.md handles empty catalog with nudge not halt" {
+  run grep -qE "[Ee]mpty catalog|catalog is empty.*nudge|do NOT halt" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+@test "pipeline.md cites bootstrap-catalog skill in empty catalog nudge" {
+  run grep -qE "bootstrap-catalog|/install-updates.*bootstrap" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Pure-scorer contract preserved: no Write tool grant added
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "pipeline.md preserves pure-scorer contract (Read + Glob only)" {
+  # The agent's tool grant must remain Read + Glob per ADR-015.
+  # Adding Write would break the architectural boundary ADR-059 verdict F2 preserves.
+  run grep -qE "^  - Read$" "$PIPELINE"
+  [ "$status" -eq 0 ]
+  run grep -qE "^  - Glob$" "$PIPELINE"
+  [ "$status" -eq 0 ]
+  # Negative: Write tool MUST NOT appear in tool grant
+  run grep -qE "^  - Write$" "$PIPELINE"
+  [ "$status" -ne 0 ]
+}

package/bin/wr-risk-scorer-extract-risks-from-reports

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Shim: dispatches to the canonical script body per ADR-049 ($PATH-resolved bin/).
+exec "$(dirname "$(readlink -f "${BASH_SOURCE[0]:-$0}")")/../scripts/extract-risks-from-reports.sh" "$@"

package/package.json

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