@windyroad/risk-scorer 0.3.1 → 0.3.2-preview.77

package/agents/pipeline.md

@@ -111,13 +111,17 @@ Do NOT emit: "Suggested Actions", "Your call:", advisory warnings, back-pressure
 
 When ANY cumulative score exceeds appetite (> 4), emit a structured `RISK_REMEDIATIONS:` block after the `RISK_SCORES:` line. This gives the calling skill machine-readable input for structured decision prompts.
 
-Format:
+Format (5 columns — machine-readable for structured AskUserQuestion prompts in calling skills):
 ```
 RISK_REMEDIATIONS:
-- R1 | <description of remediation> | <files affected>
-- R2 | <description of remediation> | <files affected>
+- R1 | <description of remediation> | <effort S/M/L> | <risk_delta -N> | <files affected>
+- R2 | <description of remediation> | <effort S/M/L> | <risk_delta -N> | <files affected>
 ```
 
+Column definitions:
+- **effort**: estimated size of the remediation — S (< 1h, single file), M (1-4h, few files), L (> 4h, multiple files)
+- **risk_delta**: estimated reduction in residual risk if this remediation is applied (e.g., `-3` means risk drops by 3 points)
+
 Include downstream back-pressure in the remediation list:
 - **Commit**: If adding this commit would push the push queue risk >= 5, include a remediation to split the commit.
 - **Push**: If pushing would push the release queue risk >= 5, include a remediation to release first.

package/agents/plan.md

@@ -49,12 +49,16 @@ You are the Risk Scorer in plan review mode. Assess both the plan's own risk AND
 
 End your report with `RISK_VERDICT: PASS` or `RISK_VERDICT: FAIL` on its own line. A PostToolUse hook reads this and writes the marker files — do NOT write files yourself.
 
-On FAIL, emit a structured `RISK_REMEDIATIONS:` block after the verdict:
+On FAIL, emit a structured `RISK_REMEDIATIONS:` block after the verdict (5 columns — machine-readable for structured AskUserQuestion prompts in calling skills):
 ```
 RISK_REMEDIATIONS:
-- R1 | <description of what the plan must add/change> | <affected area>
+- R1 | <description of what the plan must add/change> | <effort S/M/L> | <risk_delta -N> | <affected area>
 ```
 
+Column definitions:
+- **effort**: estimated size of the remediation — S (< 1h, single file), M (1-4h, few files), L (> 4h, multiple files)
+- **risk_delta**: estimated reduction in residual risk if this remediation is applied
+
 Do NOT emit free-text "consider" or "you should" prose. The structured block is the only output for above-appetite guidance.
 
 ## Control Discovery

package/agents/test/risk-scorer-structured-remediations.bats

@@ -0,0 +1,100 @@
+#!/usr/bin/env bats
+# Doc-lint guard: risk-scorer agent prompts must define a structured
+# machine-readable RISK_REMEDIATIONS block with the full 5-column format.
+#
+# Structural assertions — Permitted Exception to the source-grep ban (ADR-005 / P011).
+# These tests assert that agent specification documents conform to the
+# structured-interaction contract (ADR-013) and the machine-readable format
+# required by P021.
+#
+# Background: P021 identified that above-appetite risk-scorer output used
+# free-text "Your call:" prose. The fix defined a structured RISK_REMEDIATIONS:
+# block. This test guards that all three scoring modes (pipeline, wip, plan)
+# define the block AND include the full 5-column format so calling skills
+# can render structured option prompts with effort and risk-delta context.
+#
+# Cross-reference:
+#   ADR-013: docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md
+#   P021:    docs/problems/021-governance-skill-structured-prompts.known-error.md
+#   @jtbd JTBD-001 (enforce governance without slowing down)
+#   @jtbd JTBD-002 (ship with confidence — structured remediations are auditable)
+
+setup() {
+  AGENTS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  PIPELINE="${AGENTS_DIR}/pipeline.md"
+  WIP="${AGENTS_DIR}/wip.md"
+  PLAN="${AGENTS_DIR}/plan.md"
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# pipeline.md: above-appetite structured output
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "pipeline.md defines RISK_REMEDIATIONS block" {
+  # Must emit a structured block, not free-text, above appetite (ADR-013 Rule 1).
+  run grep -q "RISK_REMEDIATIONS:" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+@test "pipeline.md RISK_REMEDIATIONS format includes effort column" {
+  # 5-column format: id | description | effort (S/M/L) | risk_delta (-N) | files_touched
+  # This column allows calling skills to size each remediation and present
+  # a structured AskUserQuestion with effort context.
+  run grep -q "effort" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+@test "pipeline.md RISK_REMEDIATIONS format includes risk_delta column" {
+  # risk_delta lets calling skills show how much each remediation reduces score.
+  run grep -q "risk_delta" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+@test "pipeline.md defines Below-Appetite Output Rule" {
+  # Below appetite: silent pass, no advisory prose (ADR-013 Rule 5).
+  run grep -q "Below-Appetite" "$PIPELINE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# wip.md: above-appetite structured output
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "wip.md defines RISK_REMEDIATIONS block" {
+  run grep -q "RISK_REMEDIATIONS:" "$WIP"
+  [ "$status" -eq 0 ]
+}
+
+@test "wip.md RISK_REMEDIATIONS format includes effort column" {
+  run grep -q "effort" "$WIP"
+  [ "$status" -eq 0 ]
+}
+
+@test "wip.md RISK_REMEDIATIONS format includes risk_delta column" {
+  run grep -q "risk_delta" "$WIP"
+  [ "$status" -eq 0 ]
+}
+
+@test "wip.md defines Below-Appetite Rule" {
+  run grep -q "Below-Appetite" "$WIP"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# plan.md: FAIL-verdict structured output
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "plan.md defines RISK_REMEDIATIONS block" {
+  run grep -q "RISK_REMEDIATIONS:" "$PLAN"
+  [ "$status" -eq 0 ]
+}
+
+@test "plan.md RISK_REMEDIATIONS format includes effort column" {
+  run grep -q "effort" "$PLAN"
+  [ "$status" -eq 0 ]
+}
+
+@test "plan.md RISK_REMEDIATIONS format includes risk_delta column" {
+  run grep -q "risk_delta" "$PLAN"
+  [ "$status" -eq 0 ]
+}

package/agents/wip.md

@@ -53,14 +53,19 @@ If cumulative risk is **within appetite** (< 5): provide the assessment table an
 
 If cumulative risk **exceeds appetite** (>= 5): provide the assessment table, then emit a structured `RISK_REMEDIATIONS:` block with specific risk-reducing actions:
 
+Format (5 columns — machine-readable for structured AskUserQuestion prompts in calling skills):
 ```
 RISK_REMEDIATIONS:
-- R1 | Commit current changes to move WIP forward | <uncommitted files>
-- R2 | Write tests for <risk item from report> | <test file to create/extend>
-- R3 | Address release report risk <X> before adding more changes | <affected files>
-- R4 | Push commits to get CI feedback | N/A
+- R1 | Commit current changes to move WIP forward | S | -2 | <uncommitted files>
+- R2 | Write tests for <risk item from report> | M | -3 | <test file to create/extend>
+- R3 | Address release report risk <X> before adding more changes | M | -4 | <affected files>
+- R4 | Push commits to get CI feedback | S | -1 | N/A
 ```
 
+Column definitions:
+- **effort**: estimated size of the remediation — S (< 1h, single file), M (1-4h, few files), L (> 4h, multiple files)
+- **risk_delta**: estimated reduction in residual risk if this remediation is applied (e.g., `-3` means risk drops by 3 points)
+
 Do NOT emit free-text suggestions as prose. The structured block is the only output for above-appetite guidance.
 
 The verdict is `RISK_VERDICT: PAUSE`. This blocks the next edit until the risk is addressed.

package/package.json

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