@windyroad/itil 0.48.0-preview.654 → 0.49.0

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.48.0"
+  "version": "0.49.0"
 }

package/README.md

@@ -87,6 +87,7 @@ See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for th
 | `/wr-itil:reconcile-readme` | Detect and correct drift between `docs/problems/README.md` and on-disk ticket inventory | Experimental |
 | `/wr-itil:report-upstream` | Report a local problem as a structured issue against an upstream repository (ADR-024) | Experimental |
 | `/wr-itil:check-upstream-responses` | Poll upstream issues we filed via `/wr-itil:report-upstream` and surface new comments / state changes / label changes since last check (P249 Phase 1; outbound symmetric counterpart to ADR-062 inbound discovery) | Experimental |
+| `/wr-itil:update-upstream` | Post a lifecycle-update comment to an upstream issue when a local problem ticket transitions — root-cause confirmed / fix released / closed; reciprocal sibling to `/wr-itil:report-upstream` (ADR-024 amendment 2026-06-09, P080 Phase 1) | Experimental |
 | `/wr-itil:capture-rfc` | Lightweight RFC-capture skill — mandatory problem-trace per ADR-060 I1 invariant; opens a coordinated multi-commit change traceable to ≥ 1 driving problem (Phase 1 of the Problem-RFC-Story framework, P170 / ADR-060) | Experimental |
 | `/wr-itil:manage-rfc` | Heavyweight RFC intake + lifecycle management — proposed → accepted → in-progress → verifying → closed; sibling to `manage-problem` at the RFC tier (ADR-060) | Experimental |
 | `/wr-itil:capture-story` | Lightweight story-capture skill — mandatory problem-trace AND JTBD-trace per ADR-060 I6 + I9 invariants; optional `--rfc` / `--story-map` flags (I7 + I8 enforce at `accepted` transition); drafts an INVEST-shaped sub-workstream entity under a parent RFC (Phase 2 of the Problem-RFC-Story framework, P170 / ADR-060) | Experimental |

package/package.json

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

package/skills/review-problems/SKILL.md

@@ -222,7 +222,7 @@ The four ack-comment branches below (4.5d cross-reference + 4.5e steps 4 / 5 / 6
 
 | 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) |
+| **fix released** | (a) `/wr-itil:transition-problem` Known Error → Verifying — post-release surface; (b) 4.5e Step 4b inbound-discovery upgrade-pushback — Phase 1 of P129 (already-fixed-in-newer sub-shape) | (a) when the local ticket transitions to Verifying; (b) when an inbound report arrives on a reporter-version older than a matched closed ticket's `## Fix Released` version anchor | (a) existing transition-time comment; (b) 4.5e Step 4b upgrade-pushback body — "Thanks for the report. This was fixed in `@windyroad/<pkg>@<fix-version>` — please upgrade to that version or later. We're tracking the closed local ticket as `P<NNN>` if you'd like the verdict trail. If you still see this after upgrading, please file a new report describing what you're seeing on the newer version." The `<pkg>` substitution is the package name (e.g. `itil`, `architect`); `<fix-version>` is the version anchor extracted from the matched closed ticket's `## Fix Released` section (the exact version the fix shipped in, NOT the latest release — if the reporter is on `0.18.0` and the fix shipped in `0.20.0`, name `0.20.0` so the reporter has the precise upgrade target). `P<NNN>` is the matched closed-ticket ID — disclosing it preserves JTBD-301 audit-trail symmetry with the 4.5d `duplicate` verdict (which already discloses the matched P-id), and is NOT framework-vocab leakage (P229) because P-ids are reporter-readable verdict anchors, not Step IDs or classification tokens. Cache classification for surface (b): `already-fixed-in-newer`. |
 | **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." |
@@ -238,7 +238,18 @@ Architect Issue A1 / behavioural bats: each branch template MUST preserve its ex
 
 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.
+1. **Version-aware classification (P129 — Phase 1: already-fixed-in-newer branch; Phase 2 recurrence DEFERRED)**: compare reporter-version against closed-ticket fix-versions and route. Phase 1 ships the **already-fixed-in-newer** branch only; Phase 2 ships the recurrence-class lifecycle (P129 Phase 2 — `cache_audit_note: phase2-recurrence-deferred-bug-shape-match-against-P<NNN>` flags candidates encountered until Phase 2 lands).
+
+   **Inputs**: reporter-version line parsed from the inbound report body's `## Versions` section per the ADR-033 amendment (P128) schema — extract the `- Local plugin: @windyroad/<pkg>@<version>` line. If the `## Versions` section is absent or the `Local plugin` line is missing/unparseable (e.g. `not detected`), record `cache_audit_note: phase1-version-missing` and proceed to step 2 (treat as still-active — the report still routes through the full pipeline). The closed-ticket-history matcher is the same P070 semantic-comparator invoked at 4.5d but walked against `docs/problems/closed/*.md` instead of the live ranking corpus.
+
+   **Procedure**: invoke the semantic-comparator against `docs/problems/closed/*.md`. On hit, attempt best-effort fix-version extraction from the matched closed ticket's `## Fix Released` section — look for a version anchor in this priority order: (a) explicit `@windyroad/<pkg>@X.Y.Z` token, (b) explicit `vX.Y.Z` / `X.Y.Z` version tag adjacent to "released", "shipped", or "fixed in", (c) commit SHA — best-effort resolve to the first changeset publishing that SHA (skip if unresolvable). If fix-version extraction succeeds and reporter-version is **strictly less than** the extracted fix-version (semver compare), emit the `already-fixed-in-newer` classification. If extraction fails, log `cache_audit_note: phase1-fix-version-extraction-failed-P<NNN>` and proceed to step 2 — best-effort heuristic-miss is safe (maintainer re-discovers the duplication via the next `/wr-itil:review-problems` re-rank; no silent loss).
+
+   **Three Step 1 outcomes**:
+   - **`already-fixed-in-newer`** → route to **Step 4b (upgrade-pushback verdict — sub-shape of `fix released`)** below; do NOT open a local ticket. Cache classification: `already-fixed-in-newer`. The architect verdict on P129 Phase 1 (2026-06-09) confirms this is a sub-shape of the existing JTBD-301 `fix released` verdict surfaced at inbound-discovery time (vs. the post-release Known Error → Verifying transition surface), not a 6th verdict-shape row in the 4.5e-comment-shape table — preserves the JTBD-301 four-verdict contract integrity.
+   - **`recurred-in-newer-version`** → **DEFERRED to Phase 2**. For Phase 1: record `cache_audit_note: phase2-recurrence-deferred-bug-shape-match-against-P<NNN>` (names the matched closed ticket so Phase 2 can backfill the recurrence-link), then continue to step 2 (still-active path — opens a fresh local ticket as if net-new; the cache_audit_note surfaces at next interactive review for maintainer disambiguation). This is strictly additive vs. the pre-P129 baseline; no JTBD-201 audit-trail regression.
+   - **`still-active`** (no comparator hit, OR reporter-version >= fix-version, OR version-extraction failed) → continue to step 2 unchanged.
+
+   **Mechanical-stage carve-out (ADR-044 category 4 / P132)**: Step 1 classification is silent — no `AskUserQuestion` at the branch decision. User-attention surfaces ONLY at the external-comms gate UX (Step 4b's upgrade-pushback comment ride) and at ambiguity-edge `cache_audit_note` surfaces recorded for the next interactive review.
 
 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.
@@ -253,6 +264,8 @@ For each unmatched fresh report, run these steps in order; record the outcome in
 
 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.
 
+4b. **Upgrade-pushback branch (fix-released sub-shape — P129 Phase 1)**: routed in from Step 1's `already-fixed-in-newer` outcome only. Post a gated `gh issue comment` carrying the **fix-released-via-upgrade-pushback verdict** per the 4.5e-comment-shape contract row (b) above — body uses the "Thanks for the report. This was fixed in `@windyroad/<pkg>@<fix-version>` — please upgrade to that version or later. We're tracking the closed local ticket as `P<NNN>` if you'd like the verdict trail. If you still see this after upgrading, please file a new report describing what you're seeing on the newer version." template. The `<pkg>`, `<fix-version>`, and `P<NNN>` substitutions are bound by Step 1's classification context (matched closed-ticket ID + extracted fix-version anchor). Do NOT open a local ticket — the absence-of-ticket is correct because no new investigation is needed (architect verdict 2026-06-09; JTBD verdict 2026-06-09 confirmed against JTBD-301 outcome row 6). The reporter's "file a new report" escape hatch preserves the plugin-user persona's agency without forcing reclassification (JTBD verdict 2026-06-09 — persona-fit constraint on `docs/jtbd/plugin-user/persona.md`'s "Low context on repo internals" row). 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 upgrade-pushback. **Anti-leakage (P229)**: the comment body MUST NOT contain framework-internal vocab — Step IDs ("Step 4b", "4.5e Step 1"), branch names ("already-fixed-in-newer", "upgrade-pushback", "fix-released sub-shape"), classification tokens, or `docs/problems/<state>/<NNN>-<title>.md` path syntax. The plain-language `@windyroad/<pkg>@<fix-version>` upgrade target + reporter-readable `P<NNN>` ticket anchor are the only structured tokens permitted. Cache entry classification: `already-fixed-in-newer` (maintainer-internal token; remains on cache + audit-log surface 4.5f per ADR-062 § Audit-log surface shape). Audit-log append. **Gate-denial sub-branch**: if the external-comms gate denies the comment write, record `cache_audit_note: gate-denied-already-fixed-in-newer-upgrade-pushback` and continue to the next report (the upgrade-pushback comment will retry on the next discovery pass — JTBD-301 acknowledgement preserved). **Mechanical-stage carve-out (ADR-044 category 4 / P132)**: this branch resolves silently from Step 1's classification; do NOT call `AskUserQuestion` at the verdict-comment delegation step. User-attention surfaces ONLY at the existing external-comms gate UX.
+
 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 (accepted-into-backlog verdict)**: invoke `/wr-itil:capture-problem --no-prompt <report-body-verbatim>` to create the local ticket. The `--no-prompt` flag is the AFK mode marker for the I12 derive-then-ratify dispatch per ADR-060 Amendment 2026-06-02 — capture-problem derives persona + JTBD from the report body; on derivation-failure (no JTBD-NNN citations + no `--persona=` / `--jtbd=` flags supplied), capture halts-with-stderr-directive and no ticket is created (record `cache_audit_note: gate-denied-safe-and-valid-derive-failure`; the report stays uncaptured pending interactive maintainer triage). **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. 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.

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

@@ -138,8 +138,86 @@ setup() {
 # 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"
+@test "Pipeline step 1 — version-aware classification (P129 Phase 1 already-fixed-in-newer; Phase 2 recurrence deferred)" {
+  # Phase 1 landed: SKILL.md Step 1 now carries the version-aware classifier
+  # for the already-fixed-in-newer branch. Phase 2 (recurrence-class lifecycle)
+  # remains deferred and is captured via the cache_audit_note Phase 2 token.
+  run grep -inE 'version-aware classification.*P129.*Phase 1|P129.*Phase 1.*already-fixed-in-newer' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 1 — already-fixed-in-newer classification token present (P129 Phase 1)" {
+  run grep -nE 'already-fixed-in-newer' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 1 — Phase 2 recurrence deferred with cache_audit_note phase2-recurrence-deferred token" {
+  # Phase 2 deferral is recorded as a strictly additive cache_audit_note so
+  # Phase 2 can backfill the recurrence-link when it lands; the matched
+  # closed-ticket ID is named on the note so Phase 2 has a backfill anchor.
+  run grep -nE 'phase2-recurrence-deferred-bug-shape-match' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 1 — Versions section parse per ADR-033 amendment / P128 schema" {
+  # The classifier inputs depend on the inbound report carrying a parsable
+  # `## Versions` section per P128's schema (`- Local plugin: @windyroad/<pkg>@<version>`).
+  # If P128's schema regresses, this anchor surfaces the dependency.
+  run grep -inE 'Versions section.*P128|## Versions.*P128|Local plugin.*@windyroad' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 1 — missing-version fail-soft fallback (phase1-version-missing)" {
+  # When the reporter's `## Versions` section is absent or `Local plugin` is
+  # unparseable, Step 1 logs `cache_audit_note: phase1-version-missing` and
+  # proceeds to step 2 (treats as still-active). Required by the fail-soft
+  # contract at 4.5 head; protects JTBD-301 acknowledgement.
+  run grep -nE 'phase1-version-missing' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 1 — fix-version-extraction-failed fail-soft fallback" {
+  # When fix-version extraction from the matched closed ticket's
+  # `## Fix Released` section fails (best-effort heuristic miss), Step 1
+  # logs `cache_audit_note: phase1-fix-version-extraction-failed-P<NNN>`
+  # and proceeds to step 2. Maintainer re-discovers the duplication via
+  # the next /wr-itil:review-problems re-rank; no silent loss.
+  run grep -nE 'phase1-fix-version-extraction-failed' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 4b — upgrade-pushback branch (P129 Phase 1 fix-released sub-shape)" {
+  # New sub-branch wired by Step 1's already-fixed-in-newer outcome.
+  # Posts a gated upgrade-pushback comment under the fix-released verdict
+  # row of the 4.5e-comment-shape contract. Architect verdict 2026-06-09
+  # confirmed this as a sub-shape (not a 6th verdict-shape row) to
+  # preserve the JTBD-301 four-verdict contract.
+  run grep -inE '4b\..*Upgrade-pushback|Upgrade-pushback branch.*P129' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 4b — no local ticket created on already-fixed-in-newer (Phase 1 contract)" {
+  # JTBD verdict 2026-06-09: the absence-of-ticket is correct because no
+  # new investigation is needed; the "file a new report" escape hatch
+  # preserves the plugin-user persona's agency.
+  run grep -inE 'Do NOT open a local ticket|absence-of-ticket is correct' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 4b — anti-leakage (P229) preserved on upgrade-pushback body" {
+  # Comment bodies MUST NOT carry framework-internal vocab — Step IDs,
+  # branch names, classification tokens, or path syntax. The only
+  # structured tokens permitted are the plain-language upgrade target
+  # `@windyroad/<pkg>@<fix-version>` + the reporter-readable `P<NNN>` anchor.
+  run grep -inE 'Anti-leakage \(P229\).*4b|MUST NOT contain framework-internal vocab' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "Pipeline step 4b — gate-denial sub-branch records gate-denied-already-fixed-in-newer-upgrade-pushback" {
+  # Symmetry with the existing gate-denial sub-branches on Steps 4 / 5 / 6.
+  # The upgrade-pushback comment retries on next discovery pass —
+  # JTBD-301 acknowledgement is preserved across gate denials.
+  run grep -nE 'gate-denied-already-fixed-in-newer-upgrade-pushback' "$SKILL_FILE"
   [ "$status" -eq 0 ]
 }