@windyroad/itil 0.21.3 → 0.21.4

package/.claude-plugin/plugin.json

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

package/package.json

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

package/skills/work-problem/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: wr-itil:work-problem
-description: Pick the highest-WSJF open or known-error problem ticket and work it — investigate, implement, commit, and release per the standard manage-problem workflow. Interactive singular variant; distinct from /wr-itil:work-problems (plural AFK orchestrator). Use this when the user asks to "work the next problem", "work the top of the queue", or "grind through one ticket".
+description: Pick the highest-WSJF open or known-error problem ticket and work it — investigate, implement, commit, and release per the standard manage-problem workflow. Selection is framework-mediated (WSJF + documented tie-break ladder per ADR-044); singular variant; distinct from /wr-itil:work-problems (plural AFK orchestrator). Use this when the user asks to "work the next problem", "work the top of the queue", or "grind through one ticket".
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill, Agent
 ---
 
 # Work Problem — Pick-and-Run
 
-Pick the highest-WSJF ticket from the current backlog and work it end-to-end. This is the **singular, interactive** entry point — one ticket per invocation, driven by an `AskUserQuestion` selection when the WSJF ranking is tied.
+Pick the highest-WSJF ticket from the current backlog and work it end-to-end. This is the **singular** entry point — one ticket per invocation. Selection is **framework-mediated** per ADR-044's Framework-Mediated Surface (Prioritisation row): the agent applies the WSJF formula + documented tie-break ladder mechanically and reports the chosen ticket + the rung that decided. The user retains direct override via `/wr-itil:work-problem <NNN>` invocation and via mid-flow correction (ADR-044 category 6).
 
 This skill is the P071 phased-landing split of `/wr-itil:manage-problem work` per ADR-010 amended Skill Granularity rule: one skill per distinct user intent. The original `/wr-itil:manage-problem work` subcommand route remains as a thin-router forwarder during the deprecation window but is scheduled for removal in `@windyroad/itil`'s next major version.
 
 ## Name distinction (work-problem vs work-problems)
 
-- **`/wr-itil:work-problem`** (singular, this skill) — one ticket per invocation. Interactive `AskUserQuestion` selection. Intended for a user who wants to dispatch the next-highest ticket and then stop.
+- **`/wr-itil:work-problem`** (singular, this skill) — one ticket per invocation. Framework-mediated selection (WSJF + tie-break ladder). Intended for a user who wants to dispatch the next-highest ticket and then stop. User-override path: `/wr-itil:work-problem <NNN>` to pin a specific ticket.
 - **`/wr-itil:work-problems`** (plural, AFK orchestrator) — loops through the backlog by WSJF, delegating each iteration to this skill (via the Agent tool, per ADR-032 + P077). Intended for AFK batch runs; non-interactive selection; stops only when nothing actionable remains.
 
 Both names coexist intentionally per P071's out-of-scope note on the naming coexistence. The plural orchestrator uses this skill as its per-iteration unit.
@@ -21,9 +21,10 @@ Both names coexist intentionally per P071's out-of-scope note on the naming coex
 
 **In scope:**
 - Read `docs/problems/README.md` when fresh; otherwise delegate the refresh to `/wr-itil:review-problems` first (never re-implement the re-scoring logic locally — same anti-fork discipline as the list-problems cache path).
-- Select the highest-WSJF ticket via `AskUserQuestion` (structured-interaction path per ADR-013 Rule 1). Present ties as peer options with per-option rationale.
+- Pick the highest-WSJF ticket via the framework-mediated tie-break ladder (Known Error > Open; smaller effort first; older reported date; ticket number ascending) per ADR-044 Framework-Mediated Surface. Report the chosen ticket + the rung that decided. No `AskUserQuestion` fires for selection.
+- Honour the user-override path `/wr-itil:work-problem <NNN>` — when the user names a ticket directly, skip the ladder and proceed to Step 3 with the named ticket.
 - Delegate the actual work to `/wr-itil:manage-problem <NNN>` via the Skill tool so the investigation / known-error transition / fix / closure flow stays hosted on a single authoritative workflow (ADR-010 thin-router discipline applied to the work path).
-- Scope-expansion prompt (ADR-013 Rule 1) when the selected ticket's effort grows during work — same three-option structure as `/wr-itil:manage-problem`'s Working a Problem section.
+- Scope-expansion prompt (ADR-013 Rule 1; ADR-044 category-2 deviation-approval surface) when the selected ticket's effort grows during work — same three-option structure as `/wr-itil:manage-problem`'s Working a Problem section.
 
 **Out of scope:**
 - Batch looping over multiple tickets — that's `/wr-itil:work-problems` (plural). This skill runs exactly one ticket per invocation.
@@ -48,23 +49,27 @@ fi
 - **Cache fresh** (no output): read `docs/problems/README.md` and use the cached WSJF Rankings table for Step 2.
 - **Cache stale** (prints "stale") or `README.md` missing: **delegate to `/wr-itil:review-problems`** via the Skill tool to refresh the ranking before proceeding. Do NOT re-implement the re-scoring logic here — that would fork the review path and break P062's canonical-cache-writer contract. The review skill's Step 4 verification prompt runs on this refresh path (P048 Candidate 1: Verification Queue prompts always fire so pending verifications don't accumulate off-ledger).
 
-### 2. Select the ticket
+### 2. Select the ticket (framework-mediated)
 
-Read the WSJF Rankings table from the now-fresh `docs/problems/README.md`. Parse the top rows to find the highest-WSJF ticket(s).
+Read the WSJF Rankings table from the now-fresh `docs/problems/README.md`. Apply the framework's tie-break ladder mechanically to pick the next ticket — selection is **framework-mediated** per ADR-044's Framework-Mediated Surface (Prioritisation row). The agent picks, reports the choice + the tie-break rung that decided, and proceeds. **No `AskUserQuestion` fires for selection** — the WSJF formula + tie-break ladder already resolve the decision.
 
-**Selection via `AskUserQuestion`** (ADR-013 Rule 1 structured-interaction path):
+**User-override path** — when the user invokes `/wr-itil:work-problem <NNN>` (ticket ID supplied as an argument, e.g. `/wr-itil:work-problem 042`), skip the ladder entirely and proceed to Step 3 with the named ticket. This is the documented escape hatch for the user to bypass the framework-mediated selection. Mid-flow correction (ADR-044 category 6 / P078 surface) is the long-tail catcher when the agent's pick was wrong in a way the framework couldn't anticipate.
 
-- **Single top-WSJF ticket** (strictly higher than all others): present as the recommended option:
-  - Option 1: `Work P<NNN>: <title> (Recommended)` — description shows WSJF score, Severity, and Status.
-  - Option 2: `Pick a different problem` — user names a specific ID in the free-form response.
-- **Tied top-WSJF tickets** (two or more tied for the highest WSJF): present each tied ticket as a peer option. Per-option description carries a one-line rationale naming the Status / Effort / concrete next action so the user can pick with context:
-  - One option per tied ticket: `Work P<NNN>: <title>` — description: `WSJF <score> · <status> · <effort> · <one-line rationale>`.
-  - Final option: `Pick a different problem`.
-- Use `header: "Next problem"` and `multiSelect: false`.
+**Tie-break ladder** (applied in order; same logic the plural orchestrator's Step 3 uses, per P077 + ADR-044):
 
-**Never present the selection as prose "(a)/(b)/(c)" or "which would you like?"** — always use `AskUserQuestion` so the decision is structured and auditable. This is the same discipline `/wr-itil:manage-problem` Step 9c carries; the split lifts it verbatim.
+1. **WSJF score** (descending) — highest WSJF wins.
+2. **Status** — Known Error before Open. Verification Pending tickets are not in this queue (handled by `/wr-itil:review-problems` Step 4 verification prompt).
+3. **Effort** — smaller effort first (S < M < L < XL).
+4. **Reported date** — older reported date wins (FIFO discipline for tied tickets at this rung).
+5. **Ticket number** — ascending (final deterministic break).
 
-**AFK / non-interactive branch (ADR-013 Rule 6)**: when this skill is invoked inside an AFK orchestrator (detect via `/wr-itil:work-problems` markers in the invoking prompt — phrases like "AFK", "work-problems", "batch-work", "ALL_DONE"), apply the within-day tiebreak per `/wr-itil:work-problems` Step 1c: Known Error > Open; smaller Effort; older reported date; ticket number ascending. Do NOT emit `AskUserQuestion` in AFK mode — the orchestrator has already selected the iteration and this skill runs the execution only.
+When a single ticket is the strict top, rungs 2-5 are not consulted. When multiple tickets are tied at the top, walk down the ladder until a rung decides.
+
+**Report shape (JTBD-201 audit-trail)** — after picking, the agent reports the chosen ticket + the rung that decided, with citations to the WSJF inputs. Example: *"Selected P042: <title> (WSJF 12.0; tied with P057 at WSJF; tie-break rung: 'Known Error > Open' — P042 is Known Error, P057 is Open)"*. This citation makes the selection reproducible from the README state at the time of the report and is the audit surface JTBD-201 requires.
+
+**No prose-ask fallback** — never present the selection as prose "(a)/(b)/(c)" or "which would you like?" (regression guard for ADR-013 Confirmation grep). Selection is mechanical; the agent picks and reports.
+
+**No AFK / interactive split** — selection is mechanical in both interactive and AFK modes. The prior asymmetry between AFK (mechanical) and interactive (`AskUserQuestion`-driven) was the lazy-deferral surface ADR-044 was written to close; converging both modes to the same algorithm is the alignment. The plural orchestrator (`/wr-itil:work-problems`) Step 3 also uses this ladder, so all entry surfaces resolve to one selection algorithm (no AFK-vs-interactive divergence to maintain).
 
 ### 3. Delegate the work to `/wr-itil:manage-problem <NNN>`
 
@@ -75,17 +80,17 @@ Invoke `/wr-itil:manage-problem <NNN>` via the Skill tool with the selected tick
 
 **Why delegate rather than re-implement:** the full investigation / transition / fix / release pipeline is a long-lived, policy-governed flow that must stay on a single authoritative workflow. Re-hosting it on a sibling skill would fork the ownership contract and compound maintenance cost. The split skill (this file) owns the *selection* of the next ticket; `/wr-itil:manage-problem <NNN>` owns the *execution*.
 
-### 4. Scope-expansion check (ADR-013 Rule 1)
+### 4. Scope-expansion check (ADR-013 Rule 1; ADR-044 category-2 deviation-approval)
 
-If the delegated `/wr-itil:manage-problem <NNN>` reports that the ticket's effort expanded during investigation or architect review (e.g. S → L, or L → XL), fire the standard scope-change `AskUserQuestion` prompt:
+If the delegated `/wr-itil:manage-problem <NNN>` reports that the ticket's effort expanded during investigation or architect review (e.g. S → L, or L → XL), fire the standard scope-change `AskUserQuestion` prompt. **Effort growth IS the contradicting evidence** against the WSJF score that ranked this ticket at the top — this is the ADR-044 **category-2 (deviation-approval)** surface. The 3-option vocabulary below is the work-item-tactical analog of the framework-tactical 5-option vocabulary (Approve+amend / Approve+supersede / Approve+one-time / Reject / Defer); the user is the right authority for the shape, so the `AskUserQuestion` is genuine, not lazy.
 
 - Option 1: `Continue with expanded scope` — keep working this ticket at its new size.
-- Option 2: `Update problem and re-rank` — save findings to the problem file, re-score WSJF, and re-run the work selection to let the user pick from the updated queue.
+- Option 2: `Update problem and re-rank` — save findings to the problem file, re-score WSJF, and re-run the framework-mediated selection to surface the new top of queue.
 - Option 3: `Pick a different problem` — park this one and work something else.
 
 Use `header: "Scope change"` and `multiSelect: false`. This is the same structure `/wr-itil:manage-problem`'s Working a Problem section documents; the split lifts it without modification.
 
-**AFK / non-interactive branch**: same ADR-013 Rule 6 fallback as `/wr-itil:work-problems` — save findings + the new Effort/WSJF lines to the ticket file and skip to the next iteration. The orchestrator owns the re-selection loop.
+**AFK / non-interactive branch (ADR-013 Rule 6)**: same fallback as `/wr-itil:work-problems` — save findings + the new Effort/WSJF lines to the ticket file and skip to the next iteration. The orchestrator owns the re-selection loop.
 
 ### 5. Post-work housekeeping
 
@@ -99,11 +104,14 @@ After the delegated `/wr-itil:manage-problem <NNN>` completes:
 
 `work-problem` (singular) owns:
 - Reading the WSJF Rankings from `docs/problems/README.md`.
-- Firing the `AskUserQuestion` selection prompt (interactive mode).
+- Applying the framework-mediated tie-break ladder for selection (ADR-044 Prioritisation row).
+- Reporting the chosen ticket + the tie-break rung that decided (JTBD-201 audit-trail).
+- Honouring the user-override path `/wr-itil:work-problem <NNN>` (skip the ladder; proceed with the named ticket).
 - Delegating one execution iteration to `/wr-itil:manage-problem <NNN>`.
-- Firing the scope-expansion `AskUserQuestion` on effort drift.
+- Firing the scope-expansion `AskUserQuestion` on effort drift (ADR-044 category-2 deviation-approval surface).
 
 `work-problem` does NOT:
+- Fire `AskUserQuestion` for the ticket selection itself — selection is framework-mediated per ADR-044.
 - Refresh the README.md cache directly — defers to `/wr-itil:review-problems`.
 - Loop over multiple tickets — that's `/wr-itil:work-problems` (plural).
 - Commit the ranking refresh or the per-ticket work — delegated skills commit per ADR-014.
@@ -111,8 +119,10 @@ After the delegated `/wr-itil:manage-problem <NNN>` completes:
 ## Related
 
 - **P071** (`docs/problems/071-argument-based-skill-subcommands-are-not-discoverable.open.md`) — originating ticket. This skill is phase 3 of the P071 phased-landing plan (list-problems was phase 1; review-problems was phase 2).
+- **P136** (`docs/problems/136-adr-044-alignment-audit-master.open.md`) — ADR-044 alignment audit master; this skill is the Phase 2 first audit target (work-problem singular).
 - **ADR-010 amended** (`docs/decisions/010-rename-wr-problem-to-wr-itil.proposed.md` — Skill Granularity section) — canonical skill-split naming + forwarder contract + `deprecated-arguments: true` frontmatter flag.
-- **ADR-013** (`docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md`) — Rule 1 for the interactive `AskUserQuestion` selection; Rule 6 for the AFK-orchestrator non-interactive branch.
+- **ADR-013 amended** (`docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md`) — Rule 1 amended in P135 to defer to ADR-044 for framework-resolution boundary. Step 4 scope-expansion is the only Rule-1 surface this skill retains; Rule 6 covers Step 4's AFK fallback.
+- **ADR-044** (`docs/decisions/044-decision-delegation-contract.proposed.md`) — Decision-Delegation Contract; this skill's Step 2 selection is framework-mediated per the ADR's Prioritisation row. Step 4 scope-expansion is a category-2 (deviation-approval) surface per the ADR's 6-class taxonomy.
 - **ADR-014** — governance skills commit their own work. The delegated `/wr-itil:manage-problem <NNN>` owns the per-ticket commit; this skill does not re-commit.
 - **ADR-018** — release cadence. AFK orchestrator owns release cadence; this skill does NOT auto-release.
 - **ADR-032** — governance skill invocation patterns. `/wr-itil:work-problems` delegates iterations via the Agent tool; this singular skill is the canonical execution unit.

package/skills/work-problem/test/work-problem-contract.bats

@@ -12,18 +12,29 @@
 # Structural assertion — Permitted Exception to the source-grep ban
 # (ADR-005 / P011 / ADR-037 contract-assertion pattern).
 #
-# @problem P071
+# tdd-review: structural-permitted (justification: SKILL.md prose contract
+# assertions; behavioural skill-runtime harness pending P012 + P081 Phase 2;
+# expected to migrate to behavioural form once the harness exists. Touched
+# during P136 Phase 2 ADR-044 alignment audit per the inline plan's
+# bridge-marker rule.)
+#
+# @problem P071 (originating split)
+# @problem P136 (ADR-044 alignment audit master — Phase 2 work-problem singular)
+# @adr ADR-044 (Decision-Delegation Contract — framework-mediated Prioritisation surface)
 # @jtbd JTBD-001 (enforce governance without slowing down — discoverable surface)
 # @jtbd JTBD-101 (extend the suite with clear patterns — one skill per distinct user intent)
+# @jtbd JTBD-201 (audit trail — selection cites the deciding tie-break rung)
 #
 # Cross-reference:
 #   P071: docs/problems/071-argument-based-skill-subcommands-are-not-discoverable.open.md
+#   P136: docs/problems/136-adr-044-alignment-audit-master.open.md
 #   ADR-010 amended (Skill Granularity section) — split naming + forwarder contract
-#   ADR-013 Rule 1 — structured user interaction (AskUserQuestion selection prompt)
-#   ADR-013 Rule 6 — AFK non-interactive fallback
+#   ADR-013 amended Rule 1 — structured user interaction; framework-resolution narrowing per ADR-044
+#   ADR-013 Rule 6 — AFK non-interactive fallback (Step 4 scope-expansion only)
 #   ADR-014 — governance skills commit their own work (delegated target owns commits)
 #   ADR-032 — governance skill invocation patterns (plural orchestrator delegates here)
 #   ADR-037 — contract-assertion bats pattern
+#   ADR-044 — Decision-Delegation Contract; Step 2 selection is framework-mediated
 
 setup() {
   SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
@@ -204,3 +215,80 @@ setup() {
   run grep -inE "P077|ADR-032" "$SKILL_FILE"
   [ "$status" -eq 0 ]
 }
+
+# ----------------------------------------------------------------------
+# P136 Phase 2 — ADR-044 alignment audit (added 2026-04-27)
+#
+# These assertions land the framework-mediated-selection contract for
+# Step 2 and the ADR-044 category-2 cross-reference for Step 4. They
+# replace the prior assertions that mandated AskUserQuestion-driven
+# selection (which was the lazy-deferral surface ADR-044 was written to
+# close).
+# ----------------------------------------------------------------------
+
+@test "SKILL.md Step 2 specifies framework-mediated selection (ADR-044 Prioritisation)" {
+  # Per ADR-044 Framework-Mediated Surface row "Prioritisation — WSJF
+  # formula + documented tie-breaks (Known Error > Open; smaller effort
+  # first; older reported date). Pick + work." Step 2 must apply the
+  # tie-break ladder mechanically rather than defer to AskUserQuestion.
+  run awk '/^### 2\./,/^### 3\./' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"framework-mediated"* ]] || [[ "$output" == *"tie-break ladder"* ]]
+  [[ "$output" == *"Known Error"* ]]
+  [[ "$output" == *"smaller"* ]]
+  [[ "$output" == *"older reported date"* ]]
+  [[ "$output" == *"ADR-044"* ]]
+}
+
+@test "SKILL.md Step 2 reports the chosen ticket + tie-break rung that decided (JTBD-201 audit-trail)" {
+  # Audit-trail outcome: the agent must cite which rung of the ladder
+  # decided the selection so the choice is reproducible from the README
+  # state at the time of the report.
+  run awk '/^### 2\./,/^### 3\./' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"report"* ]]
+  [[ "$output" == *"tie-break"* ]] || [[ "$output" == *"ladder rung"* ]]
+}
+
+@test "SKILL.md Step 2 documents user-override path via direct NNN invocation" {
+  # Selection is framework-mediated, but the user retains agency via
+  # /wr-itil:work-problem <NNN> direct invocation. Without the
+  # documented escape hatch, the user has no way to redirect except via
+  # post-hoc correction (ADR-044 category 6). The literal-form
+  # assertion guards against the substring trap where /wr-itil:work-
+  # problems (plural) accidentally satisfies a /wr-itil:work-problem
+  # substring check.
+  run awk '/^### 2\./,/^### 3\./' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"/wr-itil:work-problem <NNN>"* ]] || [[ "$output" == *"/wr-itil:work-problem <ID>"* ]] || [[ "$output" == *"\`/wr-itil:work-problem 042\`"* ]]
+}
+
+@test "SKILL.md Step 2 does NOT fire AskUserQuestion as the selection mechanism (regression guard)" {
+  # The AskUserQuestion-driven selection prompt was the lazy-deferral
+  # surface ADR-044 closed. If it returns to Step 2 the lazy-count
+  # metric (Step 2d "Ask Hygiene Pass") will spike. AskUserQuestion may
+  # appear elsewhere (Step 4 scope-expansion) but NOT inside Step 2.
+  run awk '/^### 2\./,/^### 3\./' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  ! echo "$output" | grep -qE "Selection via .?AskUserQuestion|Use .header: .Next problem"
+}
+
+@test "SKILL.md Step 4 cross-references ADR-044 category-2 (deviation-approval)" {
+  # Effort growth IS the contradicting evidence against the WSJF score
+  # that ranked this ticket at the top — it's a deviation-approval
+  # surface in the ADR-044 taxonomy. The inline cross-reference makes
+  # the framework-resolution boundary visible at the call site.
+  run awk '/^### 4\./,/^### 5\./' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"ADR-044"* ]]
+  [[ "$output" == *"deviation-approval"* ]] || [[ "$output" == *"category 2"* ]] || [[ "$output" == *"category-2"* ]]
+}
+
+@test "bats file carries the tdd-review: structural-permitted marker (P081 + P136 bridge)" {
+  # Per P136 Phase 2 inline plan: bats touched during the audit get
+  # the structural-permitted marker as the bridge until P081 Phase 2's
+  # canonical retrofit. Without the marker, future TDD agent reviews
+  # will flag the file as a P081 violation.
+  run grep -nE "tdd-review:[[:space:]]+structural-permitted" "${BATS_TEST_FILENAME}"
+  [ "$status" -eq 0 ]
+}