@windyroad/itil 0.8.0 → 0.9.0-preview.142

package/.claude-plugin/plugin.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.8.0",
+  "version": "0.9.0-preview.142",
   "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

@@ -39,9 +39,10 @@ The `.verifying.md` suffix distinguishes "fix released, awaiting user verificati
 | **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`
-2. Update the Status field to "Parked"
-3. Add a `## Parked` section with: reason for parking, expected trigger to un-park, date parked
+1. **If the park reason is `upstream-blocked`**, run the external-root-cause detection block at Step 7 first (see "External-root-cause detection (P063)"). Park without recording the upstream dependency in `## Related` would be the canonical audit-trail gap this block closes.
+2. `git mv docs/problems/<NNN>-<title>.<current>.md docs/problems/<NNN>-<title>.parked.md`
+3. Update the Status field to "Parked"
+4. 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.
 
@@ -279,6 +280,45 @@ Pre-flight checks before allowing transition:
 
 If any check fails, report which checks failed and ask the user to address them before transitioning.
 
+#### External-root-cause detection (P063)
+
+Before renaming the file, scan the ticket's Root Cause Analysis section for external-root-cause markers. The same detection fires when parking a ticket with the `upstream-blocked` reason (see the Parked lifecycle entry at the top of this skill — it routes back to this block).
+
+**Strict detection tokens** (any of the following within the Root Cause Analysis section counts as a hit):
+
+- Literal label words: `upstream`, `third-party`, `external`, `vendor`.
+- Scoped npm package pattern: `@[\w-]+/[\w-]+` (e.g. `@anthropic/claude-code`, `@windyroad/itil`).
+
+Bash heuristic:
+
+```bash
+if grep -iE '\b(upstream|third-party|external|vendor)\b|@[[:alnum:]_-]+/[[:alnum:]_-]+' "$problem_file"; then
+  external_root_cause_detected=1
+fi
+```
+
+Detection is intentionally **strict** (explicit label or scoped-npm package only) to avoid prompt fatigue (P063 Direction decision). A passing reference to a bare package name (`gh`, `npm`) does NOT trigger the prompt.
+
+**Already-noted check** — before firing the prompt, grep the ticket for the stable marker `- **Upstream report pending** —` (written by option 2 / the AFK fallback below) or `- **Reported Upstream:**` / a `## Reported Upstream` section (written by `/wr-itil:report-upstream` Step 7 back-write per ADR-024 Confirmation criterion 3a). If any of those are already present, skip the prompt — the detection has already fired on a prior run.
+
+**If the detection fires and nothing has been noted yet**, use `AskUserQuestion`:
+
+- `header: "External root cause detected"`
+- `multiSelect: false`
+- Options:
+  1. `Invoke /wr-itil:report-upstream now` — halt the transition; the skill runs (it writes the `## Reported Upstream` appendage per ADR-024 Confirmation criterion 3a); the transition resumes afterwards.
+  2. `Defer and note in ticket` — append a pending-upstream-report line to the ticket's `## Related` section using the stable marker `- **Upstream report pending** — external dependency identified; invoke /wr-itil:report-upstream when ready`. The marker wording is fixed so subsequent runs (and the work-problems `upstream-blocked` skip path) can detect "already noted" without re-firing.
+  3. `Not actually upstream` — proceed without invocation; append the same marker with text `- **Upstream report pending** — false positive; detection misfire` so the prompt does not re-fire on later reviews.
+
+**Non-interactive (AFK) branch** (per ADR-013 Rule 6): when `AskUserQuestion` is unavailable, default to option 2 — append the pending-upstream-report line with the stable `- **Upstream report pending** —` marker. Do NOT auto-invoke `/wr-itil:report-upstream`; its Step 6 security-path branch is interactive and would halt the orchestrator anyway (per ADR-024 Consequences). The appended line lets the user see the deferred action when they return.
+
+**Scope**: this detection block fires at two points —
+
+- **Open → Known Error transition** (this step, primary insertion point).
+- **Parking path with `upstream-blocked` reason** — the parking workflow runs the same detection before `git mv` to `.parked.md`. Parking an upstream-blocked ticket without having noted (or reported) the upstream dependency is the canonical audit-trail gap this block closes.
+
+The work-problems orchestrator's `upstream-blocked` skip path (see `packages/itil/skills/work-problems/SKILL.md` classifier table) runs the AFK fallback before skipping, so ticket bodies accumulate the marker even when the orchestrator never invokes `manage-problem` on them.
+
 > **Staging trap (P057).** `git mv` stages only the rename — it does NOT pick up subsequent `Edit`-tool content changes. After the `Edit` tool modifies the renamed file (Status field, `## Fix Released` section, etc.), re-stage it explicitly: `git add <new>`. Without the explicit re-stage, the transition commit captures the rename-only change and the content edit leaks into the next commit, corrupting the audit trail. This rule applies to every `git mv` block below (Open → Known Error, Known Error → Verification Pending, Verification Pending → Closed) and to the supersession rename in `create-adr` Step 6.
 
 ```bash
@@ -319,6 +359,24 @@ git add 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`. Re-stage the `.closed.md` file explicitly after the Edit (P057 staging trap).
 
+#### README.md refresh on every transition (P062)
+
+Every Step 7 status transition (Open → Known Error, Known Error → Verification Pending, Verification Pending → Closed, Parked — regardless of source or destination suffix) regenerates `docs/problems/README.md` and stages it in the same commit so the dev-work table, Verification Queue, Parked section, and "Last reviewed" line never lag the on-disk ticket inventory. Without this step, README.md accumulates staleness between `review` invocations; the next `work` fast-path check correctly detects the lag and forces a full rescan (self-healing but wasteful), and any human browsing the file between transitions sees outdated rankings.
+
+The refresh uses the same rendering rules as Step 9e (glob `docs/problems/*.open.md` / `*.known-error.md` / `*.verifying.md` / `*.parked.md`; rank open/known-error by WSJF; list verifyings in the Verification Queue ordered by release age; list parkeds in the Parked section) but skips the full re-scoring pass — existing WSJF values on the ticket files are trusted. The refresh is a render, not a re-rank.
+
+**Mechanism:**
+
+1. After renaming + Editing + `git add`-ing the transitioned ticket file (per the staging-trap rule above), regenerate `docs/problems/README.md` in-place reflecting the new filename set and the transitioned ticket's new Status.
+2. `git add docs/problems/README.md` — stage the refreshed README with the same commit as the transition.
+3. Update the "Last reviewed" line's parenthetical to name the transition (e.g. `P<NNN> <status> — <one-line fix summary>`) so the next session's fast-path check has a human-readable audit marker alongside the git-history staleness test.
+
+**Scope**: fires for every Step 7 rename. Applies equally to:
+- Standalone transition commits (e.g. `docs(problems): P<NNN> known error — <summary>`).
+- **Folded-fix commits** where the `.verifying.md` transition rides with the fix implementation commit (e.g. `fix(<scope>): <description> (closes P<NNN>)` — per Step 11's convention for Known Error → Verification Pending). In both cases the refreshed README.md joins the same commit as the rename + content edit; never split across commits.
+
+**Fast-path interaction**: the Step 9 fast-path freshness check (`git log -1 --format=%H -- docs/problems/README.md` followed by `git log --oneline "${readme_commit}..HEAD" -- 'docs/problems/*.md'`) remains the authoritative staleness test. When this refresh fires on every transition, that check should return empty on any subsequent invocation — the cache stays fresh by construction. If the check still reports "stale", something skipped the refresh (bug) and the slow-path is the correct recovery.
+
 ### 8. For list: Show summary
 
 Read all `.open.md` and `.known-error.md` files in `docs/problems/`. Extract ID, title, priority, and status. Sort by priority (highest first). Display as a markdown table.
@@ -480,7 +538,7 @@ After any operation, report:
 - Any quality check warnings
 
 Commit the completed work per ADR-014 (governance skills commit their own work):
-1. `git add` all created/modified files for this operation — **including any file renamed via `git mv` that was then modified by the `Edit` tool** (P057 staging trap — `git mv` alone stages only the rename, not the subsequent content edit). `git add -u` is a safe catch-all for tracked modifications.
+1. `git add` all created/modified files for this operation — **including any file renamed via `git mv` that was then modified by the `Edit` tool** (P057 staging trap — `git mv` alone stages only the rename, not the subsequent content edit). `git add -u` is a safe catch-all for tracked modifications. **For any Step 7 status transition** (Open → Known Error, Known Error → Verification Pending, Verification Pending → Closed, or Parked) — including folded-fix commits where the `.verifying.md` transition rides with a `fix(<scope>): ...` commit — the stage list MUST include `docs/problems/README.md` refreshed per Step 7's "README.md refresh on every transition" block (P062). Skipping the refresh leaks staleness to the next session's fast-path.
 2. Satisfy the commit gate — two paths are valid (either produces a bypass marker):
    - **Primary**: delegate to the `wr-risk-scorer:pipeline` subagent-type via the Agent tool (subagent_type: `wr-risk-scorer:pipeline`)
    - **Fallback**: if the `wr-risk-scorer:pipeline` subagent-type is not available in the current tool set (e.g., this skill is itself running inside a spawned subagent), invoke the `/wr-risk-scorer:assess-release` skill via the Skill tool. Per ADR-015 it wraps the same pipeline subagent and the `PostToolUse:Agent` hook writes an equivalent bypass marker. Do not silently skip the gate because the primary path is unavailable — the fallback exists specifically to close this gap (see P035).

package/skills/manage-problem/test/manage-problem-external-root-cause-detection.bats

@@ -0,0 +1,98 @@
+#!/usr/bin/env bats
+
+# P063: manage-problem SKILL.md documents the external-root-cause
+# detection block that triggers /wr-itil:report-upstream (ADR-024)
+# when root cause is external.
+#
+# Doc-lint structural test (Permitted Exception per ADR-005) — asserts
+# SKILL.md wording for detection tokens, AskUserQuestion three-option
+# prompt, AFK fallback, and the stable `- **Upstream report pending** —`
+# marker. Mirrors work-problems-release-cadence.bats and
+# report-upstream-contract.bats patterns.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  MP_SKILL="$REPO_ROOT/packages/itil/skills/manage-problem/SKILL.md"
+  WP_SKILL="$REPO_ROOT/packages/itil/skills/work-problems/SKILL.md"
+}
+
+@test "manage-problem: SKILL.md contains the External-root-cause detection block (P063)" {
+  run grep -F 'External-root-cause detection (P063)' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md documents strict detection tokens (upstream, third-party, external, vendor)" {
+  run grep -F '`upstream`, `third-party`, `external`, `vendor`' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md documents the scoped-npm detection pattern" {
+  run grep -F '@[\w-]+/[\w-]+' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md documents the three AskUserQuestion options (invoke / defer / false positive)" {
+  run grep -F 'Invoke /wr-itil:report-upstream now' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+  run grep -F 'Defer and note in ticket' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+  run grep -F 'Not actually upstream' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md defines the stable Upstream report pending marker with fixed wording" {
+  run grep -F -- '- **Upstream report pending** — external dependency identified; invoke /wr-itil:report-upstream when ready' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md documents the AFK non-interactive fallback (option 2, append marker, no auto-invoke)" {
+  run grep -iE 'non-interactive.*afk|afk.*fallback' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+  # Explicit ban on auto-invoke
+  run grep -F 'Do NOT auto-invoke' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md documents the already-noted check to avoid duplicate prompts" {
+  run grep -F 'Already-noted check' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md documents both insertion points (Open → Known Error AND upstream-blocked park)" {
+  run grep -F 'Open → Known Error transition' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+  run grep -F 'Parking path with `upstream-blocked` reason' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: Parked lifecycle entry cross-references the external-root-cause detection block" {
+  run grep -F 'If the park reason is `upstream-blocked`' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: SKILL.md references ADR-024 and ADR-013 Rule 6 in the detection block" {
+  run grep -F 'ADR-024 Confirmation criterion 3a' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+  run grep -F 'ADR-013 Rule 6' "$MP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "work-problems: upstream-blocked skip row runs the AFK fallback before skipping" {
+  run grep -F 'append the pending-upstream-report marker' "$WP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "work-problems: upstream-blocked taxonomy entry documents the AFK fallback" {
+  run grep -F 'Before skipping, run the manage-problem external-root-cause detection AFK fallback' "$WP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "work-problems: Non-Interactive Decision Making table has the external-root-cause row (P063)" {
+  run grep -F 'External root cause detected at Open → Known Error' "$WP_SKILL"
+  [ "$status" -eq 0 ]
+}
+
+@test "work-problems: uses the same stable marker wording as manage-problem" {
+  run grep -F -- '- **Upstream report pending** — external dependency identified; invoke /wr-itil:report-upstream when ready' "$WP_SKILL"
+  [ "$status" -eq 0 ]
+}

package/skills/manage-problem/test/manage-problem-readme-refresh-on-transition.bats

@@ -0,0 +1,62 @@
+#!/usr/bin/env bats
+
+# P062: manage-problem SKILL.md documents that every Step 7 status
+# transition refreshes docs/problems/README.md and stages it in the
+# same commit — including folded-fix commits that ride with `fix(...)`.
+#
+# Doc-lint structural test (Permitted Exception per ADR-005). Asserts
+# SKILL.md wording for the refresh block, the four transition scopes,
+# the folded-fix-commit case, the fast-path interaction, and the
+# Step 11 commit convention's stage-list requirement.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_MD="$REPO_ROOT/packages/itil/skills/manage-problem/SKILL.md"
+}
+
+@test "manage-problem: SKILL.md contains the README.md refresh block (P062)" {
+  run grep -F 'README.md refresh on every transition (P062)' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: the refresh block lists all four transition scopes" {
+  run grep -F 'Open → Known Error, Known Error → Verification Pending, Verification Pending → Closed, Parked' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: the refresh block covers folded-fix commits explicitly" {
+  run grep -F '**Folded-fix commits**' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: the refresh block says refresh is a render not a re-rank" {
+  run grep -F 'The refresh is a render, not a re-rank' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: the refresh block stages README.md in the same commit" {
+  run grep -F 'git add docs/problems/README.md' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: Step 11 commit convention requires README.md in the stage list on transitions (P062)" {
+  run grep -F 'stage list MUST include `docs/problems/README.md`' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: Step 11 references Step 7's refresh block from the stage-list requirement" {
+  run grep -F "Step 7's \"README.md refresh on every transition\" block (P062)" "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: refresh block describes the fast-path interaction" {
+  run grep -F 'Fast-path interaction' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+  run grep -F 'cache stays fresh by construction' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}
+
+@test "manage-problem: refresh block describes Last reviewed line update" {
+  run grep -F 'Update the "Last reviewed" line' "$SKILL_MD"
+  [ "$status" -eq 0 ]
+}

package/skills/work-problems/SKILL.md

@@ -100,7 +100,7 @@ Read the problem file and apply these deterministic rules:
 | Problem previously attempted twice without progress in this session | **Skip** — mark as stuck, needs interactive attention | user-answerable (direction) |
 | Open problem with outstanding user-answerable design question (naming, direction, pacing, scope) | **Skip** — surface the question at stop (Step 2.5) | user-answerable (design) |
 | Open problem needing architect design judgment (new-ADR-level question) | **Skip** — note the architect-design blocker; Step 2.5 may elevate via a pre-triggered architect call in `--deep-stop` mode | architect-design |
-| Open problem blocked on upstream dependency or Claude Code capability gap | **Skip** — record the upstream-blocked reason | upstream-blocked |
+| Open problem blocked on upstream dependency or Claude Code capability gap | **Skip** — but first append the pending-upstream-report marker to the ticket's `## Related` section (see P063 — run the manage-problem SKILL.md external-root-cause detection AFK fallback before skipping). The marker wording is fixed: `- **Upstream report pending** — external dependency identified; invoke /wr-itil:report-upstream when ready`. Use the already-noted check to avoid duplicates. | upstream-blocked |
 
 The default is to work the problem. Only skip when the rule explicitly says so. This is an AFK loop — forward progress matters more than avoiding dead ends, because dead ends are cheap (findings are saved) and interactive input is expensive (user is absent).
 
@@ -108,7 +108,7 @@ The default is to work the problem. Only skip when the rule explicitly says so.
 
 - **user-answerable** — the user can answer directly (verification, naming, direction, pacing, scope). Step 2.5 surfaces these as questions (interactive) or in the Outstanding Design Questions table (non-interactive / AFK).
 - **architect-design** — requires architect judgment first; may escalate to a new ADR. Step 2.5 can optionally pre-trigger the architect agent in `--deep-stop` mode to produce a concrete user-answerable question. Otherwise noted as "pending architect review".
-- **upstream-blocked** — external dependency, Claude Code capability gap, or waiting on third-party fix. Truly terminal for this loop — no user question would change anything. Report the blocker and move on.
+- **upstream-blocked** — external dependency, Claude Code capability gap, or waiting on third-party fix. Truly terminal for this loop — no user question would change anything. Report the blocker and move on. **Before skipping, run the manage-problem external-root-cause detection AFK fallback** (per P063): grep the ticket for the stable marker `- **Upstream report pending** —` or `- **Reported Upstream:**` / a `## Reported Upstream` section; if none is present, append `- **Upstream report pending** — external dependency identified; invoke /wr-itil:report-upstream when ready` to the ticket's `## Related` section. This preserves the outbound audit trail across AFK iterations so the user can see the deferred action on return.
 
 Record the category alongside the skip reason in the iteration report so Step 2.5 can read the categories deterministically.
 
@@ -208,6 +208,7 @@ When `AskUserQuestion` is unavailable or the user is AFK, the skill (and the del
 | Fix verification needed | Skip problem, add to "needs verification" list |
 | Stop-condition #2 with user-answerable skip-reasons | Emit Outstanding Design Questions table in summary (do NOT call AskUserQuestion). The persona is AFK by definition — per JTBD-006 and ADR-013 Rule 6 — so the table is the default. Interactive invocations may batch up to 4 questions through AskUserQuestion instead — per ADR-013 Rule 1 (Step 2.5). |
 | Unexpected dirty state between iterations | Halt the loop. Report the `git status --porcelain` output, the last iteration's reported outcome, and the divergence — per P036 (Step 6.75). Do NOT attempt non-interactive recovery. |
+| External root cause detected at Open → Known Error, or at park with `upstream-blocked` reason | Append the stable `- **Upstream report pending** — external dependency identified; invoke /wr-itil:report-upstream when ready` marker to the ticket's `## Related` section; do NOT auto-invoke `/wr-itil:report-upstream` (Step 6 security-path branch is interactive — per ADR-024 Consequences). Use the already-noted grep check to avoid duplicate lines. Per P063 + ADR-013 Rule 6. |
 
 ## Edge Cases