@windyroad/itil 0.28.1-preview.307 → 0.29.0-preview.311

package/.claude-plugin/plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.28.1-preview.307",
+  "version": "0.29.0-preview.311",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/scripts/test/update-jtbd-references-related-problems.bats

@@ -0,0 +1,178 @@
+#!/usr/bin/env bats
+
+# P170 / Phase 4 P4.1 — behavioural fixture for the
+# update-jtbd-references-section.sh "Related problems" extension.
+# Adds a fourth lookup-table row (alongside RFCs / Story Maps /
+# Stories) so JTBD files auto-maintain a `## Related problems`
+# reverse-trace section sourced from problem-ticket frontmatter
+# `jtbd:` arrays. Mirrors the parallel-existence one-way reverse-
+# trace shape from ADR-060 § Phase 3 + Phase 4 in-scope amendment
+# (2026-05-13) P4.1.
+#
+# Per ADR-060 architect finding A4 + JTBD finding F5: lookup-table
+# row addition, NOT a new helper. The body MUST remain
+# per-section-name-branchless (assertion in
+# update-references-section-sibling-helpers.bats).
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="$REPO_ROOT/packages/itil/scripts/update-jtbd-references-section.sh"
+
+  WORKSPACE="$(mktemp -d)"
+  cd "$WORKSPACE"
+  mkdir -p docs/problems/open docs/problems/known-error docs/jtbd/solo-developer
+
+  cat > docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md <<'EOF'
+---
+status: proposed
+job-id: sample-job
+persona: solo-developer
+date-created: 2026-05-13
+---
+
+# JTBD-999: Sample Job
+
+## Job Statement
+
+Sample.
+
+## Desired Outcomes
+
+- Outcome A.
+EOF
+}
+
+teardown() {
+  if [ -n "${WORKSPACE:-}" ] && [ -d "$WORKSPACE" ]; then
+    rm -rf "$WORKSPACE"
+  fi
+}
+
+@test "Related problems: extracts user-business problem citing the JTBD" {
+  cat > docs/problems/open/501-business-problem.md <<'EOF'
+---
+type: user-business
+jtbd: [JTBD-999]
+persona: solo-developer
+---
+# Problem 501: Business problem citing JTBD-999
+
+**Status**: Open
+
+## Description
+
+Business problem.
+EOF
+
+  run bash "$SCRIPT" docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md "Related problems"
+  [ "$status" -eq 0 ]
+  grep -q '^## Related problems' docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md
+  grep -q '| P501 |' docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md
+}
+
+@test "Related problems: ignores problems that don't cite the JTBD" {
+  cat > docs/problems/open/502-unrelated.md <<'EOF'
+---
+type: technical
+---
+# Problem 502: Unrelated technical problem
+
+**Status**: Open
+
+## Description
+
+Unrelated.
+EOF
+
+  run bash "$SCRIPT" docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md "Related problems"
+  [ "$status" -eq 0 ]
+  ! grep -q '^## Related problems' docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md
+}
+
+@test "Related problems: lazy-empty when no problem cites the JTBD" {
+  cat > docs/problems/open/503-something-else.md <<'EOF'
+---
+type: user-business
+jtbd: [JTBD-001]
+---
+# Problem 503: Cites a different JTBD
+
+**Status**: Open
+EOF
+
+  run bash "$SCRIPT" docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md "Related problems"
+  [ "$status" -eq 0 ]
+  ! grep -q '^## Related problems' docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md
+}
+
+@test "Related problems: searches per-state subdirs (RFC-002 layout)" {
+  cat > docs/problems/known-error/504-business-known-error.md <<'EOF'
+---
+type: user-business
+jtbd: [JTBD-999]
+persona: solo-developer
+---
+# Problem 504: Known-error business problem
+
+**Status**: Known Error
+EOF
+
+  run bash "$SCRIPT" docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md "Related problems"
+  [ "$status" -eq 0 ]
+  grep -q '| P504 |' docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md
+}
+
+@test "Related problems: idempotent across re-runs" {
+  cat > docs/problems/open/505-idempotent.md <<'EOF'
+---
+type: user-business
+jtbd: [JTBD-999]
+persona: solo-developer
+---
+# Problem 505: Idempotent test
+
+**Status**: Open
+EOF
+
+  run bash "$SCRIPT" docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md "Related problems"
+  [ "$status" -eq 0 ]
+  before_hash=$(md5 -q docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md 2>/dev/null || md5sum docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md | awk '{print $1}')
+
+  run bash "$SCRIPT" docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md "Related problems"
+  [ "$status" -eq 0 ]
+  after_hash=$(md5 -q docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md 2>/dev/null || md5sum docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md | awk '{print $1}')
+
+  [ "$before_hash" = "$after_hash" ]
+}
+
+@test "Related problems: unknown section-name still fails" {
+  run bash "$SCRIPT" docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md "Bogus Section"
+  [ "$status" -ne 0 ]
+}
+
+@test "Related problems: helper still no per-section-name branch (P4.1 lookup-table-row addition only)" {
+  ! grep -E 'case[[:space:]]+"\$\{?section[_-]?name\}?"|if[[:space:]]+\[[[:space:]]+"\$\{?section[_-]?name\}?"[[:space:]]+=' "$SCRIPT"
+}
+
+@test "Related problems: extracts problem using body-field **JTBD**: convention (capture-problem schema P3.1)" {
+  # P3.1 capture-problem skeleton writes body-field **JTBD**: (matches
+  # existing **Status**: / **Type**: schema); helper must accept both
+  # frontmatter `jtbd:` arrays AND body-field **JTBD**: lines.
+  cat > docs/problems/open/506-body-field-business-problem.md <<'EOF'
+# Problem 506: Body-field business problem
+
+**Status**: Open
+**Reported**: 2026-05-13
+**Type**: user-business
+**JTBD**: JTBD-999
+**Persona**: solo-developer
+
+## Description
+
+Problem captured via Phase 4 P3.1 capture-problem with body-field JTBD trace.
+EOF
+
+  run bash "$SCRIPT" docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md "Related problems"
+  [ "$status" -eq 0 ]
+  grep -q '| P506 |' docs/jtbd/solo-developer/JTBD-999-sample-job.proposed.md
+}

package/scripts/update-jtbd-references-section.sh

@@ -21,25 +21,44 @@ SECTION_NAME="${2:-}"
 [ -n "$SECTION_NAME" ] || { echo "ERROR: missing section-name argument" >&2; exit 1; }
 [ -f "$JTBD_FILE" ] || { echo "ERROR: jtbd file not found: $JTBD_FILE" >&2; exit 1; }
 
-declare -A SECTION_GLOB SECTION_MODE SECTION_ID_PATTERN
+declare -A SECTION_GLOB SECTION_MODE SECTION_ID_PATTERN SECTION_ID_PREFIX
 
 SECTION_GLOB["RFCs"]="docs/rfcs/RFC-*.md"
 SECTION_MODE["RFCs"]="markdown-frontmatter-jtbd"
 SECTION_ID_PATTERN["RFCs"]="RFC-[0-9]+"
+SECTION_ID_PREFIX["RFCs"]=""
 
 SECTION_GLOB["Story Maps"]="docs/story-maps/*/STORY-MAP-*.html"
 SECTION_MODE["Story Maps"]="html-data-attribute-jtbd"
 SECTION_ID_PATTERN["Story Maps"]="STORY-MAP-[0-9]+"
+SECTION_ID_PREFIX["Story Maps"]=""
 
 SECTION_GLOB["Stories"]="docs/stories/*/STORY-*.md"
 SECTION_MODE["Stories"]="markdown-frontmatter-jtbd"
 SECTION_ID_PATTERN["Stories"]="STORY-[0-9]+"
+SECTION_ID_PREFIX["Stories"]=""
+
+# P170 Phase 4 P4.1 — Related problems reverse-trace from problem
+# tickets that cite this JTBD in their `jtbd:` frontmatter array.
+# Per ADR-060 § Phase 3 + Phase 4 in-scope amendment (2026-05-13)
+# P4.1 + JTBD finding F5: lookup-table row addition (no per-section
+# branching). Searches per-state subdirs (RFC-002 layout) via the
+# `*/` glob segment; the flat-layout half is intentionally omitted
+# because Phase 4 ships after RFC-002 T5 has completed migration.
+# Problem-ticket filenames are `<NNN>-<title>.md` without the `P`
+# prefix; render-prefix "P" produces the canonical `P<NNN>` form
+# for the rendered table row.
+SECTION_GLOB["Related problems"]="docs/problems/*/[0-9]*-*.md"
+SECTION_MODE["Related problems"]="markdown-frontmatter-jtbd"
+SECTION_ID_PATTERN["Related problems"]="^[0-9]+"
+SECTION_ID_PREFIX["Related problems"]="P"
 
 glob_pattern="${SECTION_GLOB[$SECTION_NAME]:-}"
 extraction_mode="${SECTION_MODE[$SECTION_NAME]:-}"
 id_pattern="${SECTION_ID_PATTERN[$SECTION_NAME]:-}"
+id_prefix="${SECTION_ID_PREFIX[$SECTION_NAME]:-}"
 
-[ -n "$glob_pattern" ] || { echo "ERROR: unknown section-name '$SECTION_NAME'. Supported: RFCs, Story Maps, Stories" >&2; exit 1; }
+[ -n "$glob_pattern" ] || { echo "ERROR: unknown section-name '$SECTION_NAME'. Supported: RFCs, Story Maps, Stories, Related problems" >&2; exit 1; }
 
 jtbd_basename=$(basename "$JTBD_FILE")
 jtbd_id=$(echo "$jtbd_basename" | grep -oE '^JTBD-[0-9]+' | head -1)
@@ -49,7 +68,16 @@ declare -a matched_ids=() matched_titles=() matched_statuses=()
 
 extract_from_markdown_frontmatter_jtbd() {
   local file="$1"
-  awk '/^---$/{f=!f;next} f && /^jtbd:/' "$file" | head -1 | grep -qE "\\b${jtbd_id}\\b"
+  # YAML frontmatter `jtbd:` array OR body-field `**JTBD**:` line.
+  # Problem tickets use body-field convention (per existing P170 / P189
+  # schema); RFCs / Stories / Story Maps use frontmatter `jtbd:` arrays.
+  # Phase 4 P4.2: capture-problem skeleton uses body field `**JTBD**:`
+  # per the existing convention; frontmatter migration is deferred to
+  # a follow-on slice.
+  if awk '/^---$/{f=!f;next} f && /^jtbd:/' "$file" | head -1 | grep -qE "\\b${jtbd_id}\\b"; then
+    return 0
+  fi
+  grep -m1 -E '^\*\*JTBD\*\*:' "$file" 2>/dev/null | grep -qE "\\b${jtbd_id}\\b"
 }
 
 extract_from_html_data_jtbd() {
@@ -60,7 +88,18 @@ extract_from_html_data_jtbd() {
 extract_id_from_filename() { basename "$1" | grep -oE "$id_pattern" | head -1; }
 extract_title_md() { awk '/^# / { sub(/^# /, ""); print; exit }' "$1"; }
 extract_title_html() { grep -oE '<title>[^<]+</title>' "$1" | head -1 | sed -E 's|<title>([^<]+)</title>|\1|'; }
-extract_status_md() { awk '/^---$/{f=!f;next} f && /^status:/{ sub(/^status:[[:space:]]*/, ""); gsub(/"/, ""); print; exit }' "$1"; }
+extract_status_md() {
+  # Frontmatter `status:` first; body `**Status**: <value>` fallback
+  # (problem tickets store Status as a body field, not frontmatter,
+  # so the fallback fires when frontmatter is silent — preserves
+  # backward-compat for Story / RFC files that DO carry frontmatter).
+  local s
+  s=$(awk '/^---$/{f=!f;next} f && /^status:/{ sub(/^status:[[:space:]]*/, ""); gsub(/"/, ""); print; exit }' "$1")
+  if [ -z "$s" ]; then
+    s=$(grep -m1 -E '^\*\*Status\*\*:' "$1" 2>/dev/null | sed -E 's/^\*\*Status\*\*:[[:space:]]*//')
+  fi
+  printf '%s\n' "$s"
+}
 extract_status_html() { grep -oE '<meta[[:space:]]+name="status"[[:space:]]+content="[^"]+"' "$1" | head -1 | sed -E 's|.*content="([^"]+)".*|\1|'; }
 
 case "$extraction_mode" in
@@ -86,7 +125,7 @@ for artefact in $glob_pattern; do
   if "$extract_match" "$artefact"; then
     aid=$(extract_id_from_filename "$artefact")
     [ -n "$aid" ] || continue
-    matched_ids+=("$aid")
+    matched_ids+=("${id_prefix}${aid}")
     matched_titles+=("$("$extract_title" "$artefact" 2>/dev/null || echo "")")
     matched_statuses+=("$("$extract_status" "$artefact" 2>/dev/null || echo "unknown")")
   fi

package/skills/capture-problem/SKILL.md

@@ -64,8 +64,10 @@ fi
 | `--type=technical` | Pre-resolves type to `technical`; Step 1.5 skips the classifier and the AskUserQuestion. |
 | `--type=user-business` | Pre-resolves type to `user-business`; Step 1.5 skips the classifier and the AskUserQuestion. |
 | `--no-prompt` | Pre-resolves type to `technical` (default); Step 1.5 skips the classifier and the AskUserQuestion. |
+| `--jtbd=JTBD-NNN[,JTBD-NNN...]` | Pre-resolves the JTBD-trace value (Phase 4 P3.1 + I12 invariant per ADR-060 § Phase 3 + Phase 4 in-scope amendment 2026-05-13). Step 1.5b skips the JTBD-trace lexical dispatch and the I12 hard-block. Comma-separated list of JTBD IDs (no spaces). |
+| `--persona=<value>` | Pre-resolves the persona value (Phase 4 P4.2). Step 1.5b skips persona derivation. Value MUST be one of: `solo-developer`, `tech-lead`, `plugin-developer`, `plugin-user`. |
 
-Strip recognised leading flags from `$ARGUMENTS`; the remainder (after flags) is the free-text description. If both `--type=<value>` and `--no-prompt` are present, `--type=<value>` wins (more specific). Unknown leading flags halt-with-stderr-directive: print "capture-problem: unknown flag '<flag>' — recognised flags: --type=technical, --type=user-business, --no-prompt" and exit.
+Strip recognised leading flags from `$ARGUMENTS`; the remainder (after flags) is the free-text description. If both `--type=<value>` and `--no-prompt` are present, `--type=<value>` wins (more specific). Unknown leading flags halt-with-stderr-directive: print "capture-problem: unknown flag '<flag>' — recognised flags: --type=technical, --type=user-business, --no-prompt, --jtbd=JTBD-NNN, --persona=<value>" and exit.
 
 Empty description (post-flag-strip) halts per the Rule 6 audit above.
 
@@ -111,6 +113,29 @@ Resolve `type_value` ∈ {`technical`, `user-business`} per the following framew
 
 **JTBD-301 scope guard**: this dispatch fires on the maintainer-side `/wr-itil:capture-problem` skill only. The plugin-user-side intake (`.github/ISSUE_TEMPLATE/problem-report.yml`) MUST NOT carry an equivalent type selector — plugin-user persona constraint is "no pre-classification". Triage assigns `type` during `/wr-itil:manage-problem` ingestion of user-reported issues, not at user-report time. **The lexical-signal classifier is ALSO NOT invoked from `/wr-itil:manage-problem`'s ingestion-of-plugin-user-reports path** — plugin-user descriptions do not carry the same authorial intent as maintainer-internal captures (a plugin-user describing their friction in maintainer-vocabulary terms would mis-classify); triage stays user-judgement, not lexical-classifier inference.
 
+### 1.5b JTBD-trace + persona dispatch (Phase 3 P3.1 + Phase 4 P4.2 + I12 invariant)
+
+Per ADR-060 § Phase 3 + Phase 4 in-scope amendment (2026-05-13). Fires ONLY when `type_value` resolved to `user-business` (whether via `--type=user-business` flag, `--no-prompt` default override is impossible since `--no-prompt` defaults to `technical`, the classifier silent-resolve to `user-business`, or the ambiguous-fallback AskUserQuestion). For `type_value = technical`, Steps 1.5b and the I12 hard-block do NOT fire (technical problems may carry empty `jtbd:` array; persona is optional). The whole dispatch keys on **nullable-field-conditional** shape per ADR-060 line 536 — NEVER on `type` value as a control-flow branch (preserves I2 invariant; the type co-incidence is upstream input, not control-flow key).
+
+**Resolve `jtbd_trace_value`** (an ORDERED list of JTBD IDs, possibly empty) via the following dispatch:
+
+1. **If `--jtbd=JTBD-NNN[,JTBD-NNN...]` was set in Step 1**: parse comma-separated list; assign to `jtbd_trace_value`; do NOT run the lexical detector; do NOT fire AskUserQuestion (silent-proceed per ADR-013 Rule 5).
+2. **Else** run the **lexical JTBD-trace detector** against the description: `grep -oE '\bJTBD-[0-9]+\b' | sort -u`. If matches found, set `jtbd_trace_value` to the matched IDs (de-duplicated, sorted ascending) and emit stderr advisory: `capture-problem: derived jtbd-trace=<id-list> from description JTBD-NNN citations; re-invoke with --jtbd= to override`. Do NOT fire AskUserQuestion.
+3. **Else (no flag, no lexical detection, type=user-business)**: **I12 hard-block** per ADR-060 Confirmation criterion 10. Halt-with-stderr-directive: print `capture-problem: I12 invariant — type: user-business requires ≥1 JTBD trace. Re-invoke with --jtbd=JTBD-NNN, OR edit the description to cite a JTBD-NNN ID, OR re-classify as technical via --type=technical.` and exit. This branch is the load-bearing enforcement of the new I12 invariant — JTBD-as-source-of-truth for persona-anchored unmet need; user-business problems MUST cite ≥1 JTBD.
+
+**Resolve `persona_value`** (a scalar enum value OR empty) via the following dispatch:
+
+1. **If `--persona=<value>` was set in Step 1**: validate `<value>` ∈ `{solo-developer, tech-lead, plugin-developer, plugin-user}`; halt with directive if invalid; otherwise assign and proceed silently.
+2. **Else if `jtbd_trace_value` is non-empty**: derive persona from cited JTBDs' frontmatter. Read each cited `docs/jtbd/<persona>/JTBD-<NNN>-*.md` file; extract its `persona:` (and optionally `secondary-persona:`) frontmatter values; if all cited JTBDs agree on a single persona, set `persona_value` to that persona silently and emit stderr advisory: `capture-problem: derived persona=<value> from cited JTBD <id> frontmatter`. If cited JTBDs disagree, fire AskUserQuestion with the union-of-derived-personas as options.
+3. **Else if `type_value = user-business`**: AskUserQuestion fires with the closed enum as options. Per ADR-060 P4.2: `solo-developer | tech-lead | plugin-developer | plugin-user`. Question text: *"What persona does this user-business problem serve?"*
+4. **Else (`type_value = technical`)**: leave `persona_value` empty. `persona:` frontmatter is OPTIONAL on technical problems.
+
+**I12 hard-block escape hatch (none)**: there is no `BYPASS_I12=1` env override at the SKILL surface. The block is a load-bearing schema constraint per ADR-060 Confirmation criterion 10; if a maintainer captures a user-business problem without yet knowing the JTBD trace, they must EITHER capture as `--type=technical` and re-classify during `/wr-itil:manage-problem` ingestion (when the JTBD becomes clear), OR fast-capture a placeholder JTBD via `/wr-itil:capture-jtbd` (when it ships under Phase 4 follow-on) and reference it.
+
+**JTBD-301 scope preservation**: this dispatch ALSO fires on the maintainer-side `/wr-itil:capture-problem` only. Plugin-user-side `.github/ISSUE_TEMPLATE/problem-report.yml` MUST NOT prompt for JTBD trace or persona — preserves the JTBD-301 firewall per ADR-060 P4.3 maintainer-side / plugin-user-side asymmetry clarifier. Triage during `/wr-itil:manage-problem` ingestion assigns both fields from the reporter's symptom signals (per the JTBD-301 maintainer-side-complement extension landed 2026-05-13).
+
+**Phase 3 P3.1 nullable-field-conditional shape**: the JTBD-trace prompt + I12 hard-block fire on `jtbd_trace_value` nullability (absent vs present), NOT on the `type` field's value. The composite gate (`type == user-business AND jtbd_trace_value == empty`) treats `type` as upstream-determined co-incident input — exactly the carve-out permitted by ADR-060 line 536. Steps 2-7 below execute identically regardless of `type_value`, `jtbd_trace_value`, or `persona_value`; only the values substituted into the Step 4 skeleton template differ. This preserves I2 control-flow uniformity AND extends the I2 behavioural test (per ADR-060 Confirmation criterion 11) to assert no control-flow branch on `persona:` field presence.
+
 ### 2. Minimal-grep duplicate check (3-keyword title-only)
 
 Extract up to **3 distinct kebab-cased non-stopword keywords** from the description. Grep the **filenames** of `docs/problems/*.md` AND `docs/problems/<state>/*.md` (NOT bodies — title-only is the conservative threshold per architect verdict on Q1; dual-tolerant per RFC-002 migration window):
@@ -170,6 +195,8 @@ Log the renumber decision in the operation report if origin and local diverged.
 **Priority**: 3 (Medium) — Impact: 3 x Likelihood: 1 (deferred — re-rate at next /wr-itil:review-problems)
 **Effort**: M (deferred — re-rate at next /wr-itil:review-problems)
 **Type**: <type_value>
+**JTBD**: <jtbd_trace_value_as_comma_separated_list_OR_omit_line_when_empty>
+**Persona**: <persona_value_OR_omit_line_when_empty>
 
 ## Description
 

package/skills/capture-problem/test/capture-problem-step-1-5b-jtbd-trace.bats

@@ -0,0 +1,178 @@
+#!/usr/bin/env bats
+
+# P170 / Phase 3 P3.1 + Phase 4 P4.2 + I12 — behavioural fixture for
+# capture-problem Step 1.5b JTBD-trace + persona dispatch. Per ADR-060
+# § Phase 3 + Phase 4 in-scope amendment (2026-05-13):
+#
+# - Lexical JTBD-trace detection: description-contains-JTBD-NNN-ID →
+#   silent-resolve jtbd_trace_value to the matched IDs.
+# - I12 hard-block: type=user-business AND jtbd_trace_value empty AND
+#   no --jtbd flag → halt-with-stderr-directive.
+# - --jtbd=JTBD-NNN[,...] flag pre-resolves jtbd_trace_value silently.
+# - --persona=<value> flag pre-resolves persona_value silently.
+# - Skeleton template carries **JTBD**: and **Persona**: body fields
+#   (matches existing **Status**: / **Type**: convention; frontmatter
+#   migration deferred to follow-on slice).
+#
+# Reference-impl pattern: this fixture exercises the algorithm directly
+# via shell helpers; the SKILL.md prose at runtime executes the same
+# algorithm via LLM-interpretation. The bats algorithm IS the contract
+# the SKILL.md prose binds.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_FILE="$REPO_ROOT/packages/itil/skills/capture-problem/SKILL.md"
+}
+
+# Reference implementation of the JTBD-trace lexical detector (matches
+# the Step 1.5b prose at SKILL.md). Returns space-separated sorted-unique
+# JTBD IDs from the description, OR empty string if none.
+detect_jtbd_trace() {
+  local desc="$1"
+  echo "$desc" | grep -oE '\bJTBD-[0-9]+\b' | sort -u | tr '\n' ' ' | sed 's/[[:space:]]*$//'
+}
+
+# Reference implementation of the I12 hard-block predicate. Returns
+# 0 (true → block) when type=user-business AND jtbd_trace empty AND
+# no --jtbd flag was provided. Returns 1 otherwise.
+i12_should_block() {
+  local type_value="$1" jtbd_trace="$2" had_jtbd_flag="$3"
+  [ "$type_value" = "user-business" ] || return 1
+  [ -z "$jtbd_trace" ] || return 1
+  [ "$had_jtbd_flag" = "0" ] || return 1
+  return 0
+}
+
+# Reference implementation of --jtbd= flag parser. Accepts CSV; returns
+# space-separated IDs (canonicalised) OR empty if the flag wasn't set.
+parse_jtbd_flag() {
+  local arg="$1"
+  case "$arg" in
+    --jtbd=*) echo "${arg#--jtbd=}" | tr ',' '\n' | sort -u | tr '\n' ' ' | sed 's/[[:space:]]*$//' ;;
+    *) echo "" ;;
+  esac
+}
+
+# Reference implementation of --persona= validator. Returns the value
+# if it's in the closed enum; halts (returns 1) otherwise.
+validate_persona() {
+  local val="$1"
+  case "$val" in
+    solo-developer|tech-lead|plugin-developer|plugin-user) echo "$val"; return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
+@test "P3.1 detect_jtbd_trace: description with single JTBD-NNN citation extracts ID" {
+  result=$(detect_jtbd_trace "Adopters want JTBD-101 to scale down for atomic fixes")
+  [ "$result" = "JTBD-101" ]
+}
+
+@test "P3.1 detect_jtbd_trace: description with multiple JTBD-NNN citations extracts sorted-unique IDs" {
+  result=$(detect_jtbd_trace "Composes with JTBD-008 and JTBD-001 governance outcome (also JTBD-008 again)")
+  [ "$result" = "JTBD-001 JTBD-008" ]
+}
+
+@test "P3.1 detect_jtbd_trace: description with no JTBD citation returns empty" {
+  result=$(detect_jtbd_trace "The captureProblem hook in packages/itil/hooks has a regex drift")
+  [ -z "$result" ]
+}
+
+@test "P3.1 detect_jtbd_trace: JTBD-NNN must be word-boundary (not substring)" {
+  # NOT-JTBD-001 should NOT match because of leading \b boundary check —
+  # but `\b` matches at hyphen boundary in standard regex. The detector
+  # treats this conservatively — anything matching \bJTBD-[0-9]+\b is
+  # accepted. The signal is high-precision; mis-matches at hyphen
+  # boundaries are still real JTBD-NNN citations from the maintainer's
+  # perspective.
+  result=$(detect_jtbd_trace "BANANA-JTBD-001-thing")
+  [ "$result" = "JTBD-001" ]
+}
+
+@test "I12 i12_should_block: user-business + empty jtbd + no flag → blocks" {
+  i12_should_block "user-business" "" "0"
+}
+
+@test "I12 i12_should_block: user-business + non-empty jtbd → does NOT block" {
+  ! i12_should_block "user-business" "JTBD-001" "0"
+}
+
+@test "I12 i12_should_block: user-business + empty jtbd + --jtbd flag set → does NOT block" {
+  ! i12_should_block "user-business" "" "1"
+}
+
+@test "I12 i12_should_block: technical + empty jtbd → does NOT block (technical has no JTBD requirement)" {
+  ! i12_should_block "technical" "" "0"
+}
+
+@test "P3.1 parse_jtbd_flag: --jtbd=JTBD-NNN parses single ID" {
+  result=$(parse_jtbd_flag "--jtbd=JTBD-001")
+  [ "$result" = "JTBD-001" ]
+}
+
+@test "P3.1 parse_jtbd_flag: --jtbd=JTBD-A,JTBD-B parses CSV into sorted-unique list" {
+  result=$(parse_jtbd_flag "--jtbd=JTBD-008,JTBD-001,JTBD-008")
+  [ "$result" = "JTBD-001 JTBD-008" ]
+}
+
+@test "P3.1 parse_jtbd_flag: non-jtbd-flag arg returns empty" {
+  result=$(parse_jtbd_flag "--type=user-business")
+  [ -z "$result" ]
+}
+
+@test "P4.2 validate_persona: closed enum accepts solo-developer" {
+  result=$(validate_persona "solo-developer")
+  [ "$result" = "solo-developer" ]
+}
+
+@test "P4.2 validate_persona: closed enum accepts tech-lead" {
+  validate_persona "tech-lead"
+}
+
+@test "P4.2 validate_persona: closed enum accepts plugin-developer" {
+  validate_persona "plugin-developer"
+}
+
+@test "P4.2 validate_persona: closed enum accepts plugin-user" {
+  validate_persona "plugin-user"
+}
+
+@test "P4.2 validate_persona: rejects free-text outside enum" {
+  ! validate_persona "maintainer"
+}
+
+@test "SKILL.md: Step 1.5b section header exists for JTBD-trace + persona dispatch" {
+  grep -qE '^### 1\.5b JTBD-trace \+ persona dispatch' "$SKILL_FILE"
+}
+
+@test "SKILL.md: Step 1.5b names I12 invariant load-bearing identifier" {
+  grep -qE 'I12 (invariant|hard-block)' "$SKILL_FILE"
+}
+
+@test "SKILL.md: --jtbd= flag declared in flag table" {
+  grep -qE '\| `--jtbd=JTBD-NNN' "$SKILL_FILE"
+}
+
+@test "SKILL.md: --persona= flag declared in flag table" {
+  grep -qE '\| `--persona=<value>`' "$SKILL_FILE"
+}
+
+@test "SKILL.md: Step 4 template carries **JTBD**: body field" {
+  grep -qE '^\*\*JTBD\*\*:' "$SKILL_FILE"
+}
+
+@test "SKILL.md: Step 4 template carries **Persona**: body field" {
+  grep -qE '^\*\*Persona\*\*:' "$SKILL_FILE"
+}
+
+@test "SKILL.md: Step 1.5b names nullable-field-conditional shape (NOT type-conditional)" {
+  grep -qE 'nullable-field-conditional' "$SKILL_FILE"
+}
+
+@test "SKILL.md: Step 1.5b cites I12 + ADR-060 amendment 2026-05-13" {
+  grep -qE 'ADR-060 § Phase 3 \+ Phase 4 in-scope amendment' "$SKILL_FILE"
+}
+
+@test "SKILL.md: Step 1.5b preserves JTBD-301 firewall on plugin-user-side intake" {
+  grep -qE 'plugin-user-side .* MUST NOT (prompt|carry)' "$SKILL_FILE"
+}

package/skills/review-problems/SKILL.md

@@ -108,6 +108,99 @@ The question MUST include a fix summary extracted from the `## Fix Released` sec
 
 **AFK / non-interactive branch (ADR-013 Rule 6):** when `AskUserQuestion` is unavailable, record the Verification Queue in the review output and skip the prompt. Do NOT auto-close verifying tickets — only the user can make that call. The user sees the queue on next interactive invocation.
 
+<!-- ADR-062-step-naming-reconciliation: this skill's current numbering has 7 steps; ADR-062 was authored against a stale view that called the inbound-discovery sub-step "Step 8.5" and the README renderer "Step 9e". Both names appear verbatim in headers below so ADR-062 § Confirmation criterion 1 ("Step 8.5") and § Confirmation criterion final bullet ("Step 9e") remain string-anchorable. Do NOT strip the "Step 8.5" / "Step 9e" substrings on rename. -->
+
+### 4.5. Inbound-discovery + assessment-pipeline (ADR-062 § Step 8.5 / Decision Outcome)
+
+Per ADR-062 (peer of ADR-024). Polls configured upstream channels, runs each unmatched inbound report through the six-step assessment pipeline, and routes outcomes to one of three branches: safe-and-valid-local-ticket-create / above-threshold-pushback / clear-malicious-close-with-verdict. All external comms ride the P064 + P038 evaluator gates per ADR-028 amended. Mechanical-stage carve-out (P132 / ADR-044 category 4 silent framework action): branch decisions resolve from JTBD-alignment + dual-axis-risk verdicts; this step does NOT use `AskUserQuestion` at the branch decision. User-attention surfaces ONLY at hook gates (existing external-comms gate UX) and ambiguity edge cases recorded as `cache_audit_note` in the cache for the next interactive review.
+
+**Fail-soft contract**: any error in Step 4.5 (missing channel config, GH API failure, malformed cache, subagent failure, gate denial on a verdict-comment post) MUST NOT block the review — emit an advisory note, skip the failing channel/report, and continue. Step 5 (README rewrite) proceeds regardless. The assessment pipeline is purely additive; no-inbound-discovery is the status-quo baseline.
+
+#### 4.5a. Read channel config + parse invocation flags
+
+Read `docs/problems/.upstream-channels.json`. If missing or malformed: log an advisory note (`channel config absent or malformed; inbound-discovery skipped this pass`) and skip Step 4.5 entirely. Adopters who don't ship this file inherit zero ceremony tax — the downstream-adopter non-obligation per ADR-062 § Downstream-adopter contract + JTBD-101.
+
+Parse `$ARGUMENTS` as a whitespace-separated token list. Recognised invocation flags for inbound-discovery:
+
+- `--force-upstream-recheck` → set `force_recheck=true`. Bypasses the TTL check in 4.5b; forces a fresh poll of every channel. Use case: maintainer pre-flight before a release (JTBD-202) — rebuild the cache from the upstream authoritative source rather than trusting in-window cached state.
+- `--no-force-upstream-recheck` → set `force_recheck=false` explicitly (the default). Surfaces the flag's existence in `--help`-style discovery without changing behaviour.
+
+Unknown leading flags addressed at inbound-discovery (those starting with `--force-upstream` or `--inbound-`) halt the inbound-discovery step with an advisory note naming the unrecognised flag; non-inbound flags are passed through unchanged (e.g. flags consumed by Step 2's re-scoring or Step 4's verification prompt are not in scope here).
+
+Flag-parsing defaults: `force_recheck=false` when neither flag is present.
+
+#### 4.5b. Cache TTL check + TTL-expiry auto-recheck
+
+Read `docs/problems/.upstream-cache.json`. Compute `cache_age_seconds = (now - last_checked)` when `last_checked` is non-null.
+
+Branch:
+
+- `force_recheck == true` → **force-flag branch**: bypass TTL; proceed to 4.5c (fresh poll). Emit advisory note `inbound-discovery: --force-upstream-recheck flag set; bypassing TTL`.
+- `last_checked == null` → **first-run branch**: cache is empty; proceed to 4.5c. Emit advisory note `inbound-discovery: cache empty (last_checked null); initial poll`.
+- `cache_age_seconds > ttl_seconds` → **TTL-expiry auto-recheck branch**: cache is stale; proceed to 4.5c without requiring the explicit flag. Emit advisory note `inbound-discovery: cache age <N>s exceeds ttl_seconds <M>; auto-recheck`.
+- `cache_age_seconds <= ttl_seconds` AND `force_recheck == false` → **cache-fresh branch**: skip polling; reuse the cached report list for the pipeline pass below. Emit no advisory (silent within-TTL path per ADR-013 Rule 5 below-appetite silent-pass).
+
+The TTL-expiry auto-recheck is what makes the system self-healing across maintainer cadence: a maintainer who runs `/wr-itil:review-problems` once a week without the explicit flag still gets a fresh poll after the 24-hour TTL expires. The explicit `--force-upstream-recheck` flag is the pre-flight surface (JTBD-202) for tighter cadence — e.g. immediately before a release when the maintainer wants the freshest discovery state.
+
+#### 4.5c. Poll each channel
+
+For each channel in `channels[]`, run the appropriate `gh` invocation. Fail-soft per channel: missing `GH_TOKEN`, rate-limit, or HTTP error logs an advisory and skips that channel only:
+
+- `github-issues`: `gh issue list --repo <repo> --label <label> --state open --json number,title,author,createdAt,body,labels --limit 100`
+- `github-discussions`: `gh api repos/<repo>/discussions --jq '[.[] | select(.category.name == "<category>") | {number, title, author, createdAt, body}]'` (fall back to GraphQL `gh api graphql ...` if REST is insufficient for the discussions surface).
+- `github-security-advisories`: `gh api repos/<repo>/security-advisories --jq '[.[] | {ghsa_id, summary, description, author, published_at}]'`.
+
+Write the polled results to `docs/problems/.upstream-cache.json`, updating `last_checked` and the per-channel `fetched_at` + `reports` arrays. The cache file is committed to the repo for audit-replay determinism (per ADR-062).
+
+#### 4.5d. Match reports against local tickets (P070 semantic-comparator)
+
+For each fresh report (not present in the prior cache snapshot under the same `body_hash`), invoke P070's semantic-comparator infrastructure (the same comparator used by `/wr-itil:report-upstream` outbound dedup, per ADR-062 § Reassessment composes-with).
+
+**Semantic-comparator hit** → record `matched_local_ticket: P<NNN>` on the cache entry AND post a gated `gh issue comment` containing the local-ticket cross-reference (e.g., *"Tracked locally as `docs/problems/<state>/<NNN>-<title>.md` — see that ticket for the verdict trail"*). The acknowledgement comment fires through the external-comms gate (P064 risk + P038 voice-tone per ADR-028 amended). This comment is the JTBD-301 acknowledgement that the report has been received and routed; silent-skip on matched-local-ticket would break the contract per ADR-062 § Decision Drivers row 1 (every submitted report receives a verdict, even if the verdict is "duplicate of P<NNN>").
+
+**Semantic-comparator ambiguity** (multiple plausible matches) → annotate `cache_audit_note: ambiguous-match-candidates-P<X>-P<Y>-...` and DO NOT auto-route. The ambiguity surfaces at the next interactive `review-problems` invocation (the maintainer disambiguates from the cache_audit_note channel; this is the documented user-attention surface under the mechanical-stage carve-out).
+
+**No comparator hit** → continue to 4.5e.
+
+#### 4.5e. Six-step assessment pipeline
+
+For each unmatched fresh report, run these steps in order; record the outcome in the cache + audit-log.
+
+1. **Version-aware classification (P129 carve-out — stub seam)**: when P129 ships, this step compares reporter-version against closed-ticket fix-versions and routes to upgrade-pushback / recurrence / still-active. Until P129 lands: skip this step (all reports proceed to step 2). The integration seam is documented in ADR-062 § Decision Outcome step 1.
+
+2. **JTBD-alignment classifier**: invoke `wr-jtbd:agent` subagent with the report body + persona JTBDs. Three outcomes per ADR-062:
+   - `aligned-with-existing-JTBD` → continue to step 3.
+   - `aligned-with-new-JTBD-for-existing-persona` → continue to step 3 + annotate `cache_audit_note: new-jtbd-flag` on the cache entry. The flag surfaces at next interactive review for maintainer-attention; auto-creation honors JTBD-301 acknowledgement.
+   - `not-aligned` → route to step 4 (above-threshold-pushback) with reason `out-of-scope-for-documented-personas`; do NOT execute step 3.
+
+3. **Dual-axis risk classifier**: invoke `wr-risk-scorer:inbound-report` subagent (shipped Slice B) with the report body + JTBD-alignment context. Outcomes:
+   - `safe-low-fix-risk` → step 6 (safe-and-valid branch).
+   - `safe-high-fix-risk` → step 6 (safe-and-valid branch) + annotate `cache_audit_note: high-fix-risk-flag` on the cache entry.
+   - `clear-malicious-request` → step 5 (clear-malicious branch).
+   - `above-threshold-risk` → step 4 (above-threshold-pushback branch).
+
+4. **Above-threshold-pushback branch**: post a gated `gh issue comment` declining the report (the comment body names the reason — `out-of-scope-for-documented-personas` or the matched Request-risk class from step 3). Comment fires through the external-comms gate (P064 + P038 evaluators per ADR-028 amended). Upstream issue is NOT closed by the pipeline — maintainer decides closure manually after reading the pushback. Cache entry classification: `above-threshold-pushback`. Audit-log append. **Gate-denial sub-branch**: if the external-comms gate denies the comment write (either evaluator FAILs), record `cache_audit_note: gate-denied-pushback` and continue to the next report.
+
+5. **Clear-malicious branch**: post a brief gated verdict comment (JTBD-301 acknowledgement contract — silent close is forbidden per ADR-062 Decision Drivers row 1). Comment body names the policy-violation classification verbatim from the `wr-risk-scorer:inbound-report` verdict. External-comms gates ride. Then close the upstream issue via `gh issue close <id>`. Append the reporter handle + classification to `docs/audits/inbound-discovery-log.md` for P123 block-list consumption when that ticket lands. Cache entry classification: `clear-malicious-closed`. **Gate-denial sub-branch**: if the verdict-comment gate denies, record `cache_audit_note: gate-denied-clear-malicious-pre-close` and do NOT close the upstream issue (silent close is forbidden — preserve the report for the next pass).
+
+6. **Safe-and-valid branch**: invoke `/wr-itil:capture-problem --no-prompt <report-body-verbatim>` to create the local ticket. The `--no-prompt` flag defaults to `type=technical`; the maintainer re-classifies at next interactive `review-problems` re-rate. Rationale: a default of `user-business` would mis-classify security-advisory-channel reports as user-business when they're often deep technical bugs; the maintainer-re-classify path is the safety net. Verbatim body preservation honors JTBD-301 persona constraint "capture context faithfully without cognitive re-shaping" and JTBD-201 audit-trail fidelity. Then post a gated `gh issue comment` acknowledgement carrying the new local-ticket reference. Cache entry classification: `safe-and-valid-local-ticket-created`; populate `matched_local_ticket: P<NNN>` with the freshly-allocated ID. **Gate-denial sub-branch**: if the acknowledgement comment gate denies, the local ticket already exists — record `cache_audit_note: gate-denied-safe-and-valid-acknowledgement` and continue. The acknowledgement comment will retry on the next discovery pass.
+
+#### 4.5f. Audit-log append
+
+Append a `## YYYY-MM-DDTHH:MM:SSZ — Discovery pass` heading to `docs/audits/inbound-discovery-log.md` per ADR-062 § Audit-log surface shape. The entry includes:
+
+- Channels polled (N) and per-channel report counts (new vs unchanged).
+- Pipeline outcomes by classification (counts + local-ticket IDs created + upstream issues closed + audit-flagged reporter handles for P123 future consumption).
+- Cache refresh confirmation (`docs/problems/.upstream-cache.json` rewritten at `last_checked: <ISO timestamp>`).
+
+#### 4.5g. Render-time integration
+
+The `## Inbound Upstream Reports` README section (ADR-062 § Step 9e renderer per the naming-reconciliation note at the top of this section) is populated by Step 5's renderer reading `docs/problems/.upstream-cache.json` — that renderer ships in Slice G of RFC-004. This step (4.5g) is the integration seam; the renderer is the consumer.
+
+#### 4.5 AFK-loop behaviour
+
+When invoked from `/wr-itil:work-problems` Step 6.5 (AFK orchestrator), Step 4.5 runs silently per the mechanical-stage carve-out. The only user-attention surface during AFK is the existing external-comms gate UX (a known interrupt class per ADR-028 amended); per-branch `AskUserQuestion` would re-introduce the friction P132 was engineered to remove.
+
 ### 5. Rewrite `docs/problems/README.md`
 
 Write / overwrite `docs/problems/README.md` with the refreshed ranking so future `work-problem` / `list-problems` fast-paths can skip the full re-scan. Rendering rules match the SKILL.md `Present the refreshed ranking` section above — driven off globs, not file-body scans:
@@ -136,6 +229,19 @@ Fix released, awaiting user verification (driven off the dual-tolerant glob `doc
 | P<NNN> | <title> | <release marker> | <yes (N days) / no (N days)> |
 ...
 
+## Inbound Upstream Reports
+
+Inbound reports discovered by Step 4.5 (ADR-062 § Step 9e renderer per the naming-reconciliation note at the head of Step 4.5; rendered off `docs/problems/.upstream-cache.json`). Section is **lazy-empty**: when `.upstream-cache.json` has `last_checked: null` OR no channels have any reports, the section header is rendered but the table body is empty (the empty-table state itself signals "discovery has run; no reports awaiting triage"). Sorted by `created_at ASC` within each classification group.
+
+| # | Source | Title | Author | Created | Classification | Matched local ticket |
+|---|--------|-------|--------|---------|----------------|----------------------|
+| #<id> | <channel:repo> | <title> | <author> | <YYYY-MM-DD> | <safe-and-valid \| safe-high-fix-risk \| above-threshold-pushback \| clear-malicious-closed \| matched-local-ticket \| audit-flagged> | P<NNN> \| — |
+...
+
+The `Classification` column carries the assessment-pipeline verdict; see `packages/risk-scorer/agents/inbound-report.md` § Verdict combinations for branch routing. The `Matched local ticket` column carries either the local ticket ID (when the pipeline created or matched one) or `—` (when the report is pushback or audit-flagged with no local ticket created).
+
+When `docs/problems/.upstream-cache.json` is missing OR has `last_checked: null` AND no reports cached (initial state, first run), the section is rendered with a single advisory row: `_No inbound discovery pass has run yet. Run /wr-itil:review-problems to poll the configured channels._`
+
 ## Parked
 
 | ID | Title | Reason | Parked since |

package/skills/review-problems/test/inbound-channels-cache-shape.bats

@@ -0,0 +1,127 @@
+#!/usr/bin/env bats
+# Behavioural shape contract for the inbound-discovery config + cache
+# files (RFC-004 Slice A scaffold; consumed by Slice C orchestration).
+#
+# These assertions are BEHAVIOURAL per P081 — they parse the actual JSON
+# files committed under docs/problems/ and verify the documented shapes
+# hold. No SKILL/agent prose grep here; this is config-file content
+# tested via jq.
+#
+# @problem P079
+# @rfc RFC-004 (Slice A — scaffold; Slice E — coverage)
+# @adr ADR-062 (channel config + cache schemas)
+# @adr ADR-031 (docs/problems/ as the directory for cache + config files)
+# @adr ADR-052 (behavioural-tests default)
+# @adr ADR-037 (bats doc-lint — file-shape contracts)
+# @jtbd JTBD-101 (downstream-adopter non-obligation — config file is opt-in)
+# @jtbd JTBD-201 (audit-trail replay — cache file deterministic)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  CHANNELS_FILE="${REPO_ROOT}/docs/problems/.upstream-channels.json"
+  CACHE_FILE="${REPO_ROOT}/docs/problems/.upstream-cache.json"
+  AUDIT_LOG="${REPO_ROOT}/docs/audits/inbound-discovery-log.md"
+}
+
+# Skip everything if jq is absent; the maintainer's dev env has jq per
+# the existing risk-scorer scripts, but adopter clones may not. Fail-soft.
+@test "jq is available for JSON shape assertions" {
+  command -v jq
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# docs/problems/.upstream-channels.json (Slice A scaffold — committed)
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "upstream-channels.json exists" {
+  [ -f "$CHANNELS_FILE" ]
+}
+
+@test "upstream-channels.json is valid JSON" {
+  run jq '.' "$CHANNELS_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "upstream-channels.json declares the schema URL" {
+  run jq -r '."$schema"' "$CHANNELS_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" =~ upstream-channels ]]
+}
+
+@test "upstream-channels.json has a channels[] array" {
+  run jq -e '.channels | type == "array"' "$CHANNELS_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "upstream-channels.json carries ttl_seconds (cache freshness)" {
+  run jq -e '.ttl_seconds | type == "number"' "$CHANNELS_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "default config polls all three documented channel types (issues / discussions / security-advisories)" {
+  # ADR-062 § Channel config defaults: this repo's intake polls all
+  # three. Adopters can edit; the default exercises the full pipeline.
+  run jq -e '[.channels[] | .type] | contains(["github-issues"])' "$CHANNELS_FILE"
+  [ "$status" -eq 0 ]
+  run jq -e '[.channels[] | .type] | contains(["github-discussions"])' "$CHANNELS_FILE"
+  [ "$status" -eq 0 ]
+  run jq -e '[.channels[] | .type] | contains(["github-security-advisories"])' "$CHANNELS_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "each channel entry has a 'type' and 'repo' field (minimum schema)" {
+  # Every channel must name what kind (type) and which upstream (repo).
+  # Per-type additional fields (label / template / category) are optional
+  # and per-channel-kind-specific.
+  run jq -e '.channels | all(has("type") and has("repo"))' "$CHANNELS_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# docs/problems/.upstream-cache.json (Slice A scaffold — committed empty)
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "upstream-cache.json exists" {
+  [ -f "$CACHE_FILE" ]
+}
+
+@test "upstream-cache.json is valid JSON" {
+  run jq '.' "$CACHE_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "upstream-cache.json declares the schema URL" {
+  run jq -r '."$schema"' "$CACHE_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" =~ upstream-cache ]]
+}
+
+@test "upstream-cache.json has last_checked field (null or ISO timestamp)" {
+  run jq -e '.last_checked == null or (.last_checked | type == "string")' "$CACHE_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "upstream-cache.json has channels{} object (per-channel cache map)" {
+  run jq -e '.channels | type == "object"' "$CACHE_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# docs/audits/inbound-discovery-log.md (Slice D scaffold — committed)
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "inbound-discovery-log.md exists" {
+  [ -f "$AUDIT_LOG" ]
+}
+
+@test "inbound-discovery-log.md cites ADR-062 (audit-log surface contract)" {
+  run grep -nE 'ADR-062' "$AUDIT_LOG"
+  [ "$status" -eq 0 ]
+}
+
+@test "inbound-discovery-log.md is committed under docs/audits/ per P131 (NOT under .claude/)" {
+  # CLAUDE.md P131: project-generated artefacts under docs/, never .claude/.
+  # The audit-log path is intentional per ADR-062 § Audit-log surface.
+  [[ "$AUDIT_LOG" == */docs/audits/* ]]
+  [[ "$AUDIT_LOG" != */.claude/* ]]
+}

package/skills/review-problems/test/inbound-discovery-contract.bats

@@ -0,0 +1,305 @@
+#!/usr/bin/env bats
+# Contract assertions for /wr-itil:review-problems Step 4.5
+# inbound-discovery + assessment-pipeline (RFC-004 Slice C + Slice E).
+#
+# Structural assertions — Permitted Exception to the source-grep ban
+# per ADR-005 / P011 / ADR-037 / ADR-052 § Surface 2. SKILL.md prose
+# governs LLM-driven runtime behaviour; behavioural-replay testing
+# requires a synthetic agent harness (P012 master ticket; P176 follow-up
+# for the SKILL.md surface). Until that harness lands, contract bats
+# assert the load-bearing prompt elements are present so future edits
+# don't silently strip them.
+#
+# @problem P079
+# @rfc RFC-004
+# @adr ADR-062 (inbound discovery + assessment pipeline)
+# @adr ADR-028 (external-comms gate)
+# @adr ADR-044 (decision-delegation contract — category 4 mechanical-stage carve-out)
+# @adr ADR-052 (behavioural-tests default + Permitted Exception)
+# @jtbd JTBD-301 (acknowledgement contract — non-negotiable)
+# @jtbd JTBD-001 (mechanical-stage carve-out — preserve without slowing down)
+# @jtbd JTBD-006 (AFK silent path)
+# @jtbd JTBD-101 (downstream non-obligation)
+# @jtbd JTBD-201 (audit-log replay)
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Step 4.5 presence + ADR-062 naming reconciliation
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "Step 4.5 inbound-discovery section exists in SKILL.md (RFC-004 Slice C)" {
+  run grep -nE '^### 4\.5\. Inbound-discovery' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5 header preserves ADR-062 'Step 8.5' substring anchor verbatim" {
+  # ADR-062 § Confirmation criterion 1 hard-keys on the "Step 8.5"
+  # substring. SKILL.md numbering is "Step 4.5"; header cross-references
+  # ADR-062's "Step 8.5" verbatim so the criterion remains string-anchorable.
+  # Do NOT strip the "Step 8.5" substring on rename.
+  run grep -nE 'Step 8\.5' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md preserves ADR-062 'Step 9e' substring anchor verbatim" {
+  # ADR-062 § Confirmation criterion 1 final bullet hard-keys on the
+  # "Step 9e" substring (the renderer is owned by Slice G; this skill
+  # carries the cross-reference forward).
+  run grep -nE 'Step 9e' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5 naming-reconciliation HTML comment marker exists" {
+  # Architect issue 1+2: preserve both "Step 8.5" and "Step 9e" anchors
+  # via a single HTML comment so a future rename doesn't silently strip
+  # them. Comment names ADR-062 explicitly.
+  run grep -nE 'ADR-062-step-naming-reconciliation' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Step 4.5 sub-step structure (4.5a through 4.5g)
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "Step 4.5a — read channel config (docs/problems/.upstream-channels.json)" {
+  run grep -nE '4\.5a\..*[Cc]hannel config' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE '\.upstream-channels\.json' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5b — cache TTL check (docs/problems/.upstream-cache.json)" {
+  run grep -nE '4\.5b\..*[Cc]ache TTL' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE '\.upstream-cache\.json' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5c — polls all three GitHub channels (issues / discussions / security-advisories)" {
+  run grep -nE 'github-issues' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE 'github-discussions' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE 'github-security-advisories' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5d — P070 semantic-comparator with cross-reference comment on hit (JTBD-301)" {
+  # Architect issue 5: JTBD-301 acknowledgement contract requires a
+  # gated cross-reference comment on matched-local-ticket hits; silent-skip
+  # would break the contract.
+  run grep -nE '4\.5d.*[Mm]atch.*local' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE 'cross-reference' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5e — six-step assessment pipeline" {
+  run grep -nE '4\.5e\..*[Ss]ix-step assessment pipeline' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5f — audit-log append to docs/audits/inbound-discovery-log.md" {
+  run grep -nE '4\.5f\..*[Aa]udit-log' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE 'inbound-discovery-log\.md' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5g — render-time integration seam (consumed by Slice G renderer)" {
+  run grep -nE '4\.5g\..*[Rr]ender' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Slice G: Step 5 README template carries the ## Inbound Upstream Reports section
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "Step 5 README template carries the ## Inbound Upstream Reports section header (Slice G)" {
+  run grep -nE '^## Inbound Upstream Reports$' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Slice G renderer documents the lazy-empty discipline (advisory row when no pass run)" {
+  run grep -inE 'lazy-empty|No inbound discovery pass has run' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Slice G renderer documents the classification + matched-local-ticket columns" {
+  run grep -inE 'Classification.*Matched local ticket|matched.local.ticket.*column' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Six pipeline outcomes (4.5e steps 1-6)
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "Pipeline step 1 — version-aware classification stub seam (P129 carve-out)" {
+  run grep -inE 'version-aware classification.*P129|P129.*stub seam' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 2 — JTBD-alignment classifier (wr-jtbd:agent)" {
+  run grep -nE 'JTBD-alignment classifier' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE 'wr-jtbd:agent' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 3 — dual-axis risk classifier (wr-risk-scorer:inbound-report from Slice B)" {
+  run grep -inE 'dual-axis risk classifier' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE 'wr-risk-scorer:inbound-report' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 4 — above-threshold-pushback branch (gated declining comment)" {
+  run grep -nE 'above-threshold-pushback' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 5 — clear-malicious branch with verdict comment BEFORE close (JTBD-301)" {
+  # JTBD-301 acknowledgement contract: silent close is forbidden per ADR-062.
+  run grep -nE 'clear-malicious' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -inE 'verdict comment.*BEFORE close|silent close.*forbidden' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 6 — safe-and-valid branch invokes capture-problem --no-prompt" {
+  # Architect issue 3: documenting the default-technical choice explicitly
+  # so the maintainer-re-classify safety net is visible.
+  run grep -nE 'safe-and-valid' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE 'capture-problem.*--no-prompt' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Mechanical-stage carve-out (P132 / ADR-044 category 4)
+# Load-bearing test protecting JTBD-001 + JTBD-006 against inverse-P078 drift
+# per the architect's named Slice E acceptance criterion.
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "Step 4.5 cites the mechanical-stage carve-out (P132 / ADR-044)" {
+  run grep -inE 'mechanical-stage carve-out|P132' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5 explicitly forbids AskUserQuestion at the branch decision (anti-inverse-P078 drift)" {
+  # The load-bearing structural assertion per architect Slice E acceptance.
+  # If a future edit adds AskUserQuestion to the pipeline branch decision,
+  # this assertion fails and surfaces the P132 carve-out regression.
+  run grep -nE 'does NOT use .AskUserQuestion. at the branch decision' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5 cites ADR-044 category 4 (silent framework action)" {
+  run grep -nE 'ADR-044 category 4' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# JTBD-301 acknowledgement contract (non-negotiable per ADR-062)
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "JTBD-301 acknowledgement contract cited on the matched-local-ticket path (architect issue 5)" {
+  run grep -nE 'JTBD-301' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE 'JTBD-301 acknowledgement' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Per-branch gate-denial sub-branches preserve report on external-comms gate FAIL" {
+  # Silent-skip on gate-denial would break JTBD-301; the report is preserved
+  # via cache_audit_note for the next discovery pass.
+  run grep -nE '[Gg]ate-denial sub-branch' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE 'cache_audit_note' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Fail-soft contract + downstream non-obligation
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "Step 4.5 declares the fail-soft contract" {
+  run grep -inE 'fail-soft contract' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Missing channel config skips Step 4.5 (downstream-adopter non-obligation per JTBD-101)" {
+  run grep -nE 'channel config absent|missing or malformed' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -nE 'JTBD-101' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "AFK-loop silent behaviour documented" {
+  run grep -nE 'AFK-loop|AFK orchestrator.*silently' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Slice F: --force-upstream-recheck flag parsing + TTL-expiry auto-recheck
+# (Slice F replaced the Slice C SLICE-C-FLAG-STUB string-match with proper
+# tokenized flag parsing + explicit TTL-expiry branch)
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "SLICE-C-FLAG-STUB marker has been removed (Slice F replaced the stub)" {
+  # Slice F (RFC-004) replaces the Slice C string-match with proper
+  # tokenized flag parsing. The stub marker must be gone — its presence
+  # would indicate Slice F regression.
+  run grep -nE 'SLICE-C-FLAG-STUB' "$SKILL_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "--force-upstream-recheck flag documented (Slice F)" {
+  run grep -nE -- '--force-upstream-recheck' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5a parses \$ARGUMENTS as tokenized flag list (Slice F)" {
+  # Slice F replaces the Slice C string-match with proper tokenized parsing.
+  run grep -inE 'tokenize|whitespace-separated token|parse.*ARGUMENTS' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5b — TTL-expiry auto-recheck branch fires when cache_age > ttl_seconds (Slice F)" {
+  # Self-healing: maintainer who runs review-problems once a week still
+  # gets a fresh poll after the 24-hour TTL expires, without needing the
+  # explicit flag.
+  run grep -inE 'TTL-expiry auto-recheck|cache.age.*exceeds.*ttl_seconds|cache_age.*> *ttl_seconds' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5b — explicit branch for cache-fresh (within-TTL silent-pass)" {
+  # Within-TTL path is silent per ADR-013 Rule 5 below-appetite silent-pass.
+  run grep -inE 'cache-fresh branch|within-TTL|silent within-TTL' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Step 4.5a — unknown inbound-flags surface advisory rather than silently ignoring" {
+  # Defensive contract: unknown --force-upstream / --inbound- flags get
+  # named in an advisory so typos are visible (e.g. --force-upsteam-recheck).
+  run grep -inE 'Unknown.*flag.*halt|unrecognised flag' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Cross-reference integrity (ADRs + sibling JTBDs)
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "ADR-062 cross-reference present in Step 4.5 header" {
+  run grep -nE 'ADR-062' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "ADR-028 (external-comms gate) cited for gated-comment paths" {
+  run grep -nE 'ADR-028' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}