@windyroad/itil 0.47.12-preview.598 → 0.47.12-preview.617

package/bin/wr-itil-check-outbound-responses-staleness

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Generated by scripts/sync-shim-wrappers.sh from
+# packages/shared/lib/shim-wrapper-template.sh. DO NOT EDIT individual
+# shim files in packages/*/bin/wr-* directly; edit the template + run
+# `npm run sync:shim-wrappers` to regenerate.
+#
+# Resolution (ADR-080):
+#   1. If the wrapper's parent dir is semver-shaped, treat as installed-
+#      cache execution and resolve to the highest-version sibling's
+#      scripts/ entry below.
+#   2. Otherwise (parent dir is e.g. `architect`), treat as source-
+#      monorepo execution and dispatch to own scripts/. The source-repo-
+#      guard `exec` is the anchor parsed by
+#      packages/retrospective/scripts/check-tarball-shipped-shims.sh.
+#   3. If the cache parent contains zero semver-shaped siblings, exit
+#      127 with a stderr message naming the cache parent (per SQ-080-2).
+#
+# @adr ADR-080 (highest-version-wins shim wrapper plugin scaffold)
+# @adr ADR-049 (plugin-bundled scripts resolve via bin/ on $PATH — amended)
+# @problem P343 (mid-session staleness window)
+
+set -euo pipefail
+
+SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"
+OWN_VERSION_DIR="$(dirname "$SHIM_DIR")"
+OWN_VERSION_NAME="$(basename "$OWN_VERSION_DIR")"
+CACHE_PARENT="$(dirname "$OWN_VERSION_DIR")"
+
+SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'
+
+# Source-repo guard: own parent dir is NOT semver → dispatch to own scripts/.
+if ! [[ "$OWN_VERSION_NAME" =~ $SEMVER_RE ]]; then
+  exec "$SHIM_DIR/../scripts/run-check-outbound-responses-staleness.sh" "$@"
+fi
+
+# Cache execution: pick the highest-semver sibling under CACHE_PARENT.
+HIGHEST=""
+while IFS= read -r dir; do
+  name="$(basename "$dir")"
+  [[ "$name" =~ $SEMVER_RE ]] || continue
+  if [[ -z "$HIGHEST" ]] || [[ "$(printf '%s\n%s\n' "$HIGHEST" "$name" | sort -V | tail -1)" == "$name" ]]; then
+    HIGHEST="$name"
+  fi
+done < <(find "$CACHE_PARENT" -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+if [[ -z "$HIGHEST" ]]; then
+  printf 'wr-shim: no cached versions in %s\n' "$CACHE_PARENT" >&2
+  exit 127
+fi
+
+exec "$CACHE_PARENT/$HIGHEST/scripts/run-check-outbound-responses-staleness.sh" "$@"

package/bin/wr-itil-enumerate-postrelease-kv-candidates

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Generated by scripts/sync-shim-wrappers.sh from
+# packages/shared/lib/shim-wrapper-template.sh. DO NOT EDIT individual
+# shim files in packages/*/bin/wr-* directly; edit the template + run
+# `npm run sync:shim-wrappers` to regenerate.
+#
+# Resolution (ADR-080):
+#   1. If the wrapper's parent dir is semver-shaped, treat as installed-
+#      cache execution and resolve to the highest-version sibling's
+#      scripts/ entry below.
+#   2. Otherwise (parent dir is e.g. `architect`), treat as source-
+#      monorepo execution and dispatch to own scripts/. The source-repo-
+#      guard `exec` is the anchor parsed by
+#      packages/retrospective/scripts/check-tarball-shipped-shims.sh.
+#   3. If the cache parent contains zero semver-shaped siblings, exit
+#      127 with a stderr message naming the cache parent (per SQ-080-2).
+#
+# @adr ADR-080 (highest-version-wins shim wrapper plugin scaffold)
+# @adr ADR-049 (plugin-bundled scripts resolve via bin/ on $PATH — amended)
+# @problem P343 (mid-session staleness window)
+
+set -euo pipefail
+
+SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"
+OWN_VERSION_DIR="$(dirname "$SHIM_DIR")"
+OWN_VERSION_NAME="$(basename "$OWN_VERSION_DIR")"
+CACHE_PARENT="$(dirname "$OWN_VERSION_DIR")"
+
+SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'
+
+# Source-repo guard: own parent dir is NOT semver → dispatch to own scripts/.
+if ! [[ "$OWN_VERSION_NAME" =~ $SEMVER_RE ]]; then
+  exec "$SHIM_DIR/../scripts/run-enumerate-postrelease-kv-candidates.sh" "$@"
+fi
+
+# Cache execution: pick the highest-semver sibling under CACHE_PARENT.
+HIGHEST=""
+while IFS= read -r dir; do
+  name="$(basename "$dir")"
+  [[ "$name" =~ $SEMVER_RE ]] || continue
+  if [[ -z "$HIGHEST" ]] || [[ "$(printf '%s\n%s\n' "$HIGHEST" "$name" | sort -V | tail -1)" == "$name" ]]; then
+    HIGHEST="$name"
+  fi
+done < <(find "$CACHE_PARENT" -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+if [[ -z "$HIGHEST" ]]; then
+  printf 'wr-shim: no cached versions in %s\n' "$CACHE_PARENT" >&2
+  exit 127
+fi
+
+exec "$CACHE_PARENT/$HIGHEST/scripts/run-enumerate-postrelease-kv-candidates.sh" "$@"

package/lib/check-outbound-responses-staleness.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# Outbound-responses cache staleness check — Step 0d of /wr-itil:work-problems.
+# P220 + ADR-062 § JTBD-006 driver: work-problems should pre-flight
+# /wr-itil:check-upstream-responses when the outbound-responses cache is
+# stale or missing AND local tickets carry `## Reported Upstream` back-link
+# sections, so AFK loops keep upstream-reporter responses visible without
+# the maintainer remembering to invoke check-upstream-responses first.
+#
+# The staleness comparison is the outbound symmetric counterpart of
+# check-upstream-cache-staleness.sh's inbound-discovery contract. Any
+# change to TTL semantics MUST update this helper, the check-upstream-
+# responses SKILL.md Confirmation, and the Step 0d block in work-problems
+# SKILL.md in the same commit.
+# <!-- OUTBOUND-RESPONSES-STALENESS-CONTRACT-SOURCE: packages/itil/skills/check-upstream-responses/SKILL.md ## Confirmation -->
+#
+# Source this file, then call `should_promote_outbound_responses_preflight`:
+#   . packages/itil/lib/check-outbound-responses-staleness.sh
+#   reason="$(should_promote_outbound_responses_preflight "$PWD")"
+#
+# Output (one of):
+#   no-back-link-tickets         → no problem tickets carry a `## Reported Upstream`
+#                                  section; nothing to poll. Skip silently.
+#                                  Downstream-adopter non-obligation; analogue
+#                                  to inbound's `no-channels-config`.
+#   first-run-cache-absent       → back-link tickets exist, cache file absent.
+#                                  Dispatch check-upstream-responses.
+#   first-run-last-checked-null  → cache present but last_checked is null.
+#                                  Dispatch check-upstream-responses.
+#   fresh-within-ttl             → cache within TTL; silent-pass.
+#   ttl-expiry age=<N>s ttl=<M>s → cache older than TTL; dispatch.
+#
+# TTL source: cache.ttl_seconds if present, else 86400 (24h) — symmetric
+# with the inbound axis default at packages/itil/lib/check-upstream-cache-staleness.sh.
+#
+# Dependencies: bash 4+, jq, python3 (for ISO-8601 parsing — portable across
+# Linux/BSD date implementations).
+
+should_promote_outbound_responses_preflight() {
+  local repo_root="${1:-$PWD}"
+  local problems_dir="$repo_root/docs/problems"
+  local cache_file="$problems_dir/.outbound-responses-cache.json"
+
+  if [ ! -d "$problems_dir" ]; then
+    echo "no-back-link-tickets"
+    return 0
+  fi
+
+  # Scan for `## Reported Upstream` back-link sections. Dual-tolerant per
+  # RFC-002: flat layout `<NNN>-*.<status>.md` AND per-state subdir layout
+  # `<status>/<NNN>-*.md`. Use grep -l (files-with-match); silent on
+  # zero matches via the `|| true` short-circuit.
+  local back_link_count
+  back_link_count="$(
+    grep -lE '^## Reported Upstream$' \
+      "$problems_dir"/[0-9][0-9][0-9]-*.md \
+      "$problems_dir"/*/[0-9][0-9][0-9]-*.md \
+      2>/dev/null | wc -l | tr -d ' '
+  )"
+
+  if [ "${back_link_count:-0}" -eq 0 ]; then
+    echo "no-back-link-tickets"
+    return 0
+  fi
+
+  if [ ! -f "$cache_file" ]; then
+    echo "first-run-cache-absent"
+    return 0
+  fi
+
+  local last_checked
+  last_checked="$(jq -r '.last_checked // ""' "$cache_file")"
+
+  if [ -z "$last_checked" ] || [ "$last_checked" = "null" ]; then
+    echo "first-run-last-checked-null"
+    return 0
+  fi
+
+  local ttl_seconds
+  ttl_seconds="$(jq -r '.ttl_seconds // 86400' "$cache_file")"
+
+  local last_checked_epoch now_epoch cache_age
+  last_checked_epoch="$(python3 -c "import datetime,sys; ts=sys.argv[1].replace('Z','+00:00'); print(int(datetime.datetime.fromisoformat(ts).timestamp()))" "$last_checked" 2>/dev/null || echo "0")"
+  now_epoch="$(date +%s)"
+  cache_age=$((now_epoch - last_checked_epoch))
+
+  if [ "$cache_age" -gt "$ttl_seconds" ]; then
+    echo "ttl-expiry age=${cache_age}s ttl=${ttl_seconds}s"
+    return 0
+  fi
+
+  echo "fresh-within-ttl"
+  return 0
+}

package/lib/enumerate-postrelease-kv-candidates.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+# Enumerate Known Error problem tickets whose Release-vehicle citation
+# points at a just-shipped changeset — input to the work-problems
+# Step 6.5 Post-release K→V auto-transition callback (P228).
+#
+# Driver: ADR-022 prescribes K→V transition on release, but until P228
+# there was no auto-fire surface to back-fill the transition once a fix
+# ships. Iter subprocesses defer K→V to "the next session" citing a
+# misapplied P143 amendment, and tickets accumulate in
+# `docs/problems/known-error/` with `## Fix Released` populated but no
+# transition. The 2026-06-08 P220 empirical witness confirmed the gap.
+#
+# Composes with `wr-itil-derive-release-vehicle` (P267) — the derive
+# helper's exit-code contract is the filter:
+#   exit 0  → changeset has been deleted from the working tree AND has a
+#             deletion commit in git history (released to npm). Emit as
+#             KV_CANDIDATE.
+#   exit 2  → no `.changeset/<name>.md` reference in ticket body
+#             (legacy ticket pre-P330). Skip silently.
+#   exit 3  → changeset still present in working tree (unreleased).
+#             Skip silently.
+#   other   → log to stderr, skip.
+#
+# Source this file, then call `enumerate_postrelease_kv_candidates`:
+#   . packages/itil/lib/enumerate-postrelease-kv-candidates.sh
+#   enumerate_postrelease_kv_candidates "$PWD/docs/problems" \
+#     "wr-itil-derive-release-vehicle"
+#
+# Stdout (multi-line):
+#   KV_CANDIDATE: P<NNN> | <changeset-path>
+#   ...
+#   KV_CANDIDATES_SUMMARY: total=<N>
+#
+# Exit: 0 always (idempotent — safe to invoke when the directory is
+#        empty or absent). Stderr carries non-fatal warnings.
+#
+# Glob — targets `docs/problems/known-error/*.md` directly (per-state
+# subdir layout per ADR-031). Flat-layout tickets are NOT in scope — the
+# adopter has already migrated when this callback fires (work-problems
+# Step 0a auto-migrate runs before Step 6.5).
+#
+# Cross-references:
+#   @problem P228 (K→V auto-transition gap)
+#   @problem P220 (empirical witness)
+#   @problem P267 (derive-release-vehicle composed helper)
+#   @problem P330 (Release vehicle seed reference — input signal)
+#   @adr ADR-022 (Verifying lifecycle)
+#   @adr ADR-018 (release-cadence host of the callback)
+#   @adr ADR-031 (per-state subdir layout — glob target)
+#   @adr ADR-049 (bin/ PATH shim — adopter-safe script resolution)
+#   @adr ADR-005 (behavioural bats per P081)
+#   @jtbd JTBD-006 (Progress the Backlog While I'm Away — primary driver)
+#   @jtbd JTBD-001 (Enforce Governance Without Slowing Down — audit trail)
+
+enumerate_postrelease_kv_candidates() {
+  local problems_dir="${1:-docs/problems}"
+  local derive_cmd="${2:-wr-itil-derive-release-vehicle}"
+  local kedir="$problems_dir/known-error"
+  local total=0
+
+  if [ ! -d "$kedir" ]; then
+    printf 'KV_CANDIDATES_SUMMARY: total=0\n'
+    return 0
+  fi
+
+  local saved_nullglob
+  saved_nullglob="$(shopt -p nullglob)"
+  shopt -s nullglob
+
+  local f
+  for f in "$kedir"/*.md; do
+    local bn
+    bn="$(basename "$f")"
+    [ "$bn" = "README.md" ] && continue
+
+    local nnn
+    nnn="$(printf '%s\n' "$bn" | grep -oE '^[0-9]+' | head -1)"
+    [ -z "$nnn" ] && continue
+
+    local derive_out derive_exit
+    derive_out="$("$derive_cmd" "$nnn" "$problems_dir" 2>/dev/null)"
+    derive_exit=$?
+
+    case "$derive_exit" in
+      0)
+        local changeset
+        changeset="$(printf '%s\n' "$derive_out" \
+          | grep -oE '\.changeset/[a-z0-9._-]+\.md' \
+          | head -1)"
+        printf 'KV_CANDIDATE: P%03d | %s\n' "$((10#$nnn))" "$changeset"
+        total=$((total + 1))
+        ;;
+      2|3)
+        ;;
+      *)
+        printf 'enumerate-postrelease-kv-candidates: derive helper exit=%d for P%03d (skipped)\n' \
+          "$derive_exit" "$((10#$nnn))" >&2
+        ;;
+    esac
+  done
+
+  eval "$saved_nullglob"
+
+  printf 'KV_CANDIDATES_SUMMARY: total=%d\n' "$total"
+  return 0
+}

package/package.json

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

package/scripts/run-check-outbound-responses-staleness.sh

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+# wr-itil — echo the outbound-responses-preflight promotion reason, or empty
+# if promotion is not warranted (P220 + P317/RFC-009).
+#
+# Adopter-safe wrapper: sources the canonical lib RELATIVE TO THIS SCRIPT
+# (`$(dirname)/../lib`), then echoes the function's result on stdout (the SKILL
+# captures it via `$(...)`). Replaces any SKILL-inline
+# `source packages/itil/lib/check-outbound-responses-staleness.sh;
+#  preflight_reason="$(should_promote_outbound_responses_preflight "$PWD")"`,
+# which only resolves in the source monorepo (P317). SKILLs invoke this by name
+# via the `wr-itil-check-outbound-responses-staleness` PATH shim (ADR-049).
+# Operates on the directory given as $1 (defaults to $PWD).
+set -uo pipefail
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
+  echo "wr-itil-check-outbound-responses-staleness: cannot locate lib next to the script" >&2
+  exit 2
+}
+# shellcheck source=/dev/null
+source "$LIB/check-outbound-responses-staleness.sh"
+should_promote_outbound_responses_preflight "${1:-$PWD}"

package/scripts/run-enumerate-postrelease-kv-candidates.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# wr-itil — emit `KV_CANDIDATE` lines for Known Error tickets whose
+# Release-vehicle citation matches a just-shipped (deleted-from-tree)
+# changeset (P228 / P317 RFC-009 adopter-safe).
+#
+# Adopter-safe wrapper: sources the canonical lib RELATIVE TO THIS SCRIPT
+# (`$(dirname)/../lib`), then invokes the function. The SKILL parses the
+# emitted lines via `$(...)`. Mirrors the
+# `run-check-deferred-placeholder-staleness.sh` precedent — never `source
+# packages/...` repo-relative from a SKILL; those paths only resolve in
+# the source monorepo, not adopter installs.
+#
+# SKILLs invoke this by name via the
+# `wr-itil-enumerate-postrelease-kv-candidates` PATH shim (ADR-049 +
+# ADR-080).
+#
+# Arguments (positional, all optional):
+#   $1 — problems-dir (defaults to ./docs/problems)
+#   $2 — derive-helper command name (defaults to
+#        `wr-itil-derive-release-vehicle`)
+set -uo pipefail
+
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
+  echo "wr-itil-enumerate-postrelease-kv-candidates: cannot locate lib next to the script" >&2
+  exit 2
+}
+# shellcheck source=/dev/null
+source "$LIB/enumerate-postrelease-kv-candidates.sh"
+enumerate_postrelease_kv_candidates "$@"

package/skills/check-upstream-responses/SKILL.md

@@ -37,7 +37,7 @@ Out of scope:
   [--force-recheck]        ignore cache; treat all as new
 ```
 
-Future iter will wire `/wr-itil:work-problems` Step 0c pre-flight to invoke this skill when the outbound cache is stale (sibling to Step 0b inbound cache check per ADR-062 Confirmation #5). Phase 1 ships manual-invocation only.
+`/wr-itil:work-problems` Step 0d pre-flights this skill when the outbound-responses cache is stale or missing AND back-link tickets exist (sibling to Step 0b inbound cache check per ADR-062 Confirmation #5; P220 closed the cadence gap). Direct user invocation remains a first-class surface.
 
 ## AFK behaviour
 
@@ -101,11 +101,13 @@ If the cumulative pipeline risk lands above appetite and `AskUserQuestion` is un
 Three invocation surfaces:
 
 1. **Direct user invocation** — `/wr-itil:check-upstream-responses` (or with flags). The default user-facing surface.
-2. **AFK orchestrator pre-flight** (future iter) — `/wr-itil:work-problems` Step 0c will invoke this skill when the outbound cache is stale, mirroring Step 0b's inbound staleness check per ADR-062 Confirmation #5. This wiring is deferred to a future iter; Phase 1 ships manual only.
+2. **AFK orchestrator pre-flight** — `/wr-itil:work-problems` Step 0d invokes this skill when the outbound-responses cache is stale, missing, or has `last_checked: null` AND back-link tickets exist, mirroring Step 0b's inbound staleness check per ADR-062 Confirmation #5. Cache TTL defaults to 86400s (24h) symmetric with the inbound axis. P220 closed the cadence gap.
 3. **Manual investigation during a problem-management session** — when a maintainer wants to see if any upstream reports moved before transitioning a `verifying` ticket back to `closed`. Foreground synchronous; the maintainer reads the inline summary and decides next steps.
 
 ## Confirmation
 
+<!-- OUTBOUND-RESPONSES-STALENESS-CONTRACT-SOURCE: packages/itil/skills/check-upstream-responses/SKILL.md ## Confirmation -->
+
 This skill's contract holds when:
 
 1. The script `packages/itil/scripts/check-upstream-responses.sh` is read-only externally — only `gh issue view` (no `gh issue comment`, no `gh issue create`, no `gh api`).
@@ -114,6 +116,7 @@ This skill's contract holds when:
 4. After a successful pass, the audit-log file exists and has a new `## YYYY-MM-DDTHH:MM:SSZ` heading appended.
 5. The skill is AFK-safe: zero `AskUserQuestion` calls, zero external-comms gate triggers.
 6. The exit code distinguishes success (0), error (1), and partial failure (2) so AFK orchestrators can branch correctly.
+7. **Staleness contract (P220)**: TTL defaults to 86400s (24h) symmetric with the inbound axis. Override via `ttl_seconds` field in the cache file. The Step 0d pre-flight helper at `packages/itil/lib/check-outbound-responses-staleness.sh` MUST stay symmetric with this contract — any change to TTL semantics MUST update the helper, the Step 0d SKILL block in `/wr-itil:work-problems`, and this Confirmation #7 in the same commit.
 
 ## ADR alignment
 

package/skills/review-problems/SKILL.md

@@ -204,12 +204,36 @@ Write the polled results to `docs/problems/.upstream-cache.json`, updating `last
 
 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 hit** → record `matched_local_ticket: P<NNN>` on the cache entry AND post a gated `gh issue comment` carrying the **duplicate** verdict per the JTBD-301 contract briefed at `#### 4.5e-comment-shape` below. The matched-local-ticket cross-reference comment template is the one named below at 4.5e-comment-shape § Branch templates → "Duplicate verdict (matched-local-ticket)". Do NOT post the legacy boilerplate *"Tracked locally as `docs/problems/<state>/<NNN>-<title>.md`"* — that was the P229 leak shape (framework-vocab path; bureaucratic; no verdict). 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-comment-shape — JTBD-301 verdict-shape contract (P229)
+
+The four ack-comment branches below (4.5d cross-reference + 4.5e steps 4 / 5 / 6) post **reporter-facing** comments on the upstream surface (`gh issue comment <id> --repo <owner>/<repo>`). Per JTBD-301 Desired Outcome row 6 — *"Submitted reports receive a predictable acknowledgement: labelled, routed into the maintainers' problem-management queue, and eventually responded to with a verdict (fix released / parked / duplicate / won't-fix)"* — every ack body MUST carry a **verdict** in **plain-language** so the reporter (plugin-user persona — low context on repo internals) can act on it without reading ADRs or source.
+
+**Symmetry with `/wr-itil:report-upstream` (ADR-024 / ADR-036)**: outbound report bodies use structured human-language (e.g. report-upstream § Step 5 structured-default body shape). The inbound ack mirrors the same shape: human-language verdict + actionable expectation + no maintainer-internal jargon. The two surfaces (outbound report, inbound ack) are the two sides of one trust contract; both ride the same external-comms gate (ADR-028) and the same persona constraints.
+
+**Anti-leakage rule (load-bearing)**: comment bodies MUST NOT contain **maintainer-internal framework vocab** — Step IDs (e.g. "Step 4.5e"), branch names (e.g. "safe-and-valid branch"), classification tokens (e.g. "safe-low-fix-risk", "out-of-scope-for-documented-personas"), or path syntax (e.g. `docs/problems/<state>/<NNN>-<title>.md`). The maintainer-internal vocabulary belongs in the **audit-log surface** (4.5f — `docs/audits/inbound-discovery-log.md`) and the **cache entry classification** (4.5g — `docs/problems/.upstream-cache.json`), not in user-facing comments. The P229 root-cause leak — *"classified via /wr-itil:review-problems Step 4.5e safe-and-valid branch with safe-low-fix-risk"* posted across 31 ack comments — is the canonical anti-pattern this contract forbids. Architect Issue C2: **the external-comms gate fires on the substituted body, not on the template** — when a template author substitutes `P<NNN>`, `<reason>`, `<classification>`, `<plugin>` etc., they MUST ensure the substituted values stay plain-language (e.g. plain-language gloss for `<classification>`, not raw verdict token). Substitution-time leak is the residual failure mode the gate cannot catch at template-author time.
+
+**Verdict vocabulary (JTBD-301 four-verdict + fifth implicit)**:
+
+| Verdict | Branch | When | Plain-language ack |
+|---|---|---|---|
+| **fix released** | (future — `/wr-itil:transition-problem` Known Error → Verifying, separate surface) | when the local ticket transitions to Verifying | (existing transition-time comment; out of scope for this contract — surfaces verdict at fix-ship time) |
+| **accepted into backlog** | 4.5e Step 6 (safe-and-valid) | report passes JTBD-alignment + dual-axis risk; local ticket created | "Thanks for the report. We're tracking this as a real bug — local ticket P<NNN>. The fix will ship in a future release of `@windyroad/<plugin>`; we don't have a firm date yet. Watch this issue for updates, or check our [release notes](<link>) — we'll comment here when the fix lands." (Architect C3: the **fix released** JTBD-301 verdict is post-release; this branch fires at accept-into-backlog time. Name the branch **accepted into backlog**; the **fix released** verdict surfaces later at the Known Error → Verifying transition.) |
+| **duplicate** | 4.5d (matched-local-ticket cross-reference) | semantic-comparator hits a local ticket | "Thanks for the report. We're tracking this as a duplicate of P<NNN> — see that ticket for the verdict trail. Future updates will appear on this issue when the local ticket transitions." |
+| **won't-fix** | 4.5e Step 4 (above-threshold-pushback) | JTBD-not-aligned OR above-threshold Request-risk | "We don't plan to fix this — here's why: <plain-language reason>. We track problems labelled `problem` in this repo; this report falls outside that scope. The issue stays open for your reference; close it whenever you're done." |
+| **policy-violation close** (fifth implicit verdict — architect C4) | 4.5e Step 5 (clear-malicious) | clear-malicious-request classifier hit | "We're closing this report. Reason: <plain-language gloss of the policy class — e.g. 'this matches behaviour we've classified as spam / off-topic / disclosure-bypass'>, not the raw `wr-risk-scorer:inbound-report` verdict token. If you believe this is a mistake, please file a new report describing what you're trying to accomplish." |
+
+The first four (fix-released / accepted-into-backlog / duplicate / won't-fix) map to JTBD-301's four documented verdicts. The fifth (policy-violation close) is a **stronger** verdict than won't-fix (it's an immediate close, not "we considered it and declined") and is named here precisely so the SKILL prose doesn't conflate clear-malicious with won't-fix. clear-malicious is a maintainer-side intervention; won't-fix is a deliberation outcome. The reporter sees different verdict language for the two cases.
+
+**Maintainer-side audit-log unchanged**: the classification tokens (`safe-and-valid-local-ticket-created`, `above-threshold-pushback`, `clear-malicious-closed`, `matched-local-ticket`) remain on the audit-log surface (4.5f) and on the cache-entry `Classification` column (4.5g) verbatim per ADR-062 § Audit-log surface shape — only the reporter-facing comment body strips them. This preserves replay determinism for the inbound-discovery audit trail; the user-side template change is reporter-facing only.
+
+Architect Issue A1 / behavioural bats: each branch template MUST preserve its existing **gate-denial sub-branch** (`cache_audit_note: gate-denied-<branch>`). The verdict-shape rewrite is body-content only; the gate-denial fall-through wiring stays intact across all four branches so JTBD-301 acknowledgement is preserved on the next discovery pass when the gate denies.
+
 #### 4.5e. Six-step assessment pipeline
 
 For each unmatched fresh report, run these steps in order; record the outcome in the cache + audit-log.
@@ -227,11 +251,11 @@ For each unmatched fresh report, run these steps in order; record the outcome in
    - `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.
+4. **Above-threshold-pushback branch (won't-fix verdict)**: post a gated `gh issue comment` carrying the **won't-fix verdict** per the 4.5e-comment-shape contract above — body uses the "We don't plan to fix this — here's why: <reason>" template. The `<reason>` substitution MUST be a plain-language gloss (e.g. *"this request would require us to expose internal-only API surface area we deliberately don't expose"*, not the raw `out-of-scope-for-documented-personas` token). The raw token belongs on the maintainer-side audit-log (4.5f), not in the reporter-facing comment body. 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` (maintainer-internal token; remains on cache + audit-log surface). 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).
+5. **Clear-malicious branch (policy-violation close verdict — fifth implicit verdict per 4.5e-comment-shape table)**: post a brief gated verdict comment per the 4.5e-comment-shape contract — body uses the "We're closing this report. Reason: <plain-language gloss>" template. The `<plain-language gloss>` MUST translate the `wr-risk-scorer:inbound-report` verdict into reporter-readable language (e.g. *"spam / off-topic / disclosure-bypass"*, not the raw verdict-class token). Architect C4: name this verdict as **policy-violation close**, NOT won't-fix — clear-malicious is a stronger close than won't-fix (immediate close vs. deliberated decline). The classification gloss is a load-bearing anti-leakage requirement (JTBD non-blocking advisory): the SKILL contract explicitly forbids substituting the raw `wr-risk-scorer:inbound-report` verdict token into the reporter-facing body. The raw token still ships to the maintainer-side audit-log surface (4.5f) verbatim per ADR-062 § Audit-log surface shape. JTBD-301 acknowledgement contract — silent close is forbidden per ADR-062 Decision Drivers row 1. 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. **Stamp the inbound origin (ADR-076)**: the skeleton writes `**Origin**: internal` by default — Edit it on the freshly-created ticket to `**Origin**: inbound-reported (#<id>)` (the upstream issue/discussion `<id>` polled this pass) so the ADR-076 reported-first tier ranks it ahead of internal tickets. The on-ticket `**Origin**` field, not the regenerable cache, is the authoritative rank input (ADR-076); the cache's `matched_local_ticket` remains the audit/replay record. 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.
+6. **Safe-and-valid branch (accepted-into-backlog verdict)**: 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. **Stamp the inbound origin (ADR-076)**: the skeleton writes `**Origin**: internal` by default — Edit it on the freshly-created ticket to `**Origin**: inbound-reported (#<id>)` (the upstream issue/discussion `<id>` polled this pass) so the ADR-076 reported-first tier ranks it ahead of internal tickets. The on-ticket `**Origin**` field, not the regenerable cache, is the authoritative rank input (ADR-076); the cache's `matched_local_ticket` remains the audit/replay record. 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` carrying the **accepted-into-backlog verdict** per the 4.5e-comment-shape contract above — body uses the "Thanks for the report. We're tracking this as a real bug — local ticket P<NNN>. The fix will ship in a future release of `@windyroad/<plugin>`; we don't have a firm date yet. Watch this issue for updates, or check our [release notes](<link>) — we'll comment here when the fix lands." template. The `<plugin>` substitution is the package name (e.g. `itil`, `architect`, `retrospective`); the `<link>` substitution is the package's CHANGELOG URL on npm or GitHub. Do NOT include the legacy P229 leak phrasing *"classified via /wr-itil:review-problems Step 4.5e safe-and-valid branch with safe-low-fix-risk"* in the comment body — that's the canonical anti-leakage failure mode (see 4.5e-comment-shape above). The token `safe-low-fix-risk` belongs to the maintainer-side audit-log only and the cache-entry classification column (4.5g), not in user-facing comments. 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