@windyroad/itil 0.3.2-preview.75 → 0.3.3-preview.77

package/package.json

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

package/skills/manage-problem/SKILL.md

@@ -28,8 +28,16 @@ Create, update, or transition problem tickets following an ITIL-aligned problem
 |--------|-----------|---------|----------------|
 | **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 |
+| **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 |
 
+**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`
+2. Update the Status field to "Parked"
+3. Add a `## Parked` section with: reason for parking, expected trigger to un-park, date parked
+
+To un-park: `git mv` back to `.open.md` (or `.known-error.md` if root cause is confirmed), update Status, remove `## Parked` section.
+
 **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
@@ -225,11 +233,29 @@ Read all `.open.md` and `.known-error.md` files in `docs/problems/`. Extract ID,
 
 This is a batch operation that reviews every open/known-error problem and updates it.
 
+**Fast-path for `work` (skip full re-scan when cache is fresh):**
+
+Before running the full review, check whether `docs/problems/README.md` exists and is up to date:
+
+```bash
+find docs/problems -name "*.md" ! -name "README.md" -newer docs/problems/README.md 2>/dev/null | head -1
+```
+
+If this command produces **no output** (README.md is newer than all problem files), the cache is fresh:
+- Read `docs/problems/README.md` only — it contains the ranked table from the last review
+- Skip steps 9a–9b entirely
+- Proceed directly to step 9c (work selection) using the cached table
+- Note in the output: "Using cached ranking from [timestamp in README.md]"
+
+If the command produces output, or `README.md` does not exist, run the full review (steps 9a–9e) and refresh the cache.
+
 **Step 9a: Read the risk framework**
 
 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:**
+**Step 9b: For each open/known-error problem (skip `.parked.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.
 
 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
@@ -247,11 +273,16 @@ Read `RISK-POLICY.md` to get the current impact levels (1-5), likelihood levels
 
 **Step 9c: Present summary and select problem to work**
 
-After reviewing all problems, present a WSJF-ranked table:
+After reviewing all problems, present a WSJF-ranked table for open/known-error problems:
 
 | WSJF | ID | Title | Severity | Status | Effort | Notes |
 |------|-----|-------|----------|--------|--------|-------|
 
+Then present a separate **Parked** section listing `.parked.md` files (no ranking):
+
+| ID | Title | Reason | Parked since |
+|----|-------|--------|-------------|
+
 Highlight:
 - Problems whose priority changed (↑ or ↓)
 - Problems that were auto-transitioned to known-error
@@ -275,10 +306,33 @@ Highlight:
 
 For each known-error that has a `## Fix Released` section, use `AskUserQuestion` to ask the user if the fix has been verified in production. 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.
 
-**Step 9e: Update files**
+**Step 9e: Update files and refresh README.md cache**
+
+Edit each problem file where the priority changed. Then write/overwrite `docs/problems/README.md` with the current ranked table so future `work` invocations can skip the full re-scan:
+
+```markdown
+# Problem Backlog
+
+> Last reviewed: <ISO timestamp>
+> Run `/wr-itil:manage-problem review` to refresh.
+
+## WSJF Rankings
+
+| WSJF | ID | Title | Severity | Status | Effort |
+|------|-----|-------|----------|--------|--------|
+| <score> | P<NNN> | <title> | <severity> | <status> | <effort> |
+...
+
+## Parked
+
+| ID | Title | Reason | Parked since |
+|----|-------|--------|-------------|
+| P<NNN> | <title> | <reason> | <date> |
+...
+```
 
-Edit each problem file where the priority changed. Then commit the updated files per ADR-014:
-1. `git add` the changed problem files
+Then commit all changed files per ADR-014:
+1. `git add` the changed problem files and `docs/problems/README.md`
 2. Delegate to `wr-risk-scorer:pipeline` to assess and create a bypass marker
 3. `git commit -m "docs(problems): review — re-rank priorities"`
 If `AskUserQuestion` is unavailable and risk is above appetite, skip the commit and report the uncommitted state.

package/skills/manage-problem/test/manage-problem-no-prose-options.bats

@@ -44,3 +44,20 @@ setup() {
   run grep -n "which way?" "$SKILL_FILE"
   [ "$status" -ne 0 ]
 }
+
+@test "SKILL.md mandates AskUserQuestion for work-next selection (WSJF tie-break)" {
+  # ADR-013 Rule 1: the step 9c work-selection branch must use AskUserQuestion,
+  # not a prose '(a)/(b)/(c)' list. This is a regression guard — if step 9c is
+  # edited and the AskUserQuestion mandate is removed, this test catches it.
+  # P021 investigation task: manage-problem WSJF tie → assert AskUserQuestion.
+  run grep -n "AskUserQuestion" "$SKILL_FILE"
+  [ "$status" -eq 0 ]   # file MUST reference AskUserQuestion
+}
+
+@test "SKILL.md mandates AskUserQuestion for scope-change decisions during work" {
+  # ADR-013 Rule 1: the 'Scope expansion during work' branch must use AskUserQuestion.
+  # 'Scope change' is the header text used in the AskUserQuestion call for scope decisions
+  # (per P021 amendment). Regression guard.
+  run grep -n "Scope change" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/manage-problem/test/manage-problem-parked-and-cache.bats

@@ -0,0 +1,68 @@
+#!/usr/bin/env bats
+# Doc-lint guard: manage-problem SKILL.md must define the Parked lifecycle
+# status and the README.md fast-path cache for the `work` operation.
+#
+# Structural assertions — Permitted Exception to the source-grep ban (ADR-005 / P011).
+# These tests assert that the skill specification document conforms to the
+# P027 fix: first-class Parked status + README.md-based WSJF cache.
+#
+# Cross-reference:
+#   P027: docs/problems/027-manage-problem-work-flow-is-expensive.open.md
+#   @jtbd JTBD-001 (enforce governance without slowing down — under 60s)
+#   @jtbd JTBD-005 (invoke governance assessments on demand)
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Parked lifecycle status
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "SKILL.md lifecycle table includes Parked status" {
+  # P027: Parked must be a first-class status so parked problems are
+  # auto-excluded from work selection without manual user flags each session.
+  run grep -q "Parked" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md defines .parked.md file suffix" {
+  # Parked problems need a distinct file suffix so the review step can
+  # identify and exclude them by filename pattern alone.
+  run grep -q "\.parked\.md" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md excludes parked problems from WSJF ranking" {
+  # Parked problems must not appear in the WSJF table — they are listed
+  # separately so users can see them but they don't pollute the ranking.
+  run grep -q "parked.*exclud\|exclud.*parked\|Parked.*exclud\|exclud.*Parked\|skip.*[Pp]arked\|[Pp]arked.*skip" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ──────────────────────────────────────────────────────────────────────────────
+# README.md cache (fast-path for `problem work`)
+# ──────────────────────────────────────────────────────────────────────────────
+
+@test "SKILL.md references README.md as the cache file" {
+  # P027: docs/problems/README.md is the WSJF cache written by review
+  # and read by work to skip the full re-scan when nothing changed.
+  run grep -q "README\.md" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md describes writing README.md after review" {
+  # The review step (9e) must write/overwrite README.md with the ranked table.
+  # Without this write, the cache never gets populated.
+  run grep -q "README\.md" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md describes checking README.md freshness before full re-scan" {
+  # The work fast-path: if README.md is newer than all problem files,
+  # skip the 18-file re-scan and read the cached table directly.
+  # Proxy: SKILL.md mentions -newer (the find flag used for mtime comparison).
+  run grep -q "\-newer" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}