@windyroad/itil 2.1.8 → 2.2.0-preview.1182

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "2.1.8"
+  "version": "2.2.0"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wr-itil",
-  "version": "2.1.8",
+  "version": "2.2.0",
   "description": "ITIL problem-management workflows for AI coding agents",
   "author": {
     "name": "Windy Road Technology",

package/hooks/pre-publish-intake-gate.sh

@@ -23,9 +23,17 @@
 #
 # This hook composes with risk-scorer's git-push-gate.sh: both fire on
 # Bash with `gh pr merge` matchers, and either may deny independently.
-# In practice git-push-gate denies all `gh pr merge` and routes to
-# `npm run release:watch` which subsequently runs `npm publish` — at
-# which point this hook fires.
+# In practice git-push-gate denies `gh pr merge` of the changeset release
+# PR and routes to `npm run release:watch`, which subsequently runs
+# `npm publish` — at which point this hook fires. An ordinary
+# feature-branch merge is denied by neither gate.
+#
+# The two hooks identify the release PR differently: this one greps the
+# command text for `changeset-release/`, while git-push-gate resolves the
+# PR's head branch through `gh pr view`. So a `gh pr merge <number>` or a
+# bare `gh pr merge` against the release PR is caught there and not here,
+# because the command text names no branch. No gap opens today — the
+# push gate denies first — but the divergence is worth knowing.
 
 set -euo pipefail
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "2.1.8",
+  "version": "2.2.0-preview.1182",
   "description": "ITIL-aligned IT service management for Claude Code and Codex",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/scripts/classify-readme-drift.sh

@@ -12,7 +12,7 @@
 #
 # <drift-stdout-file>: path to a file containing the captured stdout of
 # `reconcile-readme.sh` (one structured drift line per row — `DRIFT`,
-# `MISSING`, `STALE`, or `MISMATCH`).
+# `MISSING`, `STALE`, `MISMATCH`, or `CLASH`).
 #
 # <problems-dir>: defaults to ./docs/problems. Used by `git status
 # --porcelain` to scope the staged-rename probe.
@@ -27,6 +27,14 @@
 #                                            committed cross-session drift OR
 #                                            mixed; route to
 #                                            /wr-itil:reconcile-readme.
+#   HALT_ROUTE_RECONCILE clash=<N>        — <N> IDs are each claimed by more
+#                                            than one ticket file. Never
+#                                            deferrable: no working-tree
+#                                            rename can repair a clash, and
+#                                            the drift rows it causes describe
+#                                            the wrong file. Route to
+#                                            /wr-itil:reconcile-readme, whose
+#                                            --fix-clashes repairs it (duplicate-ticket-ids-are-silently-swallowed-by-the-readme-reconciler-problem).
 #
 # Exit codes:
 #   0 = INLINE_REFRESH
@@ -68,6 +76,19 @@ fi
 #   MISSING  P<NNN> verification-queue: ...
 #   STALE    P<NNN> verification-queue: ...
 #   MISMATCH P<NNN> closed: ...
+#   CLASH    P<NNN> <state>/<basename>  <state>/<basename>
+#
+# A CLASH short-circuits ahead of the rename-coverage probe below. It is a
+# structural defect — two tickets holding one number — and no rename in the
+# working tree can cover it. Left to the probe, a clashing ID that happened
+# to be a rename destination would classify as INLINE_REFRESH and the clash
+# would vanish exactly as it does today (duplicate-ticket-ids-are-silently-swallowed-by-the-readme-reconciler-problem).
+CLASH_COUNT="$(grep -cE '^CLASH' "$DRIFT_FILE" 2>/dev/null || true)"
+if [ "${CLASH_COUNT:-0}" -gt 0 ]; then
+  echo "HALT_ROUTE_RECONCILE clash=${CLASH_COUNT}"
+  exit 1
+fi
+
 DRIFT_IDS="$(grep -oE 'P[0-9]{3}' "$DRIFT_FILE" 2>/dev/null | sort -u)"
 
 if [ -z "$DRIFT_IDS" ]; then

package/scripts/reconcile-readme.sh

@@ -18,24 +18,72 @@
 # the per-state subdir wins — problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule §"Authoritative state signal"
 # treats subdirectory as the post-migration ground truth.
 #
+# Usage with the repair flag:
+#   reconcile-readme.sh --fix-clashes [<problems-dir>]
+#
 # Exit codes:
 #   0 = clean (README matches filesystem)
 #   1 = drift detected (structured diff to stdout)
 #   2 = parse error (README missing or malformed)
 #
+# With --fix-clashes, detection re-runs after the renumber and the exit
+# code reports what survives: 0 when the clash was the only drift, 1 when
+# ordinary drift remains. So a caller branching on 1 learns what is
+# actually left rather than reading a stale 1.
+#
 # Output format on drift (one line per drift entry, ≤ 150 bytes per
 # progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule progressive-disclosure budget):
 #   DRIFT    <ID> wsjf-rankings: claims=<status> actual=<status>
 #   MISSING  <ID> wsjf-rankings: actual=<status> file=<basename>
 #   STALE    <ID> verification-queue: actual=<status>
 #   MISMATCH <ID> closed: actual=<status>
+#   CLASH    <ID> <state>/<basename>  <state>/<basename>
+#
+# Read-only by default — does NOT mutate the README. The
+# /wr-itil:reconcile-readme skill applies README edits with
+# narrative-aware preservation; this script's job is to report ground
+# truth.
+#
+# --fix-clashes is the one exception: it moves the later-claiming ticket
+# file to a free ID and rewrites references to it. It never touches the
+# README, so the narrative-preservation contract above is intact.
 #
-# Read-only — does NOT mutate the README. The /wr-itil:reconcile-readme
-# skill applies edits with narrative-aware preservation; this script's
-# only job is to report ground truth.
+# ── Reference-rewrite boundary (--fix-clashes) ──────────────────────────────
+#
+# Rewritten: docs/problems/**/*.md and docs/stories/**/*.md. Scoped to
+# *.md so ID-keyed machine state (.outbound-responses-cache.json,
+# .upstream-cache.json) is never touched.
+#
+# Reported, never rewritten — every other file under docs/ naming the ID,
+# for three distinct reasons:
+#
+#   docs/decisions/**    A ratified decision body changes only by
+#                        supersession (ratified-decisions-change-only-by-supersession-architecture-rule).
+#   docs/story-maps/**   The grid is generated from its JSON island; a
+#                        text rewrite desynchronises the render and the
+#                        oversight fingerprint (story-maps-render-from-json-through-a-canonical-template-architecture-rule, a-story-map-card-stores-no-value-a-story-file-already-carries-architecture-rule,
+#                        the-grid-ships-in-the-file-a-map-is-readable-with-no-script-engine-architecture-rule). Edit via story-map-edit and re-render.
+#   docs/jtbd/**         Jobs and personas carry a ratification marker
+#                        whose integrity depends on edits being
+#                        human-confirmed (jtbd-persona-human-oversight-marker-wr-jtbd-confirm-jobs-and-personas-drain-sibling-of-architecture-rule, a-ratification-marker-can-only-be-written-when-someone-actually-ratified-architecture-rule). NOT excluded
+#                        as historical — this is a live surface.
+#   docs/retros/**       Each entry records what was true when written,
+#   docs/incidents/**    so re-pointing its identifiers rewrites history
+#   docs/audits/**       rather than repairing it.
+#   docs/briefing/**
+#   docs/risks/**        Live surfaces, neither historical nor
+#   docs/plans/**        ratification-bearing. Out of scope for this
+#   docs/rfcs/**         change; widening the rewrite set to them is a
+#                        separate decision.
 #
 # @problem docs-problems-readme-md-drifts-from-filesystem-truth-across-sessions-despite-refresh-on-create-and-refresh-on-transition-both-closed-problem
 # @problem problem-tickets-strain-as-fixes-decompose-into-multiple-coordinated-changes-need-an-rfc-framework-that-ties-all-changes-back-to-problems-and-unifies-technical-with-user-business-problems-problem (docs-problems-flat-layout-migration-per-state-subdirs-adopter-auto-migration-release-design — dual-tolerant migration window)
+# @problem duplicate-ticket-ids-are-silently-swallowed-by-the-readme-reconciler-problem (duplicate ticket IDs silently swallowed by the ID-keyed map)
+# @story see-the-id-clash-instead-of-the-drift-it-causes-delivery-story (See the ID clash instead of the drift it causes)
+# @adr afk-orchestrator-preflight-get-the-repo-into-a-clean-state-before-starting-architecture-rule (next-ID allocation is max(local, origin) + 1)
+# @adr ratified-decisions-change-only-by-supersession-architecture-rule (ratified decisions change only by supersession)
+# @adr story-maps-render-from-json-through-a-canonical-template-architecture-rule / a-story-map-card-stores-no-value-a-story-file-already-carries-architecture-rule / the-grid-ships-in-the-file-a-map-is-readable-with-no-script-engine-architecture-rule (story maps render from their island)
+# @adr jtbd-persona-human-oversight-marker-wr-jtbd-confirm-jobs-and-personas-drain-sibling-of-architecture-rule / a-ratification-marker-can-only-be-written-when-someone-actually-ratified-architecture-rule (jobs and personas carry a ratification marker)
 # @problem reconcile-readme-false-positive-parses-inbound-upstream-reports-matched-local-ticket-column-as-verification-queue-problem (Inbound Upstream Reports rows mis-attributed to VQ)
 # @adr governance-skills-commit-their-own-completed-work-architecture-rule (Reconciliation as preflight robustness layer)
 # @adr problem-lifecycle-add-a-verification-pending-status-between-known-error-and-closed-architecture-rule (Verification Pending lifecycle excludes from WSJF Rankings)
@@ -49,8 +97,23 @@
 
 set -uo pipefail
 
+FIX_CLASHES=0
+if [ "${1:-}" = "--fix-clashes" ]; then
+  FIX_CLASHES=1
+  shift
+fi
+
 PROBLEMS_DIR="${1:-docs/problems}"
 README="${PROBLEMS_DIR}/README.md"
+# The docs root, for the --fix-clashes report scan. Only trusted when the
+# tickets really do live in `<docs>/problems`; otherwise the parent is
+# some unrelated directory (a test fixture, a temp dir) and scanning it
+# would sweep the whole filesystem around it.
+if [ "$(basename "$PROBLEMS_DIR")" = "problems" ]; then
+  DOCS_DIR="$(dirname "$PROBLEMS_DIR")"
+else
+  DOCS_DIR="$PROBLEMS_DIR"
+fi
 
 # ── Pre-checks ──────────────────────────────────────────────────────────────
 
@@ -71,6 +134,15 @@ fi
 # migration race; per-state is the migration target per problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule).
 
 declare -A FS_STATUS
+# Every file that claimed each ID, newline-joined, kept per layout half.
+# FS_STATUS is keyed by ID and so is last-writer-wins: correct for the
+# cross-layout migration race it was built for, wrong for two genuinely
+# distinct tickets — the second disappears and the drift check then
+# blames whichever survived (duplicate-ticket-ids-are-silently-swallowed-by-the-readme-reconciler-problem). Keeping the halves apart lets a
+# flat+subdir pair stay the migration transient it is while two files in
+# the SAME half are reported as the clash they are.
+declare -A FLAT_FILES
+declare -A SUB_FILES
 shopt -s nullglob
 # Flat layout: docs/problems/<NNN>-<title>.<state>.md
 # Status classified from filename suffix.
@@ -94,6 +166,7 @@ for f in "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.open.md \
     *)                 continue ;;
   esac
   FS_STATUS["$id"]="$ticket_status"
+  FLAT_FILES["$id"]+="$f"$'\n'
 done
 # Per-state subdir layout: docs/problems/<state>/<NNN>-<title>.md
 # Status derived from parent directory name (the subdirectory IS the
@@ -105,10 +178,19 @@ for ticket_status in open known-error verifying closed parked; do
     num="${base%%-*}"
     id="P${num}"
     FS_STATUS["$id"]="$ticket_status"
+    SUB_FILES["$id"]+="$f"$'\n'
   done
 done
 shopt -u nullglob
 
+# Per-state wins on cross-layout collision, so an ID present in both
+# halves is the problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule migration transient and not a clash. Collapse to
+# the winning half; a clash is then simply more than one file left.
+declare -A FS_FILES
+for id in "${!FLAT_FILES[@]}" "${!SUB_FILES[@]}"; do
+  FS_FILES["$id"]="${SUB_FILES[$id]:-${FLAT_FILES[$id]}}"
+done
+
 # ── Parse README sections into ID buckets ───────────────────────────────────
 # We use the section-header line numbers to slice the file into ranges.
 
@@ -234,6 +316,124 @@ for id in "${!FS_STATUS[@]}"; do
   esac
 done
 
+# (5) An ID claimed by more than one file is a clash, not drift. It is
+#     reported ahead of everything else because the drift rows it causes
+#     describe the wrong file (duplicate-ticket-ids-are-silently-swallowed-by-the-readme-reconciler-problem).
+
+# `<state>/<basename>`, basename truncated to 40 chars, so the row stays
+# inside the per-row budget with this repo's long ticket filenames.
+clash_label() {
+  local path="$1" base parent
+  base="$(basename "$path")"
+  parent="$(basename "$(dirname "$path")")"
+  [ ${#base} -gt 40 ] && base="${base:0:40}..."
+  printf '%s/%s' "$parent" "$base"
+}
+
+CLASH_IDS=()
+for id in "${!FS_FILES[@]}"; do
+  mapfile -t claimants < <(printf '%s' "${FS_FILES[$id]}" | grep -v '^$')
+  [ "${#claimants[@]}" -gt 1 ] || continue
+  CLASH_IDS+=("$id")
+  DRIFT_LINES+=("CLASH    ${id} $(clash_label "${claimants[0]}")  $(clash_label "${claimants[1]}")")
+done
+
+# ── Repair (--fix-clashes only) ─────────────────────────────────────────────
+
+if [ "$FIX_CLASHES" = "1" ] && [ "${#CLASH_IDS[@]}" -gt 0 ]; then
+  # afk-orchestrator-preflight-get-the-repo-into-a-clean-state-before-starting-architecture-rule allocates against origin as well as the working tree, so a
+  # renumber cannot land on an ID created on the remote and recreate the
+  # clash it is repairing. The base ref is resolved rather than assumed:
+  # an adopter's default branch may not be `main`, and assuming it is the
+  # same class of defect as the gates hardcoded to the home-repo shape.
+  BASE_REF="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null)" || BASE_REF=""
+  BASE_REF="${BASE_REF#origin/}"
+  [ -n "$BASE_REF" ] || BASE_REF="main"
+
+  local_max=$(ls "$PROBLEMS_DIR"/*.md "$PROBLEMS_DIR"/*/*.md 2>/dev/null \
+    | sed 's|.*/||' | grep -oE '^[0-9]+' | sort -n | tail -1)
+  origin_max=$(git ls-tree -r --name-only "origin/${BASE_REF}" "$PROBLEMS_DIR/" 2>/dev/null \
+    | sed 's|.*/||' | grep -oE '^[0-9]+' | sort -n | tail -1)
+  if [ -z "$origin_max" ]; then
+    echo "NOTE     no origin/${BASE_REF} — allocating from the working tree only, ordering by mtime"
+  fi
+  next=$(( 10#$(printf '%s\n%s\n' "${local_max:-0}" "${origin_max:-0}" | sort -n | tail -1) ))
+
+  # First-add commit on the resolved base ref decides who claimed the
+  # number first. Outside a repository (or for a file never committed)
+  # this yields nothing and mtime stands in.
+  first_seen() {
+    local path="$1" t
+    t=$(git log --diff-filter=A --format=%at "$BASE_REF" -- "$path" 2>/dev/null | tail -1)
+    [ -n "$t" ] || t=$(git log --diff-filter=A --format=%at -- "$path" 2>/dev/null | tail -1)
+    # GNU stat first: on a Mac with coreutils installed, `-f` means
+    # "filesystem status" and happily prints a block-count dump instead
+    # of failing, which then gets treated as a timestamp.
+    [ -n "$t" ] || t=$(stat -c %Y "$path" 2>/dev/null)
+    [ -n "$t" ] || t=$(stat -f %m "$path" 2>/dev/null)
+    printf '%s' "${t:-0}"
+  }
+
+  for id in "${CLASH_IDS[@]}"; do
+    mapfile -t claimants < <(printf '%s' "${FS_FILES[$id]}" | grep -v '^$')
+    # Earliest claimant keeps the number; everyone after it is renumbered.
+    mapfile -t ordered < <(
+      for c in "${claimants[@]}"; do printf '%s\t%s\n' "$(first_seen "$c")" "$c"; done \
+        | sort -n -k1,1 | cut -f2-
+    )
+    for loser in "${ordered[@]:1}"; do
+      [ -f "$loser" ] || continue
+      next=$(( next + 1 ))
+      new_num=$(printf '%03d' "$next")
+      old_num="${id#P}"
+      new_id="P${new_num}"
+      dir="$(dirname "$loser")"
+      new_path="${dir}/${new_num}-$(basename "$loser" | cut -d- -f2-)"
+
+      if git ls-files --error-unmatch "$loser" >/dev/null 2>&1; then
+        git mv "$loser" "$new_path"
+      else
+        mv "$loser" "$new_path"
+      fi
+
+      # perl, not sed: BSD sed has no `\b`, and without a word boundary
+      # renumbering P23 would also rewrite phase-3b-readme-badge-renderer-wr-itil-plugin-maturity-render-advisory-drift-detector-check-plugin-maturity-drift-sh-problem.
+      rewrite_id_in() {
+        perl -pi -e "s/\\bP${old_num}\\b/${new_id}/g; s/\\b(Problem|problem) ${old_num}\\b/\$1 ${new_num}/g" "$1"
+      }
+
+      # The ticket's own references follow it — unambiguous, they are
+      # inside the file being renumbered.
+      rewrite_id_in "$new_path"
+
+      # A story the ticket names in its `## Stories` section, and which
+      # names the ticket back, is the one foreign reference that resolves
+      # without guessing: the two-way link says which of the two
+      # claimants it meant. Every other reference to the old ID is
+      # ambiguous by construction — both tickets carried it — so it is
+      # reported below rather than guessed at.
+      while IFS= read -r story_id; do
+        story_file=$(grep -rl "^# ${story_id}:" --include='*.md' "$DOCS_DIR/stories" 2>/dev/null | head -1)
+        [ -n "$story_file" ] || continue
+        grep -qE "\\bP${old_num}\\b" "$story_file" || continue
+        rewrite_id_in "$story_file"
+        echo "RETRACE  ${new_id} in ${story_file#"$DOCS_DIR"/}"
+      done < <(sed -n '/^## Stories/,/^## /p' "$new_path" | grep -oE '\bSTORY-[0-9]+\b' | sort -u)
+
+      echo "RENUMBER ${id} -> ${new_id} $(clash_label "$new_path")"
+
+      # Everything else under docs/ that names the old ID is reported,
+      # never rewritten — see the boundary in this file's docblock.
+      while IFS= read -r stranded; do
+        echo "MANUAL   ${id} still named in ${stranded#"$DOCS_DIR"/} — ambiguous, both claimants held it"
+      done < <(grep -rl -E "\\bP${old_num}\\b" "$DOCS_DIR" 2>/dev/null | sort)
+    done
+  done
+
+  # Re-run detection so the exit code reports what actually survives.
+  exec "$0" "$PROBLEMS_DIR"
+fi
+
 # ── Report ──────────────────────────────────────────────────────────────────
 
 if [ ${#DRIFT_LINES[@]} -eq 0 ]; then

package/skills/reconcile-readme/SKILL.md

@@ -51,9 +51,34 @@ Exit codes:
 - `1` — drift detected. The script prints one structured row per drift entry to stdout (each ≤ 150 bytes per the "Progressive disclosure + once-per-session budget for UserPromptSubmit governance prose" architecture rule progressive-disclosure budget). Continue to Step 2.
 - `2` — parse error. README is missing, malformed, or section headers are absent. Halt with the parse-error message; this is a deeper repair that needs investigation, not mechanical reconciliation. In AFK mode (the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 6), halt-with-report; do not attempt edits.
 
+### Step 1a. Repair any ID clash before reading the rest of the drift
+
+If the output carries one or more `CLASH` rows, two tickets are claiming one number. Nothing below can be trusted until that is repaired: the filesystem-truth map is keyed by ID, so one claimant was dropped and the `DRIFT` / `STALE` / `MISSING` rows alongside it describe the wrong file.
+
+This is mechanical — the framework has already decided who keeps the number (the earlier claimant, by first-add commit on the base ref) and what the other becomes (`max(local, origin) + 1`). Do NOT ask. Re-run with the repair flag:
+
+```bash
+wr-itil-reconcile-readme --fix-clashes docs/problems
+```
+
+The renumber moves the later claimant, rewrites its own references, and follows the two-way link to any story it names. It then re-runs detection, so its exit code and remaining rows describe what actually survives — continue from there.
+
+Two kinds of line come back alongside the drift:
+
+- `RENUMBER P<old> -> P<new> <path>` — what moved. Relay it; the number people have been using has changed.
+- `MANUAL P<old> still named in <path>` — a reference the repair would have had to guess at, since both claimants held that number. Surface every one of them for a person to resolve. Do NOT rewrite them, do NOT offer to rewrite them, and do NOT bulk search-and-replace the old ID anywhere. Say why, in plain words, for whichever trees the rows name:
+
+| Where the reference lives | Why it is left alone |
+|---|---|
+| `docs/decisions/` | A ratified decision changes only by supersession. Its body records what was decided; a script editing it in place is the one edit that rule forbids. |
+| `docs/story-maps/` | The grid is generated from the map's own data island and carries an oversight fingerprint. Rewriting the rendered HTML desynchronises the two and leaves the map reading as ratified against content nobody re-confirmed. Change it through `story-map-edit` and re-render. |
+| `docs/jtbd/` | Jobs and personas carry a ratification marker whose integrity depends on edits being human-confirmed. A script rewrite moves content underneath a marker nobody re-confirmed. |
+| `docs/retros/`, `docs/incidents/`, `docs/audits/`, `docs/briefing/` | Each entry records what was true when it was written. Re-pointing its identifiers rewrites history rather than repairing it. |
+| `docs/risks/`, `docs/plans/`, `docs/rfcs/` | Live surfaces, but out of scope for this repair. Widening it to them is a separate decision, not a call to make here. |
+
 ### Step 2. Bucket the drift entries by section
 
-Each drift line is one of four shapes:
+Each drift line is one of five shapes (`CLASH` is handled at Step 1a, before this bucketing):
 
 | Marker | Meaning | Required edit |
 |--------|---------|---------------|
@@ -143,7 +168,7 @@ The "Structured User Interaction for Governance-Skill Decisions" architecture ru
 ## Confirmation
 
 This skill's contract holds when:
-1. The script `packages/itil/scripts/reconcile-readme.sh` is read-only — no live README mutation in the script layer (mutation only in this skill's Step 4, via the Edit tool).
+1. The script `packages/itil/scripts/reconcile-readme.sh` never mutates the README — that happens only in this skill's Step 4, via the Edit tool. Its one write path is `--fix-clashes`, which moves a clashing ticket file and rewrites references to it, and touches no README.
 2. Each agent-applied edit preserves the README's narrative content (prose paragraph at top, Closed section free text).
 3. After Step 4 + Step 5, a re-run of the script reports exit 0 (clean).
 4. The reconciled README rides a single commit (Step 6 single-purpose commit) regardless of invocation mode — interactive and AFK behave identically per the "Governance Skills Commit Their Own Completed Work" architecture rule governance-skill commit contract (the "Skill contract "interactive vs AFK" commit-gating anti-pattern contradicts" problem).

package/skills-codex/reconcile-readme/SKILL.md

@@ -62,9 +62,34 @@ Exit codes:
 - `1` — drift detected. The script prints one structured row per drift entry to stdout (each ≤ 150 bytes per the "Progressive disclosure + once-per-session budget for UserPromptSubmit governance prose" architecture rule progressive-disclosure budget). Continue to Step 2.
 - `2` — parse error. README is missing, malformed, or section headers are absent. Halt with the parse-error message; this is a deeper repair that needs investigation, not mechanical reconciliation. In AFK mode (the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 6), halt-with-report; do not attempt edits.
 
+### Step 1a. Repair any ID clash before reading the rest of the drift
+
+If the output carries one or more `CLASH` rows, two tickets are claiming one number. Nothing below can be trusted until that is repaired: the filesystem-truth map is keyed by ID, so one claimant was dropped and the `DRIFT` / `STALE` / `MISSING` rows alongside it describe the wrong file.
+
+This is mechanical — the framework has already decided who keeps the number (the earlier claimant, by first-add commit on the base ref) and what the other becomes (`max(local, origin) + 1`). Do NOT ask. Re-run with the repair flag:
+
+```bash
+<itil-plugin-root>/bin/wr-itil-reconcile-readme --fix-clashes docs/problems
+```
+
+The renumber moves the later claimant, rewrites its own references, and follows the two-way link to any story it names. It then re-runs detection, so its exit code and remaining rows describe what actually survives — continue from there.
+
+Two kinds of line come back alongside the drift:
+
+- `RENUMBER P<old> -> P<new> <path>` — what moved. Relay it; the number people have been using has changed.
+- `MANUAL P<old> still named in <path>` — a reference the repair would have had to guess at, since both claimants held that number. Surface every one of them for a person to resolve. Do NOT rewrite them, do NOT offer to rewrite them, and do NOT bulk search-and-replace the old ID anywhere. Say why, in plain words, for whichever trees the rows name:
+
+| Where the reference lives | Why it is left alone |
+|---|---|
+| `docs/decisions/` | A ratified decision changes only by supersession. Its body records what was decided; a script editing it in place is the one edit that rule forbids. |
+| `docs/story-maps/` | The grid is generated from the map's own data island and carries an oversight fingerprint. Rewriting the rendered HTML desynchronises the two and leaves the map reading as ratified against content nobody re-confirmed. Change it through `story-map-edit` and re-render. |
+| `docs/jtbd/` | Jobs and personas carry a ratification marker whose integrity depends on edits being human-confirmed. A script rewrite moves content underneath a marker nobody re-confirmed. |
+| `docs/retros/`, `docs/incidents/`, `docs/audits/`, `docs/briefing/` | Each entry records what was true when it was written. Re-pointing its identifiers rewrites history rather than repairing it. |
+| `docs/risks/`, `docs/plans/`, `docs/rfcs/` | Live surfaces, but out of scope for this repair. Widening it to them is a separate decision, not a call to make here. |
+
 ### Step 2. Bucket the drift entries by section
 
-Each drift line is one of four shapes:
+Each drift line is one of five shapes (`CLASH` is handled at Step 1a, before this bucketing):
 
 | Marker | Meaning | Required edit |
 |--------|---------|---------------|
@@ -154,7 +179,7 @@ The "Structured User Interaction for Governance-Skill Decisions" architecture ru
 ## Confirmation
 
 This skill's contract holds when:
-1. The script `<itil-plugin-root>/scripts/reconcile-readme.sh` is read-only — no live README mutation in the script layer (mutation only in this skill's Step 4, via the Edit tool).
+1. The script `<itil-plugin-root>/scripts/reconcile-readme.sh` never mutates the README — that happens only in this skill's Step 4, via the Edit tool. Its one write path is `--fix-clashes`, which moves a clashing ticket file and rewrites references to it, and touches no README.
 2. Each agent-applied edit preserves the README's narrative content (prose paragraph at top, Closed section free text).
 3. After Step 4 + Step 5, a re-run of the script reports exit 0 (clean).
 4. The reconciled README rides a single commit (Step 6 single-purpose commit) regardless of invocation mode — interactive and AFK behave identically per the "Governance Skills Commit Their Own Completed Work" architecture rule governance-skill commit contract (the "Skill contract "interactive vs AFK" commit-gating anti-pattern contradicts" problem).