@windyroad/itil 0.24.0-preview.268 → 0.24.1-preview.270

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-itil",
-  "version": "0.24.0",
+  "version": "0.24.1",
   "description": "ITIL-aligned IT service management for Claude Code"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.24.0-preview.268",
+  "version": "0.24.1-preview.270",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"
@@ -24,6 +24,7 @@
     "agents/",
     "hooks/",
     "skills/",
+    "scripts/",
     ".claude-plugin/",
     "lib/"
   ]

package/scripts/check-problems-readme-budget.sh

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# packages/itil/scripts/check-problems-readme-budget.sh
+#
+# Diagnose-only advisory script for the docs/problems/README.md "Last
+# reviewed" line (line 3). Sibling to P099's
+# packages/retrospective/scripts/check-briefing-budgets.sh on a
+# different surface — both apply ADR-040 line 92's reusable triplet
+# (read-only diagnostic + behavioural bats + ADR-tier-budget
+# enforcement clause) to an accumulator-doc surface.
+#
+# Usage:
+#   check-problems-readme-budget.sh [<readme-path>]
+#
+# Default <readme-path> is ./docs/problems/README.md.
+# Threshold is read from PROBLEMS_README_LINE3_MAX_BYTES (default 5120
+# — matches ADR-040 Tier 3 Tier 3 envelope; the soft per-fragment cap
+# is 1024 bytes, enforced by the SKILL.md authoring contracts in
+# manage-problem / transition-problem / transition-problems /
+# review-problems / reconcile-readme).
+#
+# Exit codes:
+#   0 = always (advisory only — overflow is signal, not failure)
+#   2 = parse error (README path missing or unreadable)
+#
+# Output format on overflow (one line, terse machine-readable per
+# ADR-038 progressive-disclosure budget):
+#   OVER <readme-path> line=3 bytes=<N> threshold=<N>
+#
+# Output is empty (no lines) when line 3 is under the threshold.
+#
+# Read-only — does NOT mutate the README. Truncation is owned by the
+# per-operation refresh contracts in manage-problem Step 5 P094 +
+# Step 7 P062 (and the sibling skills).
+#
+# @problem P134
+# @adr ADR-040 (Session-start briefing surface — Tier 3 budget; line 92's
+#   reusable-pattern note explicitly names "problems index" as a
+#   candidate surface for this triplet)
+# @adr ADR-038 (Progressive disclosure — per-row terse budget)
+# @adr ADR-013 Rule 6 (non-interactive fail-safe — advisory exit 0)
+# @adr ADR-005 (Plugin testing strategy)
+# @jtbd JTBD-001 / JTBD-006 / JTBD-101
+
+set -uo pipefail
+
+README_PATH="${1:-docs/problems/README.md}"
+THRESHOLD="${PROBLEMS_README_LINE3_MAX_BYTES:-5120}"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -f "$README_PATH" ]; then
+  echo "check-problems-readme-budget: README not found: $README_PATH" >&2
+  exit 2
+fi
+
+# ── Measure line 3 byte size ────────────────────────────────────────────────
+# `awk 'NR==3'` extracts line 3 verbatim; the trailing newline that awk
+# emits is not part of the line's content. We use printf '%s' to feed
+# the line to wc -c with no added newline so the byte count matches the
+# in-file content of line 3. Empty / missing line 3 yields 0 bytes.
+
+line3="$(awk 'NR==3' "$README_PATH")"
+bytes=$(printf '%s' "$line3" | wc -c | tr -d ' ')
+
+if [ "$bytes" -ge "$THRESHOLD" ] && [ "$bytes" -gt 0 ]; then
+  echo "OVER $README_PATH line=3 bytes=$bytes threshold=$THRESHOLD"
+fi
+
+# Edge case: threshold of 0 with non-empty line 3 — still report (sanity
+# path exercised in bats). The first guard above requires bytes > 0 so
+# we never emit OVER for an empty/missing line 3.
+
+exit 0

package/scripts/classify-readme-drift.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# packages/itil/scripts/classify-readme-drift.sh
+#
+# Classify reconcile-readme.sh exit-1 drift output as either
+# inline-refresh-deferrable (covered by uncommitted ticket renames in the
+# working tree — in-flow P094/P062 refresh will land the README correction
+# in the upcoming commit per ADR-014) or halt-route-reconcile (committed
+# cross-session drift — must route to /wr-itil:reconcile-readme).
+#
+# Usage:
+#   classify-readme-drift.sh <drift-stdout-file> [<problems-dir>]
+#
+# <drift-stdout-file>: path to a file containing the captured stdout of
+# `reconcile-readme.sh` (one structured drift line per row — `DRIFT`,
+# `MISSING`, `STALE`, or `MISMATCH`).
+#
+# <problems-dir>: defaults to ./docs/problems. Used by `git status
+# --porcelain` to scope the staged-rename probe.
+#
+# Output (stdout, single classification line):
+#   INLINE_REFRESH covered=<N>            — every drift ID is the destination
+#                                            of a staged rename in the working
+#                                            tree; defer to in-flow P094/P062
+#                                            refresh per ADR-014.
+#   HALT_ROUTE_RECONCILE uncovered=<N>    — at least one drift ID is NOT
+#                                            covered by a working-tree rename;
+#                                            committed cross-session drift OR
+#                                            mixed; route to
+#                                            /wr-itil:reconcile-readme.
+#
+# Exit codes:
+#   0 = INLINE_REFRESH
+#   1 = HALT_ROUTE_RECONCILE
+#   2 = parse error (drift-stdout-file missing or empty)
+#
+# @problem P149 — manage-problem Step 0 reconcile halt-on-drift directive
+#                 doesn't distinguish uncommitted-rename-rooted drift from
+#                 committed cross-session drift; this script is the
+#                 detection mechanism that makes the carve-out behavioural.
+# @adr ADR-014 (single-commit grain — the carve-out preserves it for the
+#               in-flow path while keeping cross-session drift safety)
+# @adr ADR-013 Rule 6 (AFK fail-safe — committed drift still routes to
+#                       /wr-itil:reconcile-readme; only the inline path
+#                       is added)
+# @adr ADR-038 (progressive disclosure — output is a single terse line)
+# @jtbd JTBD-006 (Progress the Backlog While I'm Away — AFK loop continuity)
+# @jtbd JTBD-001 (Enforce Governance Without Slowing Down — single-commit grain)
+
+set -uo pipefail
+
+DRIFT_FILE="${1:-}"
+PROBLEMS_DIR="${2:-docs/problems}"
+
+if [ -z "$DRIFT_FILE" ]; then
+  echo "USAGE: classify-readme-drift.sh <drift-stdout-file> [<problems-dir>]" >&2
+  exit 2
+fi
+
+if [ ! -f "$DRIFT_FILE" ]; then
+  echo "PARSE_ERROR: drift-stdout-file not found: $DRIFT_FILE" >&2
+  exit 2
+fi
+
+# ── Extract drifting IDs from the script's structured output ────────────────
+# Each line is one of:
+#   DRIFT    P<NNN> wsjf-rankings: ...
+#   MISSING  P<NNN> wsjf-rankings: ...
+#   MISSING  P<NNN> verification-queue: ...
+#   STALE    P<NNN> verification-queue: ...
+#   MISMATCH P<NNN> closed: ...
+DRIFT_IDS="$(grep -oE 'P[0-9]{3}' "$DRIFT_FILE" 2>/dev/null | sort -u)"
+
+if [ -z "$DRIFT_IDS" ]; then
+  echo "PARSE_ERROR: drift-stdout-file empty (no P<NNN> tokens): $DRIFT_FILE" >&2
+  exit 2
+fi
+
+# ── Build set of IDs covered by staged renames in the working tree ──────────
+# `git status --porcelain` v1 emits rename lines as:
+#   R  <old-path> -> <new-path>
+#   RM <old-path> -> <new-path>   (rename + unstaged modification)
+# We match the destination path's ticket ID — the post-rename status is what
+# the in-flow P094/P062 refresh will reconcile in the upcoming commit.
+RENAMED_IDS=""
+if git rev-parse --git-dir >/dev/null 2>&1; then
+  RENAMED_IDS="$(
+    git status --porcelain "$PROBLEMS_DIR" 2>/dev/null \
+      | awk '/^R/' \
+      | sed 's|.*-> ||' \
+      | sed "s|^${PROBLEMS_DIR}/||" \
+      | grep -oE '^[0-9]{3}' \
+      | awk '{ printf "P%s\n", $0 }' \
+      | sort -u
+  )"
+fi
+
+# ── Cross-reference each drift ID against the renamed set ───────────────────
+COVERED=0
+UNCOVERED=0
+while IFS= read -r id; do
+  [ -z "$id" ] && continue
+  if [ -n "$RENAMED_IDS" ] && printf '%s\n' "$RENAMED_IDS" | grep -qx "$id"; then
+    COVERED=$((COVERED + 1))
+  else
+    UNCOVERED=$((UNCOVERED + 1))
+  fi
+done <<< "$DRIFT_IDS"
+
+if [ "$UNCOVERED" -gt 0 ]; then
+  printf 'HALT_ROUTE_RECONCILE uncovered=%d\n' "$UNCOVERED"
+  exit 1
+fi
+
+printf 'INLINE_REFRESH covered=%d\n' "$COVERED"
+exit 0

package/scripts/reconcile-readme.sh

@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+# packages/itil/scripts/reconcile-readme.sh
+#
+# Diagnose-only drift detector for docs/problems/README.md vs filesystem
+# truth. Reads <problems-dir>/<NNN>-*.<status>.md, parses the README's
+# WSJF Rankings + Verification Queue + Closed tables, and reports each
+# disagreement.
+#
+# Usage:
+#   reconcile-readme.sh [<problems-dir>]
+#
+# Default <problems-dir> is ./docs/problems.
+#
+# Exit codes:
+#   0 = clean (README matches filesystem)
+#   1 = drift detected (structured diff to stdout)
+#   2 = parse error (README missing or malformed)
+#
+# Output format on drift (one line per drift entry, ≤ 150 bytes per
+# ADR-038 progressive-disclosure budget):
+#   DRIFT    <ID> wsjf-rankings: claims=<status> actual=<status>
+#   MISSING  <ID> wsjf-rankings: actual=<status> file=<basename>
+#   STALE    <ID> verification-queue: actual=<status>
+#   MISMATCH <ID> closed: actual=<status>
+#
+# Read-only — does NOT mutate the README. The /wr-itil:reconcile-readme
+# skill applies edits with narrative-aware preservation; this script's
+# only job is to report ground truth.
+#
+# @problem P118
+# @adr ADR-014 (Reconciliation as preflight robustness layer)
+# @adr ADR-022 (Verification Pending lifecycle excludes from WSJF Rankings)
+# @adr ADR-038 (Progressive disclosure — per-row byte budget)
+
+set -uo pipefail
+
+PROBLEMS_DIR="${1:-docs/problems}"
+README="${PROBLEMS_DIR}/README.md"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -f "$README" ]; then
+  echo "PARSE_ERROR: README not found at ${README}" >&2
+  exit 2
+fi
+
+if ! grep -q '^## WSJF Rankings' "$README"; then
+  echo "PARSE_ERROR: '## WSJF Rankings' header missing in ${README}" >&2
+  exit 2
+fi
+
+# ── Build filesystem truth: ID → status ─────────────────────────────────────
+
+declare -A FS_STATUS
+shopt -s nullglob
+for f in "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.open.md \
+         "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.known-error.md \
+         "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.verifying.md \
+         "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.closed.md \
+         "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.parked.md; do
+  base="$(basename "$f")"
+  num="${base%%-*}"
+  id="P${num}"
+  # `ticket_status` (not bash `status`) — zsh has `$status` as a read-only
+  # built-in mapping to `$?`. Defensive rename per P133 even though this
+  # script's `#!/usr/bin/env bash` shebang means it never runs under zsh.
+  case "$base" in
+    *.open.md)         ticket_status="open" ;;
+    *.known-error.md)  ticket_status="known-error" ;;
+    *.verifying.md)    ticket_status="verifying" ;;
+    *.closed.md)       ticket_status="closed" ;;
+    *.parked.md)       ticket_status="parked" ;;
+    *)                 continue ;;
+  esac
+  FS_STATUS["$id"]="$ticket_status"
+done
+shopt -u nullglob
+
+# ── Parse README sections into ID buckets ───────────────────────────────────
+# We use the section-header line numbers to slice the file into ranges.
+
+WSJF_START=$(grep -n '^## WSJF Rankings' "$README" | head -1 | cut -d: -f1)
+VQ_START=$(grep -n '^## Verification Queue' "$README" | head -1 | cut -d: -f1)
+CLOSED_START=$(grep -n '^## Closed' "$README" | head -1 | cut -d: -f1)
+PARKED_START=$(grep -n '^## Parked' "$README" | head -1 | cut -d: -f1)
+END_LINE=$(wc -l < "$README")
+
+# Sentinel each end with the next section start (or EOF).
+WSJF_END=${VQ_START:-${CLOSED_START:-${PARKED_START:-$END_LINE}}}
+VQ_END=${CLOSED_START:-${PARKED_START:-$END_LINE}}
+CLOSED_END=${PARKED_START:-$END_LINE}
+PARKED_END=$END_LINE
+
+# Extract IDs claimed by each section. Only data rows of the form
+#   | ... | P<NNN> | ... |
+# count; header + separator rows are skipped naturally because they
+# do not contain a P<NNN> token in the second column.
+
+extract_section_ids() {
+  local start="$1" end="$2"
+  [ -z "$start" ] && return 0
+  sed -n "${start},${end}p" "$README" \
+    | grep -oE '\| *P[0-9]{3} *\|' \
+    | grep -oE 'P[0-9]{3}' \
+    | sort -u
+}
+
+README_WSJF_IDS="$(extract_section_ids "$WSJF_START" "$WSJF_END")"
+README_VQ_IDS="$(extract_section_ids "$VQ_START" "$VQ_END")"
+README_CLOSED_IDS="$(extract_section_ids "$CLOSED_START" "$CLOSED_END")"
+README_PARKED_IDS="$(extract_section_ids "$PARKED_START" "$PARKED_END")"
+
+# ── Diff ─────────────────────────────────────────────────────────────────────
+
+DRIFT_LINES=()
+
+# (1) Each ID listed in WSJF Rankings must be .open.md or .known-error.md
+#     on disk. .verifying.md → drift (belongs in VQ); .closed.md → drift;
+#     .parked.md → drift; missing → drift.
+while read -r id; do
+  [ -z "$id" ] && continue
+  actual="${FS_STATUS[$id]:-missing}"
+  case "$actual" in
+    open|known-error)
+      : # ok
+      ;;
+    *)
+      DRIFT_LINES+=("DRIFT    ${id} wsjf-rankings: claims=open actual=${actual}")
+      ;;
+  esac
+done <<< "$README_WSJF_IDS"
+
+# (2) Each ID listed in Verification Queue must be .verifying.md on disk.
+#     .closed.md → STALE (drift class P062 closure didn't refresh);
+#     .open.md / .known-error.md → STALE; missing → STALE.
+while read -r id; do
+  [ -z "$id" ] && continue
+  actual="${FS_STATUS[$id]:-missing}"
+  case "$actual" in
+    verifying)
+      : # ok
+      ;;
+    *)
+      DRIFT_LINES+=("STALE    ${id} verification-queue: actual=${actual}")
+      ;;
+  esac
+done <<< "$README_VQ_IDS"
+
+# (3) Each ID listed in Closed section must be .closed.md on disk.
+while read -r id; do
+  [ -z "$id" ] && continue
+  actual="${FS_STATUS[$id]:-missing}"
+  case "$actual" in
+    closed)
+      : # ok
+      ;;
+    *)
+      DRIFT_LINES+=("MISMATCH ${id} closed: actual=${actual}")
+      ;;
+  esac
+done <<< "$README_CLOSED_IDS"
+
+# (4) Each .open.md / .known-error.md file on disk must appear in WSJF
+#     Rankings. Build a lookup set for quick membership tests.
+declare -A IN_WSJF
+while read -r id; do
+  [ -z "$id" ] && continue
+  IN_WSJF["$id"]=1
+done <<< "$README_WSJF_IDS"
+
+declare -A IN_VQ
+while read -r id; do
+  [ -z "$id" ] && continue
+  IN_VQ["$id"]=1
+done <<< "$README_VQ_IDS"
+
+for id in "${!FS_STATUS[@]}"; do
+  ticket_status="${FS_STATUS[$id]}"
+  case "$ticket_status" in
+    open|known-error)
+      if [ -z "${IN_WSJF[$id]:-}" ]; then
+        DRIFT_LINES+=("MISSING  ${id} wsjf-rankings: actual=${ticket_status}")
+      fi
+      ;;
+    verifying)
+      if [ -z "${IN_VQ[$id]:-}" ]; then
+        DRIFT_LINES+=("MISSING  ${id} verification-queue: actual=${ticket_status}")
+      fi
+      ;;
+    # closed and parked: not required to appear in their respective
+    # sections (Closed is curated narrative; Parked is exhaustive but
+    # an absence is a soft drift not flagged at this layer).
+  esac
+done
+
+# ── Report ──────────────────────────────────────────────────────────────────
+
+if [ ${#DRIFT_LINES[@]} -eq 0 ]; then
+  exit 0
+fi
+
+# Sort for stable output (ID order).
+IFS=$'\n' sorted=($(printf '%s\n' "${DRIFT_LINES[@]}" | sort))
+unset IFS
+for line in "${sorted[@]}"; do
+  printf '%s\n' "$line"
+done
+exit 1

package/scripts/test/check-problems-readme-budget.bats

@@ -0,0 +1,192 @@
+#!/usr/bin/env bats
+
+# @problem P134 — docs/problems/README.md line 3 narrative-blob accumulator
+# bloat. Sibling to P099 (briefing tier 3) on a different surface. The
+# "Last reviewed" line accumulates session-summary fragments unbounded;
+# at ~62 KB it breaks the Read tool entirely (25K-token limit on the
+# whole file regardless of offset/limit). P134 promotes the same
+# advisory-triplet pattern P099 documented (advisory script + behavioural
+# bats + ADR-040-tier-budget enforcement clause) to this surface.
+#
+# Contract: `check-problems-readme-budget.sh [<readme-path>]` is a
+# diagnose-only advisory script. It reads `docs/problems/README.md`
+# (or the supplied path), measures the byte size of line 3, and reports
+# overflow when line 3 is at or above the configured threshold (default
+# 5120 bytes per ADR-040 Tier 3 envelope; overridable via the
+# `PROBLEMS_README_LINE3_MAX_BYTES` env var).
+#
+# Exit codes:
+#   0 = always (advisory only — overflow is signal, not failure)
+#   2 = parse error (README path missing or unreadable)
+#
+# Output format on overflow (one line, terse machine-readable per
+# ADR-038 progressive-disclosure budget):
+#   OVER <readme-path> line=3 bytes=<N> threshold=<N>
+#
+# Output is empty (no lines) when line 3 is under the threshold.
+#
+# The script is read-only — it does NOT mutate the README. Truncation
+# is owned by the per-operation refresh contracts in `manage-problem`
+# Step 5 P094 + Step 7 P062 (and the sibling skills `transition-problem`,
+# `transition-problems`, `review-problems`, `reconcile-readme`).
+#
+# @jtbd JTBD-001 (Enforce Governance Without Slowing Down — restores
+#   Read-tool affordance to the highest-traffic problems-management surface)
+# @jtbd JTBD-006 (Progress the Backlog While I'm Away — every AFK iter's
+#   manage-problem call previously paid an awk/grep workaround tax)
+# @jtbd JTBD-101 (Extend the Suite with Clear Patterns — re-applies P099's
+#   advisory-script + bats + ADR-tier-budget triplet to a new surface,
+#   exactly the reusable shape ADR-040 line 92 documents)
+#
+# Cross-reference:
+#   P134: docs/problems/134-docs-problems-readme-md-line-3-narrative-blob-accumulator-bloat-sibling-p099.*.md
+#   P099: docs/problems/099-briefing-md-grows-unbounded-via-run-retro-appends-violating-progressive-disclosure.*.md
+#   ADR-040 — Session-start briefing surface (Tier 3 budget; line 92's
+#     reusable-pattern note explicitly names "problems index" as a
+#     candidate surface for this triplet)
+#   ADR-038 — Progressive disclosure (per-row terse budget)
+#   ADR-013 Rule 6 — non-interactive fail-safe (advisory-only / exit 0)
+#   ADR-005 — Plugin testing strategy (script-level bats governance)
+
+setup() {
+  SCRIPTS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SCRIPT="$SCRIPTS_DIR/check-problems-readme-budget.sh"
+  FIXTURE_DIR="$(mktemp -d)"
+}
+
+teardown() {
+  rm -rf "$FIXTURE_DIR"
+}
+
+# Helper: write a problems README fixture with the given line-3 byte size.
+# Lines 1, 2 are short header; line 3 is the synthetic "Last reviewed"
+# blob padded to target_bytes; lines 4+ contain a short stub so the
+# multi-line shape mirrors the production README.
+write_problems_readme() {
+  local path="$1"
+  local target_bytes="$2"
+  : > "$path"
+  printf '# Problem Backlog\n\n' >> "$path"
+  if [ "$target_bytes" -gt 0 ]; then
+    # Build a single line of exactly target_bytes bytes (no trailing
+    # newline before the byte budget completes). The newline at the
+    # end is part of the file structure but not counted in line 3's
+    # byte size — `awk 'NR==3' | wc -c` would include it; the script
+    # under test must strip it to match the threshold semantics.
+    local prefix='> Last reviewed: '
+    local prefix_size=${#prefix}
+    local body_target=$(( target_bytes - prefix_size ))
+    if [ "$body_target" -gt 0 ]; then
+      printf '%s' "$prefix" >> "$path"
+      # Append body_target dots — a single contiguous line.
+      printf '%.0s.' $(seq 1 "$body_target") >> "$path"
+    else
+      # target smaller than prefix — emit only the requested bytes
+      printf '%.0s.' $(seq 1 "$target_bytes") >> "$path"
+    fi
+    printf '\n' >> "$path"
+  else
+    printf '\n' >> "$path"
+  fi
+  printf '\n## WSJF Rankings\n\n(stub)\n' >> "$path"
+}
+
+# ── Existence + executable ──────────────────────────────────────────────────
+
+@test "check-problems-readme-budget: script exists" {
+  [ -f "$SCRIPT" ]
+}
+
+@test "check-problems-readme-budget: script is executable" {
+  [ -x "$SCRIPT" ]
+}
+
+# ── Default-threshold behaviour (5120 bytes per ADR-040 Tier 3 envelope) ────
+
+@test "check-problems-readme-budget: line 3 well under threshold produces no output and exits 0" {
+  write_problems_readme "$FIXTURE_DIR/README.md" 1024
+  run "$SCRIPT" "$FIXTURE_DIR/README.md"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-problems-readme-budget: line 3 at exactly the default threshold emits OVER (>= boundary)" {
+  write_problems_readme "$FIXTURE_DIR/README.md" 5120
+  run "$SCRIPT" "$FIXTURE_DIR/README.md"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER .*README.md line=3 bytes=5120 threshold=5120$"
+}
+
+@test "check-problems-readme-budget: line 3 well over threshold emits OVER with bytes + threshold" {
+  write_problems_readme "$FIXTURE_DIR/README.md" 12000
+  run "$SCRIPT" "$FIXTURE_DIR/README.md"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER .*README.md line=3 bytes=12000 threshold=5120$"
+}
+
+@test "check-problems-readme-budget: short line 3 (single fragment ~600 bytes) produces no output" {
+  write_problems_readme "$FIXTURE_DIR/README.md" 600
+  run "$SCRIPT" "$FIXTURE_DIR/README.md"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Configurable threshold via env var ──────────────────────────────────────
+
+@test "check-problems-readme-budget: PROBLEMS_README_LINE3_MAX_BYTES env var overrides default" {
+  write_problems_readme "$FIXTURE_DIR/README.md" 3000
+  # Default 5120: under threshold, no output. With env var set to 2000:
+  # over threshold, expect OVER line.
+  PROBLEMS_README_LINE3_MAX_BYTES=2000 run "$SCRIPT" "$FIXTURE_DIR/README.md"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER .*README.md line=3 bytes=3000 threshold=2000$"
+}
+
+@test "check-problems-readme-budget: env var threshold of 0 emits OVER for non-empty line 3 (sanity)" {
+  write_problems_readme "$FIXTURE_DIR/README.md" 100
+  PROBLEMS_README_LINE3_MAX_BYTES=0 run "$SCRIPT" "$FIXTURE_DIR/README.md"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER .*README.md line=3 bytes=100 threshold=0$"
+}
+
+# ── Argument and error handling ─────────────────────────────────────────────
+
+@test "check-problems-readme-budget: defaults to docs/problems/README.md when no arg provided" {
+  cd "$FIXTURE_DIR"
+  mkdir -p docs/problems
+  write_problems_readme docs/problems/README.md 8000
+  run "$SCRIPT"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -E "^OVER docs/problems/README.md line=3 bytes=8000 threshold=5120$"
+}
+
+@test "check-problems-readme-budget: missing README path exits 2 with parse error on stderr" {
+  run "$SCRIPT" "$FIXTURE_DIR/does-not-exist/README.md"
+  [ "$status" -eq 2 ]
+  echo "$output" | grep -iE "not found|missing|does not exist"
+}
+
+@test "check-problems-readme-budget: file with no line 3 (only 2 lines) exits 0 with no output" {
+  printf '# Problem Backlog\n\n' > "$FIXTURE_DIR/README.md"
+  run "$SCRIPT" "$FIXTURE_DIR/README.md"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+@test "check-problems-readme-budget: file with empty line 3 exits 0 with no output" {
+  printf '# Problem Backlog\n\n\n## WSJF Rankings\n\n(stub)\n' > "$FIXTURE_DIR/README.md"
+  run "$SCRIPT" "$FIXTURE_DIR/README.md"
+  [ "$status" -eq 0 ]
+  [ -z "$output" ]
+}
+
+# ── Read-only contract ──────────────────────────────────────────────────────
+
+@test "check-problems-readme-budget: script does not mutate the README under audit" {
+  write_problems_readme "$FIXTURE_DIR/README.md" 12000
+  pre_hash=$(shasum -a 256 "$FIXTURE_DIR/README.md" | awk '{print $1}')
+  run "$SCRIPT" "$FIXTURE_DIR/README.md"
+  [ "$status" -eq 0 ]
+  post_hash=$(shasum -a 256 "$FIXTURE_DIR/README.md" | awk '{print $1}')
+  [ "$pre_hash" = "$post_hash" ]
+}