@windyroad/itil 0.61.0 → 0.61.1-preview.1037

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.61.0"
+  "version": "0.61.1"
 }

package/lib/story-oversight.sh

@@ -19,15 +19,43 @@
 # encodings in one filter:
 #   - markdown: `human-oversight:` / `oversight-hash:` frontmatter lines
 #   - HTML:     <meta name="human-oversight" ...> / <meta name="oversight-hash" ...>
+# THE single definition of what the fingerprint ignores. Reads stdin, writes the
+# normalised stream. Both hash functions route through this and neither carries
+# its own copy — that duplication is why the P474 `**Status**:` mirror had to be
+# removed from two places and why a third copy could have been missed entirely
+# (RFC-059 / STORY-055).
+#
+# Excludes the marker lines plus the lifecycle `status` key in both encodings, and
+# normalises lifecycle PROGRESS — acceptance-criterion ticks and slice
+# `data-status` — so ONLY a SUBSTANCE change re-opens ratification. Ticking a
+# criterion or advancing status is progress, not a revision of what the human
+# ratified; the value statement, criterion TEXT and structure all still drift.
+#
+# Editing this filter changes ADR-090's Decision Outcome, not merely a mechanism.
+# It is the surface the 2026-07-03 narrowing changed while going unrecorded for
+# three weeks; a change here needs an ADR-090 amendment. The pattern is a
+# LITERAL on purpose: built from a variable, an expansion that ever yielded empty
+# would make `grep -vE ''` suppress every line and hash the empty stream to a
+# constant, after which one artefact's stored hash would validate against ANY
+# content — and `itil-no-implement-draft-gate` sources this lib under
+# `2>/dev/null || exit 0`, so that failure would remove the gate silently.
+_oversight_filter() {
+  grep -vE '^(human-oversight|oversight-hash|oversight-basis|status):|<meta[^>]*name="(human-oversight|oversight-hash|oversight-basis|status)"' \
+    | sed -E 's/- \[[ xX]\]/- [ ]/g; s/data-status="[^"]*"/data-status=""/g'
+}
+
+# The excluded key set, readable by tests and the corpus lint. Kept in agreement
+# with the literal above by a bidirectional test rather than by construction, for
+# the reason in that comment. One key per line.
+oversight_excluded_keys() {
+  printf '%s\n' human-oversight oversight-hash oversight-basis status
+}
+
 oversight_content_hash() {
-  # Exclude the marker + lifecycle-`status` lines, and normalize lifecycle-PROGRESS
-  # state — acceptance-criterion checkbox ticks and slice `data-status` — so that
-  # ONLY a SUBSTANCE change re-opens ratification. Ticking a criterion or advancing
-  # status/slice-progress is progress, not a change to what the user ratified; the
-  # value statement, criterion TEXT, and structure still drift the hash.
-  grep -vE '^(human-oversight|oversight-hash|oversight-basis|status):|<meta[^>]*name="(human-oversight|oversight-hash|oversight-basis|status)"' "$1" \
-    | sed -E 's/- \[[ xX]\]/- [ ]/g; s/data-status="[^"]*"/data-status=""/g' \
-    | shasum -a 256 | awk '{print $1}'
+  # Input path: the file is fed to the filter directly, so trailing blank lines
+  # are PRESERVED. Deliberately NOT unified with the map variant below — see the
+  # note there. Changing this changes every stored fingerprint.
+  _oversight_filter < "$1" | shasum -a 256 | awk '{print $1}'
 }
 
 # Hash a story MAP's content while EXCLUDING the single-line card elements whose
@@ -52,10 +80,16 @@ oversight_content_hash_excluding_stories() {
     # Anchored on the closing quote so STORY-05 cannot strip STORY-054's card.
     filtered="$(printf '%s\n' "$filtered" | grep -vF "data-story-id=\"${id}\"" || true)"
   done
-  printf '%s\n' "$filtered" \
-    | grep -vE '^(human-oversight|oversight-hash|oversight-basis|status):|<meta[^>]*name="(human-oversight|oversight-hash|oversight-basis|status)"' \
-    | sed -E 's/- \[[ xX]\]/- [ ]/g; s/data-status="[^"]*"/data-status=""/g' \
-    | shasum -a 256 | awk '{print $1}'
+  # Input path: `$(cat)` above stripped ALL trailing newlines and this `printf`
+  # re-adds exactly one, so trailing blank lines are COLLAPSED here where
+  # `oversight_content_hash` preserves them. That divergence is pre-existing and
+  # is preserved deliberately — unifying the two input paths would silently change
+  # one function's hash and un-ratify every stored fingerprint at once. A
+  # consequence worth knowing: with zero ids this does NOT equal
+  # `oversight_content_hash` for an artefact with trailing blank lines, which is
+  # recorded as its own P474 task because it makes ADR-101's map leg
+  # unsatisfiable for such a map even with the right card excluded.
+  printf '%s\n' "$filtered" | _oversight_filter | shasum -a 256 | awk '{print $1}'
 }
 
 # True (0) if this artefact's `confirmed` marker was written by the ADR-101 AFK

package/package.json

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

package/scripts/test/oversight-mirror-corpus-lint.bats

@@ -0,0 +1,143 @@
+#!/usr/bin/env bats
+# P474 / STORY-055 — corpus lint: no artefact may mirror an excluded key.
+#
+# This is a LINT, not a behavioural test, and the distinction is deliberate rather
+# than an ADR-052 exception. ADR-052's forbidden class is structural assertion on
+# document content *as a proxy for behaviour*; all its documented failure modes
+# are proxy failures. Here the content IS the deliverable — "no live artefact
+# carries a mirror" is a property of data, and data has no behaviour to assert.
+# So it homes under ADR-005's script/data-validation authority, which ADR-052
+# explicitly leaves intact.
+#
+# WHY it exists: P474's mirror audit was a one-time inspection, and a one-time
+# inspection has no cadence. The fingerprint excludes four frontmatter keys; if
+# any of them acquires a body mirror, accepting a story silently drops its own
+# ratification and the no-implement gate then denies its own implementing commit.
+# That already happened once with `status`.
+#
+# The behavioural half lives in the last test: it covers a mirror of ANY excluded
+# key in ANY shape, including an HTML meta mirror, which the lint's line-anchored
+# bold-key pattern structurally cannot reach.
+#
+# Two things this lint does NOT catch, recorded rather than implied:
+#   1. The story-map `href` leg (open P474 task) — a card links
+#      `../../stories/<state>/…`, so the lifecycle directory sits inside the map's
+#      hashed content while the card's `data-status` is normalised out. No
+#      bold-key pattern can see that.
+#   2. A mirror written with leading whitespace or inside a list item — the cost
+#      of line-anchoring, taken so no exclusion set is needed.
+#
+# @problem P474  @adr ADR-090 ADR-005 ADR-052  @story STORY-055
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  LIB="${REPO_ROOT}/packages/itil/lib/story-oversight.sh"
+  # shellcheck source=/dev/null
+  source "$LIB"
+  STORIES="$REPO_ROOT/docs/stories"
+  MAPS="$REPO_ROOT/docs/story-maps"
+  TMPD="$(mktemp -d)"
+}
+teardown() { rm -rf "$TMPD"; }
+
+# Build the pattern from the lib's own accessor, so a key added to the exclusion
+# set is covered without editing this file. Case-INSENSITIVE is load-bearing: the
+# accessor holds lowercase keys (`status`) while every real mirror is Title-Case
+# (`**Status**:`), so a case-sensitive pattern built from the accessor matches
+# nothing on arrival AND stays green when a mirror is reintroduced.
+mirror_pattern() {
+  local alt; alt="$(oversight_excluded_keys | paste -sd'|' -)"
+  printf '^\\*\\*(%s)\\*\\*[[:space:]]*:' "$alt"
+}
+
+# Line-anchored on purpose. Unanchored, this matches four lines of legitimate
+# prose *about* the defect (the stories README, two lines in STORY-054, and
+# STORY-055's own problem trace), which would redden on arrival and require an
+# exclusion list growing with every future story that discusses a mirror.
+scan() {
+  grep -rniE "$(mirror_pattern)" "$@" 2>/dev/null || true
+}
+
+@test "lint: the excluded-key accessor is non-empty and the pattern is well-formed" {
+  # Guard against a silently-empty pattern — the whole lint would go vacuous.
+  local keys; keys="$(oversight_excluded_keys)"
+  [ -n "$keys" ]
+  [ "$(printf '%s\n' "$keys" | wc -l | tr -d ' ')" -ge 4 ]
+  [[ "$(mirror_pattern)" == *'status'* ]]
+}
+
+@test "lint: search roots exist and hold artefacts — fails loudly, never vacuously" {
+  # A renamed or adopter-relative path must fail here rather than let the scan
+  # below pass by matching nothing. This is the shape that reddened main once.
+  [ -d "$STORIES" ]
+  [ -d "$MAPS" ]
+  local n
+  n="$(find "$STORIES" -name 'STORY-*.md' -type f 2>/dev/null | wc -l | tr -d ' ')"
+  [ "$n" -ge 1 ] || { echo "no STORY-*.md under $STORIES — lint would be vacuous"; false; }
+  n="$(find "$MAPS" -name '*.html' -type f 2>/dev/null | wc -l | tr -d ' ')"
+  [ "$n" -ge 1 ] || { echo "no maps under $MAPS — lint would be vacuous"; false; }
+}
+
+@test "lint: no story artefact mirrors an excluded frontmatter key in its body" {
+  local hits
+  hits="$(scan "$STORIES"/*/STORY-*.md)"
+  [ -z "$hits" ] || {
+    printf 'body mirror of an excluded key found — accepting these stories will drop their ratification:\n%s\n' "$hits"
+    printf 'remove the line; run `wr-itil-migrate-story-status-mirror docs/stories` for an existing corpus.\n'
+    false
+  }
+}
+
+@test "lint: no story map mirrors an excluded frontmatter key in its body" {
+  # The map's own `<meta name="status">` is the key's HOME in the HTML encoding,
+  # not a mirror of it, and the lib's filter already excludes it — so the
+  # line-anchored bold-key pattern correctly does not flag it.
+  local hits
+  hits="$(scan "$MAPS"/*/*.html)"
+  [ -z "$hits" ] || {
+    printf 'body mirror of an excluded key found in a map:\n%s\n' "$hits"
+    false
+  }
+}
+
+@test "lint: RED on an injected mirror — proves the pattern actually fires" {
+  mkdir -p "$TMPD/stories/draft"
+  printf -- '---\nstatus: accepted\n---\n\n# STORY-999: x\n\n**Status**: accepted\n**Reported**: 2026-07-30\n' \
+    > "$TMPD/stories/draft/STORY-999-x.md"
+  local hits; hits="$(scan "$TMPD/stories"/*/STORY-*.md)"
+  [ -n "$hits" ] || { echo "lint failed to detect an injected line-start **Status**: mirror"; false; }
+  [[ "$hits" == *"STORY-999"* ]]
+}
+
+@test "lint: prose ABOUT a mirror is not flagged — that is what line-anchoring buys" {
+  mkdir -p "$TMPD/prose/draft"
+  printf -- '---\nstatus: accepted\n---\n\n# STORY-998: y\n\nThe `**Status**:` line used to be hashed.\n<!-- No **Status**: body line, deliberately. -->\n' \
+    > "$TMPD/prose/draft/STORY-998-y.md"
+  [ -z "$(scan "$TMPD/prose"/*/STORY-*.md)" ]
+}
+
+# The behavioural half. Covers a mirror of ANY excluded key in ANY shape,
+# including the HTML meta form the lint's pattern cannot reach.
+@test "behavioural: a mirror of any excluded key drifts a ratified artefact" {
+  local k
+  for k in $(oversight_excluded_keys); do
+    # Skip the marker keys themselves — those are excluded BY the marker write,
+    # so a "mirror" of them is what the filter is for.
+    case "$k" in human-oversight|oversight-hash|oversight-basis) continue ;; esac
+    local f="$TMPD/mirror-$k.md"
+    printf -- '---\n%s: draft\nhuman-oversight: confirmed\noversight-hash: P\n---\n\n# STORY-997\n\nbody\n' "$k" > "$f"
+    local h; h="$(oversight_content_hash "$f")"
+    sed -i.bak "s/oversight-hash: P/oversight-hash: $h/" "$f" && rm -f "$f.bak"
+    run is_story_map_ratified "$f"
+    [ "$status" -eq 0 ]
+    # Add a body mirror of that key, then advance BOTH copies the way a
+    # transition would. The frontmatter change alone is excluded; the body
+    # mirror is not — so ratification must drop, which is P474 exactly.
+    printf -- '**%s**: accepted\n' "$k" >> "$f"
+    h="$(oversight_content_hash "$f")"
+    sed -i.bak "s/^oversight-hash: .*/oversight-hash: $h/" "$f" && rm -f "$f.bak"
+    sed -i.bak "s/^${k}: draft/${k}: accepted/; s/^\\*\\*${k}\\*\\*: accepted/**${k}**: DIFFERENT/" "$f" && rm -f "$f.bak"
+    run is_story_map_ratified "$f"
+    [ "$status" -ne 0 ] || { echo "a body mirror of '$k' did not drift the hash"; false; }
+  done
+}

package/scripts/test/story-oversight-lib.bats

@@ -86,3 +86,105 @@ teardown() { rm -rf "$TMPD"; }
   printf '<meta name="human-oversight" content="confirmed">\n<meta name="oversight-hash" content="%s">\n<h1>map</h1>\n' "$h" > "$TMPD/m.html"
   run is_story_map_ratified "$TMPD/m.html"; [ "$status" -eq 0 ]
 }
+
+# --- P474 / STORY-055: the extraction must not move a single hash --------------
+#
+# `oversight_content_hash` and `oversight_content_hash_excluding_stories` shared a
+# verbatim grep|sed filter, which is why the P474 mirror had to be removed twice
+# and why a third copy could have been missed. The filter is now extracted.
+#
+# The extraction boundary is the whole risk. The two functions' INPUT paths are
+# NOT equivalent and must stay that way: one passes the file to grep directly,
+# the other round-trips through $(cat) — which strips all trailing newlines —
+# then printf '%s\n' re-adds exactly one. So trailing blank lines are preserved
+# by the first and collapsed by the second. Extract the filter only; unify the
+# input paths "for symmetry" and the hash silently changes for any artefact with
+# anomalous trailing whitespace, un-ratifying every stored fingerprint at once.
+#
+# `_ref_*` below are VERBATIM copies of the pre-extraction implementation. They
+# exist to be compared against, so do NOT refactor them to call the new helper —
+# that would make the equivalence assertions circular and worthless.
+
+_ref_hash() {
+  grep -vE '^(human-oversight|oversight-hash|oversight-basis|status):|<meta[^>]*name="(human-oversight|oversight-hash|oversight-basis|status)"' "$1" \
+    | sed -E 's/- \[[ xX]\]/- [ ]/g; s/data-status="[^"]*"/data-status=""/g' \
+    | shasum -a 256 | awk '{print $1}'
+}
+
+_ref_hash_excluding() {
+  local f="$1"; shift
+  local filtered id
+  filtered="$(cat "$f")"
+  for id in "$@"; do
+    [ -n "$id" ] || continue
+    filtered="$(printf '%s\n' "$filtered" | grep -vF "data-story-id=\"${id}\"" || true)"
+  done
+  printf '%s\n' "$filtered" \
+    | grep -vE '^(human-oversight|oversight-hash|oversight-basis|status):|<meta[^>]*name="(human-oversight|oversight-hash|oversight-basis|status)"' \
+    | sed -E 's/- \[[ xX]\]/- [ ]/g; s/data-status="[^"]*"/data-status=""/g' \
+    | shasum -a 256 | awk '{print $1}'
+}
+
+@test "extraction: byte-identical to the frozen reference across edge shapes" {
+  # No final newline.
+  printf -- '---\nstatus: draft\n---\nbody' > "$TMPD/a"
+  # Multiple trailing blank lines — the shape the input-path divergence hinges on.
+  printf -- '---\nstatus: draft\n---\nbody\n\n\n\n' > "$TMPD/b"
+  # CRLF.
+  printf -- '---\r\nstatus: draft\r\n---\r\nbody\r\n' > "$TMPD/c"
+  # Empty file.
+  : > "$TMPD/d"
+  # A criterion tick and a data-status, both normalised.
+  printf -- '- [x] done\n<a data-status="done">x</a>\n' > "$TMPD/e"
+  # Every excluded key present, in both encodings.
+  printf -- 'human-oversight: confirmed\noversight-hash: deadbeef\noversight-basis: pure-decomposition\nstatus: accepted\n<meta name="status" content="draft">\nbody\n' > "$TMPD/f"
+  # Only a newline.
+  printf '\n' > "$TMPD/g"
+
+  for n in a b c d e f g; do
+    [ "$(oversight_content_hash "$TMPD/$n")" = "$(_ref_hash "$TMPD/$n")" ] || {
+      echo "oversight_content_hash diverged on fixture $n"; false
+    }
+  done
+}
+
+@test "extraction: map variant byte-identical, including the id-exclusion loop" {
+  printf -- '<meta name="status" content="draft">\n<a data-story-id="STORY-05">short</a>\n<a data-story-id="STORY-054">long</a>\n<a class="slice" data-status="done">s</a>\nbody\n\n\n' \
+    > "$TMPD/m.html"
+  # Zero ids, one id, and the prefix-collision pair — STORY-05 must not strip
+  # STORY-054's card, which is what the closing-quote anchor buys.
+  [ "$(oversight_content_hash_excluding_stories "$TMPD/m.html")" = "$(_ref_hash_excluding "$TMPD/m.html")" ]
+  [ "$(oversight_content_hash_excluding_stories "$TMPD/m.html" STORY-054)" = "$(_ref_hash_excluding "$TMPD/m.html" STORY-054)" ]
+  [ "$(oversight_content_hash_excluding_stories "$TMPD/m.html" STORY-05)" = "$(_ref_hash_excluding "$TMPD/m.html" STORY-05)" ]
+  [ "$(oversight_content_hash_excluding_stories "$TMPD/m.html" STORY-05 STORY-054)" = "$(_ref_hash_excluding "$TMPD/m.html" STORY-05 STORY-054)" ]
+  # And the divergence itself is preserved rather than accidentally unified.
+  [ "$(oversight_content_hash_excluding_stories "$TMPD/m.html")" != "$(oversight_content_hash "$TMPD/m.html")" ]
+}
+
+# Golden hashes are pinned over FIXTURES, never over live artefacts. Pinning to
+# the corpus would redden this suite on every later legitimate artefact edit —
+# ADR-052's refactor-blocking failure mode. Their job is to catch the frozen
+# reference itself rotting, which the equivalence cases above cannot.
+@test "extraction: pinned golden hashes over a canonical fixture" {
+  printf -- '---\nstatus: draft\nhuman-oversight: confirmed\n---\n\n# STORY-900: canonical\n\n**Reported**: 2026-07-30\n\n- [ ] a criterion\n' \
+    > "$TMPD/golden.md"
+  [ "$(oversight_content_hash "$TMPD/golden.md")" = "1a18f2501f7092b64316a1566795e64860f90893c2b4d0d36cd9a783ada21414" ]
+}
+
+@test "extraction: the excluded-key accessor agrees with the operative pattern both ways" {
+  local keys; keys="$(oversight_excluded_keys)"
+  [ -n "$keys" ]
+  # Every accessor key appears as an alternation branch in the operative filter.
+  for k in $keys; do
+    grep -qF -- "$k" "$LIB" || { echo "accessor key '$k' absent from the lib pattern"; false; }
+  done
+  # And every branch in the operative pattern appears in the accessor — the
+  # direction that catches a key ADDED to the regex but not to the accessor,
+  # which would leave the corpus lint blind to it.
+  local branch
+  for branch in $(grep -oE '\^\(([a-z-]+\|)+[a-z-]+\):' "$LIB" | head -1 | tr -d '^():' | tr '|' ' '); do
+    printf '%s\n' "$keys" | grep -qx -- "$branch" || {
+      echo "pattern branch '$branch' missing from oversight_excluded_keys()"; false
+    }
+  done
+}