@windyroad/itil 0.5.0-preview.116 → 0.6.0-preview.118

package/.claude-plugin/plugin.json

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

package/package.json

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

package/skills/manage-incident/SKILL.md

@@ -210,7 +210,7 @@ linked_id=<extracted from Linked Problem section>
 linked_file=$(ls docs/problems/${linked_id}-*.md 2>/dev/null | head -1)
 ```
 
-- If `linked_file` ends with `.known-error.md` or `.closed.md` → close is allowed
+- If `linked_file` ends with `.known-error.md`, `.verifying.md`, or `.closed.md` → close is allowed (per ADR-022: `.verifying.md` means root cause is confirmed AND fix has been released, which satisfies the "Restored → Closed" handoff at least as well as Known Error did under the old contract)
 - If `linked_file` ends with `.open.md` → close is blocked; report "Linked problem ${linked_id} is still Open. Transition it to Known Error first, or update the Linked Problem reference."
 - If no linked problem and the file has a **No Problem** section → close is allowed
 

package/skills/manage-problem/SKILL.md

@@ -21,19 +21,22 @@ When referencing problem IDs, ADR IDs, or JTBD IDs in prose output, always inclu
 - **Work**: `problem work` — runs a review first, then begins working the highest-WSJF problem
 - **Review**: `problem review` — re-assess all open problems: update priorities per RISK-POLICY.md, estimate effort, calculate WSJF, and update files
 
-**Closing problems:** Problems are closed ONLY after the user verifies the fix in production — not when the fix is committed or released. The workflow:
-1. When the fix is released: add a `## Fix Released` section to the known-error file (e.g., `Deployed in v0.26.X. Awaiting user verification.`). Keep the file as `.known-error.md`.
-2. When the user explicitly confirms ("it's fixed", "verified", "working"): `git mv` to `.closed.md`, update the Status field, and reference the problem in the commit message (e.g., "Closes P008").
+**Closing problems:** Problems are closed ONLY after the user verifies the fix in production — not when the fix is committed or released. The workflow (per ADR-022):
+1. When the fix is released: `git mv` the file from `.known-error.md` to `.verifying.md`, update the Status field to "Verification Pending", AND add a `## Fix Released` section (e.g., `Deployed in v0.26.X. Awaiting user verification.`). All three edits land in the same commit per ADR-014.
+2. When the user explicitly confirms ("it's fixed", "verified", "working"): `git mv` from `.verifying.md` to `.closed.md`, update the Status field to "Closed", and reference the problem in the commit message (e.g., "Closes P008").
 3. Never assume the fix works — always wait for explicit user confirmation before closing.
 
+The `.verifying.md` suffix distinguishes "fix released, awaiting user verification" from "root cause confirmed, fix not yet implemented" (the Known Error meaning pre-release). See ADR-022 for rationale.
+
 ## Problem Lifecycle
 
 | Status | File suffix | Meaning | Entry criteria |
 |--------|-----------|---------|----------------|
 | **Open** | `.open.md` | Reported, under investigation | New problem identified |
-| **Known Error** | `.known-error.md` | Root cause confirmed, fix path clear | Root cause documented, reproduction test exists, workaround in place |
+| **Known Error** | `.known-error.md` | Root cause confirmed, fix path clear, **fix NOT yet released** | Root cause documented, reproduction test exists, workaround in place |
+| **Verification Pending** | `.verifying.md` | Fix released, awaiting user verification (ADR-022) | Fix shipped; `## Fix Released` section written; user action remaining |
 | **Parked** | `.parked.md` | Blocked on upstream or suspended by user decision | Upstream blocker identified, or user explicitly suspends; reason and un-park trigger documented |
-| **Closed** | `.closed.md` | Fix verified in production | Fix released AND user explicitly confirms it works |
+| **Closed** | `.closed.md` | Fix verified in production | User explicitly confirms the released fix works |
 
 **Parked problems** are excluded from WSJF ranking and work selection. They are listed separately in review output so users can see them without them polluting the backlog. To park a problem:
 1. `git mv docs/problems/<NNN>-<title>.<current>.md docs/problems/<NNN>-<title>.parked.md`
@@ -42,6 +45,8 @@ When referencing problem IDs, ADR IDs, or JTBD IDs in prose output, always inclu
 
 To un-park: `git mv` back to `.open.md` (or `.known-error.md` if root cause is confirmed), update Status, remove `## Parked` section.
 
+**Verification Pending problems** are also excluded from WSJF ranking — their remaining work is user-side verification, not dev effort. They appear in a dedicated "Verification Queue" section in review output so the user can see what's waiting on them without mixing with dev-work ranking. See step 9c for the queue layout.
+
 **Test-driven resolution:** When root cause is identified, create a failing test that reproduces the problem. Skip/disable the test if a feature-disabling workaround is applied. Re-enable the test when the permanent fix is implemented — the test passing confirms resolution.
 
 ## WSJF Prioritisation
@@ -58,6 +63,10 @@ Problems are ranked using Weighted Shortest Job First (WSJF):
 |--------|-----------|
 | Known Error | 2.0 |
 | Open | 1.0 |
+| Verification Pending | 0 (excluded) |
+| Parked | 0 (excluded) |
+
+`Verification Pending` and `Parked` tickets are excluded from the main dev-work ranking per ADR-022 (verification) and the Parked policy above. `Verification Pending` remaining work is user-side confirmation, not dev effort, so mixing it into the dev-work queue would distort WSJF. Both are surfaced in dedicated sections (see step 9c) — not in the ranked table.
 
 **Effort** (estimated fix size — smaller effort = higher priority):
 
@@ -251,6 +260,8 @@ Apply the update — this could be:
 
 **Open → Known Error** (rename file, update content):
 
+Known Error means "root cause confirmed, fix path clear, fix NOT yet released" (per ADR-022). Releasing the fix is a separate Known Error → Verification Pending transition — do NOT stay on `.known-error.md` after the fix ships.
+
 Pre-flight checks before allowing transition:
 - [ ] Root cause is documented (not just "Preliminary Hypothesis")
 - [ ] At least one investigation task is checked off
@@ -266,7 +277,29 @@ git mv docs/problems/<NNN>-<title>.open.md docs/problems/<NNN>-<title>.known-err
 
 Update the "Status" field in the file to "Known Error".
 
-**Closing** requires user verification in production — see "Closing problems" above. When the fix is released, add a `## Fix Released` section but keep as `.known-error.md`. Only close when the user confirms.
+**Known Error → Verification Pending** (fix released, per ADR-022):
+
+When the fix for a Known Error ships, transition the ticket in a single commit:
+
+```bash
+git mv docs/problems/<NNN>-<title>.known-error.md docs/problems/<NNN>-<title>.verifying.md
+```
+
+Then edit the file:
+- Update the "Status" field to "Verification Pending"
+- Add a `## Fix Released` section with: release marker (version, commit SHA, or date), one-sentence fix summary, "Awaiting user verification" line, and any exercise evidence from the releasing session.
+
+Both the `git mv` and the file edits belong in the same commit as the fix implementation per ADR-014 (governance skills commit their own work). The `.verifying.md` suffix signals to every downstream consumer (work-problems classifier, review step 9d, README rendering) that the remaining work is user-side verification — no file-body scan needed.
+
+**Verification Pending → Closed** (user confirms):
+
+Only the user can make this call. When they explicitly confirm the fix works in production:
+
+```bash
+git mv docs/problems/<NNN>-<title>.verifying.md docs/problems/<NNN>-<title>.closed.md
+```
+
+Update the "Status" field to "Closed". Reference the problem ID in the closure commit message (e.g., "Closes P008"). Step 9d's verification prompt is the structured path that fires this transition during `manage-problem review`.
 
 ### 8. For list: Show summary
 
@@ -301,9 +334,9 @@ If the command prints "stale", or `README.md` does not exist in git, run the ful
 
 Read `RISK-POLICY.md` to get the current impact levels (1-5), likelihood levels (1-5), risk matrix, and label bands. These are the authoritative definitions — do not use outdated scales.
 
-**Step 9b: For each open/known-error problem (skip `.parked.md` files entirely):**
+**Step 9b: For each open/known-error problem (skip `.parked.md` and `.verifying.md` files entirely):**
 
-Parked problems are excluded from WSJF ranking — do not read, score, or update them in this step. They are shown in a separate section in step 9c.
+Parked problems and Verification Pending problems are excluded from WSJF ranking — do not read, score, or update them in this step. Parked tickets are shown in a dedicated Parked section in step 9c; Verification Pending tickets are shown in a dedicated Verification Queue section in step 9c (ranked by release age, not WSJF — per ADR-022).
 
 1. Read the problem file
 2. Read the codebase context — check if the problem's root cause has been investigated, if there are related fixes in git history, or if the problem is stale
@@ -321,11 +354,16 @@ Parked problems are excluded from WSJF ranking — do not read, score, or update
 
 **Step 9c: Present summary and select problem to work**
 
-After reviewing all problems, present a WSJF-ranked table for open/known-error problems:
+After reviewing all problems, present a WSJF-ranked table for open/known-error problems (the main dev-work queue):
 
 | WSJF | ID | Title | Severity | Status | Effort | Notes |
 |------|-----|-------|----------|--------|--------|-------|
 
+Then present a separate **Verification Queue** section for `.verifying.md` files (per ADR-022 — ranked by release age, oldest first; no WSJF because the multiplier is 0):
+
+| ID | Title | Released | Fix summary |
+|----|-------|----------|-------------|
+
 Then present a separate **Parked** section listing `.parked.md` files (no ranking):
 
 | ID | Title | Reason | Parked since |
@@ -336,7 +374,7 @@ Highlight:
 - Problems that were auto-transitioned to known-error
 - Problems that may be stale (reported > 2 weeks ago with no investigation progress)
 - Problems that have been fixed but not closed (check git history for fix commits)
-- Known errors with a `## Fix Released` section (pending user verification)
+- Verification Pending tickets whose fix has been exercised repeatedly without regression (P048 detection layer — candidate for closure verification)
 
 **When the operation is `work` (not just `review`), select the problem to work using `AskUserQuestion`:**
 
@@ -352,7 +390,7 @@ Highlight:
 
 **Step 9d: Check for pending verifications**
 
-For each known-error that has a `## Fix Released` section, use `AskUserQuestion` to ask the user if the fix has been verified in production. The question MUST include a fix summary extracted from the `## Fix Released` section — include the first sentence (or first bullet list) of that section in the question body or as the option description, so the user can answer without reading the full problem file. Do not ask with only the problem ID + title + version. If the user confirms, close the problem (`git mv` to `.closed.md`, update Status). If the user says no or is unsure, leave it as known-error.
+Target `docs/problems/*.verifying.md` via glob — do NOT scan `.known-error.md` bodies for a `## Fix Released` section (per ADR-022, Verification Pending is a first-class status, not a substring marker). For each `.verifying.md` file, use `AskUserQuestion` to ask the user if the fix has been verified in production. The question MUST include a fix summary extracted from the `## Fix Released` section — include the first sentence (or first bullet list) of that section in the question body or as the option description, so the user can answer without reading the full problem file. Do not ask with only the problem ID + title + version. If the user confirms, close the problem (`git mv` from `.verifying.md` to `.closed.md`, update Status). If the user says no or is unsure, leave it as Verification Pending.
 
 **Step 9e: Update files and refresh README.md cache**
 
@@ -371,6 +409,15 @@ Edit each problem file where the priority changed. Then write/overwrite `docs/pr
 | <score> | P<NNN> | <title> | <severity> | <status> | <effort> |
 ...
 
+## Verification Queue
+
+Fix released, awaiting user verification (driven off `docs/problems/*.verifying.md` via glob — per ADR-022). Ranked by release age, oldest first:
+
+| ID | Title | Released | Fix summary |
+|----|-------|----------|-------------|
+| P<NNN> | <title> | <release marker> | <one-sentence fix summary> |
+...
+
 ## Parked
 
 | ID | Title | Reason | Parked since |
@@ -417,9 +464,10 @@ Commit the completed work per ADR-014 (governance skills commit their own work):
 3. `git commit -m "<message>"` using the convention for the operation type:
    - New problem: `docs(problems): open P<NNN> <title>`
    - Known Error transition: `docs(problems): P<NNN> known error — <root cause summary>`
+   - Verification Pending transition: usually folded into the `fix(<scope>): ... (closes P<NNN>)` commit that ships the fix — the `git mv` to `.verifying.md` and the `## Fix Released` section land together. If transitioning without a fix commit, use `docs(problems): P<NNN> verification pending — <release marker>`.
    - Problem closed: `docs(problems): close P<NNN> <title>`
    - Review/re-rank: `docs(problems): review — re-rank priorities`
-   - Fix implemented: `fix(<scope>): <description> (closes P<NNN>)` — include problem file changes in the same commit
+   - Fix implemented: `fix(<scope>): <description> (closes P<NNN>)` — include problem file changes (rename to `.verifying.md` + `## Fix Released` section) in the same commit per ADR-022
 4. If risk is above appetite: use `AskUserQuestion` to ask whether to commit anyway, remediate first, or park the work. If `AskUserQuestion` is unavailable, skip the commit and report the uncommitted state clearly (ADR-013 Rule 6 fail-safe). This applies only to the risk-above-appetite branch, not to the delegation-unavailable case above.
 
 ### 12. Auto-release when changesets are queued (ADR-020)

package/skills/manage-problem/test/manage-problem-verification-pending.bats

@@ -0,0 +1,114 @@
+#!/usr/bin/env bats
+# Doc-lint guard: manage-problem / work-problems / manage-incident SKILL.md
+# files must document the Verification Pending lifecycle status per ADR-022.
+# README.md template must present a Verification Queue section driven off the
+# `.verifying.md` glob.
+#
+# Structural assertion — Permitted Exception to the source-grep ban
+# (ADR-005 / P011). These tests assert that the three skill specification
+# documents and the README template contain the status contract introduced
+# by ADR-022 (Problem lifecycle — Verification Pending).
+#
+# Migration of existing `.known-error.md` files to `.verifying.md` is a
+# separate follow-up commit per ADR-022 Scope; these tests cover only the
+# documentation/contract changes that land in this iteration.
+#
+# Cross-reference:
+#   ADR-022: docs/decisions/022-problem-lifecycle-verification-pending-status.proposed.md
+#   P049: docs/problems/049-known-error-status-overloaded-with-fix-released-substate.*.md
+#   P048: docs/problems/048-manage-problem-does-not-detect-verification-candidates.open.md
+#   ADR-011: docs/decisions/011-manage-incident-skill.proposed.md
+#   ADR-014: docs/decisions/014-governance-skills-commit-their-own-work.proposed.md
+#   @jtbd JTBD-001 (enforce governance without slowing down)
+#   @jtbd JTBD-006 (progress the backlog while I'm away)
+#   @jtbd JTBD-101 (extend the suite with clear patterns)
+#   @jtbd JTBD-201 (restore service fast with an audit trail)
+
+setup() {
+  TEST_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")" && pwd)"
+  # Test file lives at packages/itil/skills/manage-problem/test/ — walk up to the
+  # repo root and then into the three SKILL.md locations.
+  REPO_ROOT="$(cd "${TEST_DIR}/../../../../.." && pwd)"
+  MANAGE_PROBLEM="${REPO_ROOT}/packages/itil/skills/manage-problem/SKILL.md"
+  WORK_PROBLEMS="${REPO_ROOT}/packages/itil/skills/work-problems/SKILL.md"
+  MANAGE_INCIDENT="${REPO_ROOT}/packages/itil/skills/manage-incident/SKILL.md"
+  README_FILE="${REPO_ROOT}/docs/problems/README.md"
+}
+
+@test "ADR-022 exists (P049 precondition)" {
+  [ -f "${REPO_ROOT}/docs/decisions/022-problem-lifecycle-verification-pending-status.proposed.md" ] || \
+    [ -f "${REPO_ROOT}/docs/decisions/022-problem-lifecycle-verification-pending-status.accepted.md" ]
+}
+
+@test "manage-problem SKILL.md exists (P049 precondition)" {
+  [ -f "$MANAGE_PROBLEM" ]
+}
+
+@test "manage-problem SKILL.md lifecycle table includes Verification Pending status (P049 + ADR-022)" {
+  # ADR-022 Confirmation item 1: the lifecycle table must carry
+  # "Verification Pending | .verifying.md" as a first-class row.
+  run grep -inE "Verification Pending" "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+  run grep -inE "\.verifying\.md" "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem SKILL.md WSJF multiplier table documents Verification Pending exclusion (P049 + ADR-022)" {
+  # ADR-022 Confirmation item 1: status multiplier table must carry a row
+  # with the new status and either multiplier 0 OR explicit "excluded"
+  # wording. Accept either so future tuning within the ADR's "reassessment
+  # criteria" envelope doesn't require this test to change.
+  run grep -inE "Verification Pending.*(0|excluded)|excluded.*Verification Pending" "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem SKILL.md documents the Known Error to Verification Pending transition (P049 + ADR-022)" {
+  # ADR-022 Scope line 61: the skill must describe the Known Error →
+  # Verification Pending transition explicitly (git mv + Status field
+  # update + Fix Released section in the same commit).
+  run grep -inE "(Known Error|\.known-error\.md).*(→|->|to).*(Verification Pending|\.verifying\.md)|git mv.*\.verifying\.md" "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem SKILL.md review step 9 targets .verifying.md via glob or suffix (P049 + ADR-022)" {
+  # ADR-022 Confirmation: step 9d targets *.verifying.md via glob rather
+  # than scanning .known-error.md bodies.
+  run grep -inE "\*\.verifying\.md|\.verifying\.md.*glob|glob.*\.verifying\.md" "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem SKILL.md review step 9 has a Verification Queue section (P049 + ADR-022)" {
+  # ADR-022 Scope line 63: dedicated Verification Queue section parallel to
+  # the main ranked table.
+  run grep -inE "Verification Queue" "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem SKILL.md cites ADR-022 (P049)" {
+  # Traceability: the skill must cite the ADR that governs the status
+  # contract so reviewers can chase the decision from the implementation.
+  run grep -n "ADR-022" "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+@test "work-problems SKILL.md classifier uses the .verifying.md suffix (P049 + ADR-022)" {
+  # ADR-022 Scope line 67: work-problems classifier becomes suffix-based
+  # rather than file-body-scan-based.
+  run grep -inE "\.verifying\.md" "$WORK_PROBLEMS"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-incident SKILL.md linked-problem close gating accepts .verifying.md (P049 + ADR-022)" {
+  # ADR-022 Scope line 68: incident close gating accepts .verifying.md
+  # alongside .known-error.md and .closed.md; .open.md still blocks.
+  run grep -inE "\.verifying\.md" "$MANAGE_INCIDENT"
+  [ "$status" -eq 0 ]
+}
+
+@test "docs/problems/README.md template has a Verification Queue section (P049 + ADR-022)" {
+  # ADR-022 Scope line 69: README replaces the hand-maintained "Known Errors
+  # (Fix Released — pending verification)" shadow table with a Verification
+  # Queue driven off the glob.
+  run grep -inE "Verification Queue" "$README_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/work-problems/SKILL.md

@@ -43,6 +43,7 @@ Read `docs/problems/README.md` if it exists and is fresh (check via git history
 Exclude:
 - `.closed.md` files (done)
 - `.parked.md` files (blocked on upstream)
+- `.verifying.md` files (Verification Pending — fix released, awaiting user verification per ADR-022; surfaced in the Verification Queue section, never in dev-work ranking)
 - Problems with no WSJF score (need a review first — run `/wr-itil:manage-problem review` as the first iteration if scores are missing)
 
 ### Step 2: Check stop conditions
@@ -91,8 +92,8 @@ Read the problem file and apply these deterministic rules:
 
 | Problem state | Action | Skip-reason category |
 |---|---|---|
-| Known Error with `## Fix Released` | **Skip** — needs user verification | user-answerable (verification) |
-| Known Error with fix strategy documented | **Work it** — implement the fix | — |
+| `.verifying.md` (Verification Pending, per ADR-022) | **Skip** — fix released, awaiting user verification | user-answerable (verification) |
+| Known Error with fix strategy documented | **Work it** — implement the fix (on release, transition to `.verifying.md` per ADR-022) | — |
 | Known Error without fix strategy | **Work it** — produce a fix strategy, then implement | — |
 | Open problem with preliminary hypothesis or investigation notes | **Work it** — continue the investigation | — |
 | Open problem with no leads (empty Root Cause Analysis) | **Work it** — read the relevant code, form a hypothesis, document findings | — |