@windyroad/itil 0.4.1 → 0.4.2

package/.claude-plugin/plugin.json

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

package/package.json

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

package/skills/work-problems/SKILL.md

@@ -14,6 +14,28 @@ The user is AFK during this process, so every decision point that would normally
 
 Each iteration is one cycle of: scan backlog, pick highest-WSJF problem, work it, report result. The loop continues until a stop condition is met.
 
+### Step 0: Preflight (per ADR-019)
+
+Before opening the work loop, reconcile local state with origin so the orchestrator does not iterate against a stale backlog or create tickets with IDs that collide with parallel sessions (P040).
+
+**Mechanism:**
+
+1. Run `git fetch origin`.
+2. Compare local `HEAD` with `origin/<base>` (default `main`; otherwise the branch the user is on).
+3. Branch on the divergence shape:
+
+| Local vs origin | Action |
+|---|---|
+| HEAD at or ahead of origin/<base> | Proceed to Step 1 |
+| origin/<base> ahead, local has no unpushed commits (pure fast-forward) | Run `git pull --ff-only` non-interactively. Log the count of pulled commits in the AFK iteration log. Proceed to Step 1. |
+| origin/<base> ahead, local has unpushed commits (non-fast-forward) | STOP the loop. Report the divergence with `git log --oneline HEAD..origin/<base>` and `git log --oneline origin/<base>..HEAD`. Do NOT attempt to rebase or merge non-interactively — that is a judgment call the persona forbids in AFK mode. |
+
+**Network failure**: if `git fetch origin` returns a network error, stop and report. Default behaviour is fail-closed — the user can retry when network is restored.
+
+**Non-interactive authorisation**: per ADR-013 Rule 6, `git fetch origin` and `git pull --ff-only` are policy-authorised actions (no semantic merge, no destructive overwrite). `git pull --rebase`, `git merge`, and any operation that resolves conflicts are NOT policy-authorised — they require user input.
+
+**Cross-cutting**: this rule applies to every AFK orchestrator skill. The next-ID collision guard (ADR-019 confirmation criterion 2) belongs in the ticket-creator skills (`manage-problem` and `wr-architect:create-adr`), not here — see the related problem ticket for that work.
+
 ### Step 1: Scan the backlog
 
 Read `docs/problems/README.md` if it exists and is fresh (check via git history — see manage-problem step 9 for the cache freshness check). If stale or missing, scan all `.open.md` and `.known-error.md` files in `docs/problems/`, extract their WSJF scores, and rank them.
@@ -134,6 +156,7 @@ When `AskUserQuestion` is unavailable or the user is AFK, the skill (and the del
 | Commit when risk within appetite | Auto-commit (manage-problem step 9e fallback) |
 | Commit when risk above appetite | Skip commit, report uncommitted state |
 | Pipeline risk at appetite (push or release >= 4/25) | Drain release queue (`push:watch` then `release:watch`) before next iteration — per ADR-018 (Step 6.5) |
+| Origin diverged before start | Pull `--ff-only` if trivial; stop with report (`git log HEAD..origin/<base>` and reverse) if non-fast-forward — per ADR-019 (Step 0) |
 | Fix verification needed | Skip problem, add to "needs verification" list |
 
 ## Edge Cases

package/skills/work-problems/test/work-problems-preflight.bats

@@ -0,0 +1,69 @@
+#!/usr/bin/env bats
+# Doc-lint guard: work-problems SKILL.md must include the preflight
+# (fetch-origin + divergence handling) per ADR-019.
+#
+# Structural assertion — Permitted Exception to the source-grep ban (ADR-005 / P011).
+# These tests assert that the skill specification document contains the
+# preflight step so the AFK orchestrator does not iterate against a stale
+# local backlog when origin/<base> has advanced.
+#
+# Cross-reference:
+#   P040 (work-problems does not fetch origin before starting)
+#   ADR-019 (AFK orchestrator preflight)
+#   @jtbd JTBD-006 (Progress the Backlog While I'm Away)
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+@test "SKILL.md cites ADR-019 (preflight)" {
+  # ADR-019 confirmation criterion: skill must reference the ADR.
+  run grep -n "ADR-019" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md preflight runs git fetch origin" {
+  # ADR-019 mechanism: must run `git fetch origin` before opening the
+  # work loop.
+  run grep -n "git fetch origin" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md preflight uses git pull --ff-only on trivial divergence" {
+  # ADR-019 mechanism: trivial fast-forward is policy-authorised; non-ff is
+  # not. The skill must cite --ff-only to prevent merge attempts.
+  run grep -n "ff-only" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md preflight stops the loop on non-fast-forward divergence" {
+  # Confirmation: divergence handling must include a stop-with-report path,
+  # not a silent retry or merge.
+  run grep -niE "non-fast-forward|non-ff" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md preflight has a discrete step before backlog scan" {
+  # The preflight should appear as a discrete step (e.g. Step 0 — Preflight)
+  # so it is not buried in prose.
+  run grep -niE "step 0|preflight" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Non-Interactive Decision Making table covers origin divergence" {
+  # ADR-019 confirmation: the non-interactive defaults table must include a
+  # row for the divergence decision.
+  run grep -niE "Origin diverged|origin.*divergence|fast-forward" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md explicitly forbids non-interactive merge/rebase remediation" {
+  # ADR-019 forbids non-interactive rebase/merge attempts. The skill must
+  # negate these (e.g. "Do NOT attempt to rebase or merge" or "are NOT
+  # policy-authorised") rather than silently allow them. We assert the
+  # negation appears, not that the words are absent — discussing forbidden
+  # operations in the negative is exactly what the ADR requires.
+  run grep -niE "Do NOT attempt to rebase or merge|NOT policy-authorised" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}