@windyroad/itil 0.56.0-preview.879 → 0.56.0-preview.880

package/bin/wr-itil-mark-story-oversight-confirmed

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Generated by scripts/sync-shim-wrappers.sh from
+# packages/shared/lib/shim-wrapper-template.sh. DO NOT EDIT individual
+# shim files in packages/*/bin/wr-* directly; edit the template + run
+# `npm run sync:shim-wrappers` to regenerate.
+#
+# Resolution (ADR-080):
+#   1. If the wrapper's parent dir is semver-shaped, treat as installed-
+#      cache execution and resolve to the highest-version sibling's
+#      scripts/ entry below.
+#   2. Otherwise (parent dir is e.g. `architect`), treat as source-
+#      monorepo execution and dispatch to own scripts/. The source-repo-
+#      guard `exec` is the anchor parsed by
+#      packages/retrospective/scripts/check-tarball-shipped-shims.sh.
+#   3. If the cache parent contains zero semver-shaped siblings, exit
+#      127 with a stderr message naming the cache parent (per SQ-080-2).
+#
+# @adr ADR-080 (highest-version-wins shim wrapper plugin scaffold)
+# @adr ADR-049 (plugin-bundled scripts resolve via bin/ on $PATH — amended)
+# @problem P343 (mid-session staleness window)
+
+set -euo pipefail
+
+SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"
+OWN_VERSION_DIR="$(dirname "$SHIM_DIR")"
+OWN_VERSION_NAME="$(basename "$OWN_VERSION_DIR")"
+CACHE_PARENT="$(dirname "$OWN_VERSION_DIR")"
+
+SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'
+
+# Source-repo guard: own parent dir is NOT semver → dispatch to own scripts/.
+if ! [[ "$OWN_VERSION_NAME" =~ $SEMVER_RE ]]; then
+  exec "$SHIM_DIR/../scripts/mark-story-oversight-confirmed.sh" "$@"
+fi
+
+# Cache execution: pick the highest-semver sibling under CACHE_PARENT.
+HIGHEST=""
+while IFS= read -r dir; do
+  name="$(basename "$dir")"
+  [[ "$name" =~ $SEMVER_RE ]] || continue
+  if [[ -z "$HIGHEST" ]] || [[ "$(printf '%s\n%s\n' "$HIGHEST" "$name" | sort -V | tail -1)" == "$name" ]]; then
+    HIGHEST="$name"
+  fi
+done < <(find "$CACHE_PARENT" -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+if [[ -z "$HIGHEST" ]]; then
+  printf 'wr-shim: no cached versions in %s\n' "$CACHE_PARENT" >&2
+  exit 127
+fi
+
+exec "$CACHE_PARENT/$HIGHEST/scripts/mark-story-oversight-confirmed.sh" "$@"

package/lib/story-oversight.sh

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# story-oversight.sh — ADR-090 lazy-fingerprint ratification helpers.
+#
+# Shared by detect-unratified-stories-maps.sh, check-rfc-stories-ratified.sh, and
+# mark-story-oversight-confirmed.sh so all three agree on ONE hash definition
+# (if they diverged, a freshly-ratified artefact would read as drifted forever).
+#
+# A story/map is RATIFIED when it carries a `confirmed` human-oversight marker
+# AND a stored oversight-hash that matches a fresh hash of its content-minus-
+# marker. Any content edit changes the hash → the artefact reads as drifted /
+# unratified until re-ratified. This is ADR-090's drift-invalidation (ADR-009
+# drift lineage, NOT ADR-066 write-once) — the same hash-the-artefact pattern
+# the external-comms gate uses.
+#
+# Sourced, not executed. Requires `shasum` (BSD + coreutils both ship it).
+
+# Stable hash of the artefact's content EXCLUDING the two marker lines, so
+# writing/updating the marker is idempotent w.r.t. the hash. Covers both
+# encodings in one filter:
+#   - markdown: `human-oversight:` / `oversight-hash:` frontmatter lines
+#   - HTML:     <meta name="human-oversight" ...> / <meta name="oversight-hash" ...>
+oversight_content_hash() {
+  grep -vE '^(human-oversight|oversight-hash):|<meta[^>]*name="(human-oversight|oversight-hash)"' "$1" \
+    | shasum -a 256 | awk '{print $1}'
+}
+
+# Echo the stored oversight-hash (md frontmatter OR HTML meta), empty if none.
+oversight_stored_hash() {
+  local h
+  h="$(grep -oE '^oversight-hash:[[:space:]]*[a-f0-9]{64}' "$1" 2>/dev/null | grep -oE '[a-f0-9]{64}' | head -1)"
+  [ -z "$h" ] && h="$(grep -oE '<meta[^>]*name="oversight-hash"[^>]*content="[a-f0-9]{64}"' "$1" 2>/dev/null | grep -oE '[a-f0-9]{64}' | head -1)"
+  printf '%s' "$h"
+}
+
+# True (0) if the file carries a `confirmed` human-oversight marker (md or HTML).
+oversight_is_confirmed() {
+  grep -qiE '^human-oversight:[[:space:]]*confirmed([[:space:]]|$)' "$1" && return 0
+  grep -qiE '<meta[^>]*name="human-oversight"[^>]*content="confirmed"' "$1" && return 0
+  return 1
+}
+
+# True (0) if RATIFIED: confirmed AND a stored hash that matches current content.
+# A confirmed marker with NO stored hash (legacy hand-ratified) is NOT ratified —
+# it must be re-ratified once to gain its fingerprint.
+is_story_map_ratified() {
+  local f="$1" stored
+  oversight_is_confirmed "$f" || return 1
+  stored="$(oversight_stored_hash "$f")"
+  [ -z "$stored" ] && return 1
+  [ "$stored" = "$(oversight_content_hash "$f")" ]
+}

package/package.json

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

package/scripts/check-rfc-stories-ratified.sh

@@ -17,6 +17,12 @@
 # Authority: ADR-090. Driver: P404 Phase 2. Test: check-rfc-stories-ratified.bats.
 set -euo pipefail
 
+# Adopter-safe: source the shared lazy-fingerprint lib RELATIVE TO THIS SCRIPT (P317).
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
+  echo "check-rfc-stories-ratified: cannot locate lib dir" >&2; exit 2; }
+# shellcheck source=/dev/null
+source "$LIB/story-oversight.sh"
+
 rfc="${1:-}"
 stories_root="${2:-docs/stories}"
 if [ -z "$rfc" ]; then
@@ -45,7 +51,7 @@ for id in $ids; do
     unratified="$unratified $id(missing)"
     continue
   fi
-  if ! grep -qE '^human-oversight:[[:space:]]*confirmed([[:space:]]|$)' "$f"; then
+  if ! is_story_map_ratified "$f"; then
     unratified="$unratified $id(unratified)"
   fi
 done

package/scripts/detect-unratified-stories-maps.sh

@@ -1,42 +1,43 @@
 #!/usr/bin/env bash
 # detect-unratified-stories-maps.sh — ADR-090 detector.
 #
-# Token-cheap detection of story maps + stories lacking the ratified
-# `human-oversight: confirmed` marker. Mirrors wr-architect detect-unoversighted.sh
-# but spans two artefact types with different marker encodings:
-#   - stories:    markdown YAML frontmatter  `human-oversight: confirmed`
-#   - story-maps: HTML meta tag              `<meta name="human-oversight" content="confirmed">`
-#
-# ADR-090's marker is DRIFT-INVALIDATED (unlike ADR-066 write-once): an edit
-# re-opens it to `unconfirmed`, so this detector surfaces both the never-ratified
-# (no marker) and the drift-reopened (`unconfirmed`) cases as the drain queue.
+# Token-cheap detection of story maps + stories that are NOT ratified. Mirrors
+# wr-architect detect-unoversighted.sh but spans two artefact types and is
+# DRIFT-AWARE via the shared lazy-fingerprint helper: an artefact is ratified
+# only when it carries a `confirmed` human-oversight marker AND a stored
+# oversight-hash matching its current content. This surfaces three cases as the
+# drain queue:
+#   - never ratified   (no marker)
+#   - drift-reopened   (marker says confirmed, but content changed → hash mismatch)
+#   - legacy confirmed  (confirmed but no fingerprint yet — needs one re-ratify)
 #
 # Usage: detect-unratified-stories-maps.sh [STORIES_DIR=docs/stories] [MAPS_DIR=docs/story-maps]
-# Output: one unratified artefact path per line, sorted. Empty = all confirmed.
+# Output: one unratified artefact path per line, sorted. Empty = all ratified.
 # Always exits 0 (detector, not a gate). Consumed by the work-problems Step 2.4
-# oversight-unconfirmed drain (mirror of the architect/jtbd detectors).
+# oversight-unconfirmed drain.
 set -euo pipefail
 
+# Adopter-safe: source the shared hash lib RELATIVE TO THIS SCRIPT (P317).
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
+  echo "detect-unratified-stories-maps: cannot locate lib dir" >&2; exit 0; }
+# shellcheck source=/dev/null
+source "$LIB/story-oversight.sh"
+
 STORIES_DIR="${1:-docs/stories}"
 MAPS_DIR="${2:-docs/story-maps}"
 
 shopt -s nullglob
 
 {
-  # Stories — markdown YAML frontmatter.
   if [ -d "$STORIES_DIR" ]; then
     for f in "$STORIES_DIR"/*.md "$STORIES_DIR"/*/*.md; do
       [ "$(basename "$f")" = "README.md" ] && continue
-      fm="$(awk 'NR==1 && $0 != "---" { exit } NR==1 { next } /^---[[:space:]]*$/ { exit } { print }' "$f")"
-      printf '%s\n' "$fm" | grep -qiE '^human-oversight:[[:space:]]*confirmed[[:space:]]*$' && continue
-      echo "$f"
+      is_story_map_ratified "$f" || echo "$f"
     done
   fi
-  # Story maps — HTML meta tag.
   if [ -d "$MAPS_DIR" ]; then
     for f in "$MAPS_DIR"/*.html "$MAPS_DIR"/*/*.html; do
-      grep -qiE '<meta[^>]*name="human-oversight"[^>]*content="confirmed"' "$f" && continue
-      echo "$f"
+      is_story_map_ratified "$f" || echo "$f"
     done
   fi
 } | sort

package/scripts/mark-story-oversight-confirmed.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# mark-story-oversight-confirmed.sh — ADR-090 ratify write-path.
+#
+# Writes `human-oversight: confirmed` + an `oversight-hash` fingerprint of the
+# current content into a story (markdown frontmatter) or story-map (HTML meta).
+# Idempotent: re-running recomputes the hash and replaces any existing marker
+# (never duplicates). A later content edit changes the content hash, so the
+# stored fingerprint no longer matches → the artefact reads as drifted /
+# unratified until re-ratified (ADR-090 drift-invalidation).
+#
+# Usage: mark-story-oversight-confirmed.sh <story-or-map-file>
+# Exit:  0 = ratified; 2 = usage / file error.
+#
+# Authority: ADR-090. Driver: P404 Phase 2. Test: mark-story-oversight-confirmed.bats.
+set -euo pipefail
+
+# Adopter-safe: source the shared hash lib RELATIVE TO THIS SCRIPT (P317), never
+# repo-relative.
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
+  echo "mark-story-oversight-confirmed: cannot locate lib dir" >&2; exit 2; }
+# shellcheck source=/dev/null
+source "$LIB/story-oversight.sh"
+
+f="${1:-}"
+if [ -z "$f" ]; then
+  echo "mark-story-oversight-confirmed: usage: mark-story-oversight-confirmed.sh <file>" >&2
+  exit 2
+fi
+[ -f "$f" ] || { echo "mark-story-oversight-confirmed: file not found: $f" >&2; exit 2; }
+
+h="$(oversight_content_hash "$f")"
+tmp="$(mktemp)"
+
+case "$f" in
+  *.html)
+    if grep -qi '<head' "$f"; then
+      # Insert the two metas after the <head> tag; drop any existing marker metas.
+      awk -v H="$h" '
+        /<meta[^>]*name="(human-oversight|oversight-hash)"/ { next }
+        { print }
+        !done && tolower($0) ~ /<head[ >]/ {
+          print "  <meta name=\"human-oversight\" content=\"confirmed\">"
+          print "  <meta name=\"oversight-hash\" content=\"" H "\">"
+          done=1
+        }
+      ' "$f" > "$tmp"
+    else
+      # No <head> — prepend the metas (position is irrelevant to the hash).
+      { printf '<meta name="human-oversight" content="confirmed">\n'
+        printf '<meta name="oversight-hash" content="%s">\n' "$h"
+        grep -vE '<meta[^>]*name="(human-oversight|oversight-hash)"' "$f"; } > "$tmp"
+    fi
+    ;;
+  *)
+    # Markdown: rewrite frontmatter — drop existing markers, insert both before
+    # the closing `---`.
+    awk -v H="$h" '
+      NR==1 && $0=="---" { infm=1; print; next }
+      infm && /^(human-oversight|oversight-hash):/ { next }
+      infm && /^---[[:space:]]*$/ && !done {
+        print "human-oversight: confirmed"
+        print "oversight-hash: " H
+        print; done=1; infm=0; next
+      }
+      { print }
+    ' "$f" > "$tmp"
+    ;;
+esac
+
+mv "$tmp" "$f"
+echo "mark-story-oversight-confirmed: ratified $f (oversight-hash ${h:0:12}…)" >&2
+exit 0

package/scripts/test/check-rfc-stories-ratified.bats

@@ -1,26 +1,29 @@
 #!/usr/bin/env bats
 # Behavioural test for check-rfc-stories-ratified.sh (ADR-090 — an RFC may
-# reference only RATIFIED stories). For each STORY-NNN in the RFC's stories:
-# frontmatter, the predicate resolves the story file and verifies
-# human-oversight: confirmed. Composes with check-rfc-has-stories (ADR-089):
-# has-stories checks >=1 exists; this checks each listed one is ratified.
+# reference only RATIFIED stories). DRIFT-AWARE via the shared lazy-fingerprint
+# lib: a listed story counts only when it is `confirmed` AND its stored
+# oversight-hash matches current content. Composes with check-rfc-has-stories
+# (ADR-089): has-stories checks >=1 exists; this checks each listed one is ratified.
 #
-# @adr ADR-090 (story maps and stories carry a drift-invalidated human-oversight marker)
+# @adr ADR-090
 # @problem P404 (implement ADR-089 + ADR-090) — Phase 2
 
 setup() {
   REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
   SCRIPT="${REPO_ROOT}/packages/itil/scripts/check-rfc-stories-ratified.sh"
+  MARK="${REPO_ROOT}/packages/itil/scripts/mark-story-oversight-confirmed.sh"
   TMPD="$(mktemp -d)"
   mkdir -p "$TMPD/stories/accepted"
 }
 teardown() { rm -rf "$TMPD"; }
 
-mkstory() { # $1=id $2=oversight-value(or "none")
+mkstory() { # $1=id $2=confirmed|unconfirmed|none
   local f="$TMPD/stories/accepted/$1-x.md"
-  { echo "---"; echo "status: accepted"; echo "story-id: x"
-    [ "$2" != "none" ] && echo "human-oversight: $2"
-    echo "---"; echo "# $1"; } > "$f"
+  case "$2" in
+    confirmed)   printf -- '---\nstatus: accepted\n---\n# %s\n' "$1" > "$f"; bash "$MARK" "$f" ;;
+    unconfirmed) printf -- '---\nstatus: accepted\nhuman-oversight: unconfirmed\n---\n# %s\n' "$1" > "$f" ;;
+    none)        printf -- '---\nstatus: accepted\n---\n# %s\n' "$1" > "$f" ;;
+  esac
 }
 mkrfc() { printf -- '---\nstatus: proposed\nstories: [%s]\n---\n# rfc\n' "$1" > "$TMPD/RFC.proposed.md"; }
 
@@ -30,14 +33,14 @@ mkrfc() { printf -- '---\nstatus: proposed\nstories: [%s]\n---\n# rfc\n' "$1" >
   [ "$status" -eq 0 ]
 }
 
-@test "check-rfc-stories-ratified: a confirmed story is ACCEPTED (exit 0)" {
+@test "check-rfc-stories-ratified: a ratified (confirmed+hash) story is ACCEPTED (exit 0)" {
   mkstory STORY-020 confirmed
   mkrfc STORY-020
   run bash "$SCRIPT" "$TMPD/RFC.proposed.md" "$TMPD/stories"
   [ "$status" -eq 0 ]
 }
 
-@test "check-rfc-stories-ratified: an unconfirmed story is REJECTED (exit non-zero)" {
+@test "check-rfc-stories-ratified: an unconfirmed story is REJECTED" {
   mkstory STORY-020 unconfirmed
   mkrfc STORY-020
   run bash "$SCRIPT" "$TMPD/RFC.proposed.md" "$TMPD/stories"
@@ -53,6 +56,15 @@ mkrfc() { printf -- '---\nstatus: proposed\nstories: [%s]\n---\n# rfc\n' "$1" >
   [[ "$output" == *"STORY-020"* ]]
 }
 
+@test "check-rfc-stories-ratified: a confirmed-but-DRIFTED story is REJECTED" {
+  mkstory STORY-020 confirmed
+  printf '\nedit after ratify\n' >> "$TMPD/stories/accepted/STORY-020-x.md"
+  mkrfc STORY-020
+  run bash "$SCRIPT" "$TMPD/RFC.proposed.md" "$TMPD/stories"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"STORY-020"* ]]
+}
+
 @test "check-rfc-stories-ratified: a missing story file is REJECTED" {
   mkrfc STORY-099
   run bash "$SCRIPT" "$TMPD/RFC.proposed.md" "$TMPD/stories"
@@ -60,7 +72,7 @@ mkrfc() { printf -- '---\nstatus: proposed\nstories: [%s]\n---\n# rfc\n' "$1" >
   [[ "$output" == *"STORY-099"* ]]
 }
 
-@test "check-rfc-stories-ratified: mixed — one confirmed one unconfirmed is REJECTED" {
+@test "check-rfc-stories-ratified: mixed — one ratified one unconfirmed is REJECTED" {
   mkstory STORY-020 confirmed
   mkstory STORY-021 unconfirmed
   mkrfc "STORY-020, STORY-021"

package/scripts/test/detect-unratified-stories-maps.bats

@@ -1,44 +1,54 @@
 #!/usr/bin/env bats
 # Behavioural test for detect-unratified-stories-maps.sh (ADR-090 detector).
-# Mirrors wr-architect detect-unoversighted.sh, but spans TWO artefact types
-# with DIFFERENT marker encodings:
-#   - stories: markdown YAML frontmatter `human-oversight: confirmed`
-#   - story-maps: HTML `<meta name="human-oversight" content="confirmed">`
-# Lists every artefact whose marker is missing or not `confirmed`. Always exit 0.
+# DRIFT-AWARE via the shared lazy-fingerprint lib: an artefact counts as ratified
+# only when it is `confirmed` AND its stored oversight-hash matches current
+# content. Surfaces never-ratified, unconfirmed, and drift-reopened (confirmed
+# then edited) cases; omits genuinely-ratified ones. Always exit 0.
 #
-# @adr ADR-090 (drift-invalidated story-map/story human-oversight marker)
-# @problem P404 (implement ADR-089 + ADR-090) — Phase 2
+# @adr ADR-090
+# @problem P404 (Phase 2)
 
 setup() {
   REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
   SCRIPT="${REPO_ROOT}/packages/itil/scripts/detect-unratified-stories-maps.sh"
+  MARK="${REPO_ROOT}/packages/itil/scripts/mark-story-oversight-confirmed.sh"
   TMPD="$(mktemp -d)"
   mkdir -p "$TMPD/stories/accepted" "$TMPD/story-maps/draft"
-  # stories (markdown frontmatter)
-  printf -- '---\nstatus: accepted\nhuman-oversight: confirmed\n---\n# ok\n'   > "$TMPD/stories/accepted/STORY-1-ok.md"
+
+  # Genuinely ratified (via the mark write-path) — should NOT be listed.
+  printf -- '---\nstatus: accepted\n---\n# ok\n' > "$TMPD/stories/accepted/STORY-1-ok.md"
+  bash "$MARK" "$TMPD/stories/accepted/STORY-1-ok.md"
+  printf -- '<head></head>\n<h1>ok map</h1>\n' > "$TMPD/story-maps/draft/STORY-MAP-1-ok.html"
+  bash "$MARK" "$TMPD/story-maps/draft/STORY-MAP-1-ok.html"
+
+  # Unconfirmed + unmarked — listed.
   printf -- '---\nstatus: accepted\nhuman-oversight: unconfirmed\n---\n# no\n' > "$TMPD/stories/accepted/STORY-2-unconf.md"
   printf -- '---\nstatus: accepted\n---\n# nomarker\n'                          > "$TMPD/stories/accepted/STORY-3-none.md"
-  # story-maps (HTML meta)
-  printf -- '<meta name="human-oversight" content="confirmed">\n'   > "$TMPD/story-maps/draft/STORY-MAP-1-ok.html"
-  printf -- '<meta name="human-oversight" content="unconfirmed">\n' > "$TMPD/story-maps/draft/STORY-MAP-2-unconf.html"
-  printf -- '<h1>no meta</h1>\n'                                     > "$TMPD/story-maps/draft/STORY-MAP-3-none.html"
+
+  # Drifted: ratified, then content edited afterward — listed.
+  printf -- '---\nstatus: accepted\n---\n# body\n' > "$TMPD/stories/accepted/STORY-4-drift.md"
+  bash "$MARK" "$TMPD/stories/accepted/STORY-4-drift.md"
+  printf '\nAn edit made after ratification.\n' >> "$TMPD/stories/accepted/STORY-4-drift.md"
+
+  # HTML map with no marker — listed.
+  printf -- '<h1>no meta</h1>\n' > "$TMPD/story-maps/draft/STORY-MAP-3-none.html"
 }
 teardown() { rm -rf "$TMPD"; }
 
-@test "detect: lists unconfirmed + unmarked, omits confirmed; exits 0" {
+@test "detect: lists unconfirmed + unmarked + DRIFTED, omits genuinely-ratified; exit 0" {
   run bash "$SCRIPT" "$TMPD/stories" "$TMPD/story-maps"
   [ "$status" -eq 0 ]
   [[ "$output" == *"STORY-2-unconf.md"* ]]
   [[ "$output" == *"STORY-3-none.md"* ]]
-  [[ "$output" == *"STORY-MAP-2-unconf.html"* ]]
+  [[ "$output" == *"STORY-4-drift.md"* ]]
   [[ "$output" == *"STORY-MAP-3-none.html"* ]]
   [[ "$output" != *"STORY-1-ok.md"* ]]
   [[ "$output" != *"STORY-MAP-1-ok.html"* ]]
 }
 
-@test "detect: all-confirmed set yields empty output, exit 0" {
+@test "detect: all-ratified set yields empty output, exit 0" {
   rm "$TMPD/stories/accepted/STORY-2-unconf.md" "$TMPD/stories/accepted/STORY-3-none.md" \
-     "$TMPD/story-maps/draft/STORY-MAP-2-unconf.html" "$TMPD/story-maps/draft/STORY-MAP-3-none.html"
+     "$TMPD/stories/accepted/STORY-4-drift.md" "$TMPD/story-maps/draft/STORY-MAP-3-none.html"
   run bash "$SCRIPT" "$TMPD/stories" "$TMPD/story-maps"
   [ "$status" -eq 0 ]
   [ -z "$output" ]

package/scripts/test/mark-story-oversight-confirmed.bats

@@ -0,0 +1,53 @@
+#!/usr/bin/env bats
+# Behavioural test for mark-story-oversight-confirmed.sh (ADR-090 ratify write-path).
+# Writes `confirmed` + the content fingerprint into a story (md frontmatter) or a
+# story-map (HTML meta). After marking, is_story_map_ratified is true; a later
+# content edit drifts it back to not-ratified.
+#
+# @adr ADR-090
+# @problem P404 (Phase 2)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="${REPO_ROOT}/packages/itil/scripts/mark-story-oversight-confirmed.sh"
+  # shellcheck source=/dev/null
+  source "${REPO_ROOT}/packages/itil/lib/story-oversight.sh"
+  TMPD="$(mktemp -d)"
+}
+teardown() { rm -rf "$TMPD"; }
+
+@test "mark: md story with no marker → ratified after mark" {
+  printf -- '---\nstatus: accepted\n---\n# body\n' > "$TMPD/s.md"
+  run bash "$SCRIPT" "$TMPD/s.md"; [ "$status" -eq 0 ]
+  run is_story_map_ratified "$TMPD/s.md"; [ "$status" -eq 0 ]
+}
+
+@test "mark: md story with existing unconfirmed marker → confirmed + ratified" {
+  printf -- '---\nstatus: accepted\nhuman-oversight: unconfirmed\n---\n# body\n' > "$TMPD/s.md"
+  bash "$SCRIPT" "$TMPD/s.md"
+  grep -qE '^human-oversight:[[:space:]]*confirmed' "$TMPD/s.md"
+  run is_story_map_ratified "$TMPD/s.md"; [ "$status" -eq 0 ]
+  # no duplicate marker line left behind
+  [ "$(grep -cE '^human-oversight:' "$TMPD/s.md")" -eq 1 ]
+}
+
+@test "mark: idempotent — marking twice stays ratified, single marker" {
+  printf -- '---\nstatus: accepted\n---\n# body\n' > "$TMPD/s.md"
+  bash "$SCRIPT" "$TMPD/s.md"; bash "$SCRIPT" "$TMPD/s.md"
+  run is_story_map_ratified "$TMPD/s.md"; [ "$status" -eq 0 ]
+  [ "$(grep -cE '^oversight-hash:' "$TMPD/s.md")" -eq 1 ]
+}
+
+@test "mark: drift — mark then edit body → not ratified" {
+  printf -- '---\nstatus: accepted\n---\n# body\n' > "$TMPD/s.md"
+  bash "$SCRIPT" "$TMPD/s.md"
+  printf -- '---\nstatus: accepted\nhuman-oversight: confirmed\n---\n# body EDITED\n' > "$TMPD/s.md"
+  run is_story_map_ratified "$TMPD/s.md"; [ "$status" -ne 0 ]
+}
+
+@test "mark: HTML map → ratified after mark" {
+  printf -- '<!doctype html>\n<head><title>map</title></head>\n<body><h1>map</h1></body>\n' > "$TMPD/m.html"
+  run bash "$SCRIPT" "$TMPD/m.html"; [ "$status" -eq 0 ]
+  grep -qE '<meta[^>]*name="human-oversight"[^>]*content="confirmed"' "$TMPD/m.html"
+  run is_story_map_ratified "$TMPD/m.html"; [ "$status" -eq 0 ]
+}

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

@@ -0,0 +1,64 @@
+#!/usr/bin/env bats
+# Behavioural test for lib/story-oversight.sh — ADR-090 lazy-fingerprint helpers.
+# The hash EXCLUDES the marker lines (so writing the marker is idempotent), and
+# "ratified" = confirmed marker AND stored hash matches current content. Any
+# content edit drifts the hash → not ratified (ADR-090 drift-invalidation).
+#
+# @adr ADR-090
+# @problem P404 (Phase 2)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  LIB="${REPO_ROOT}/packages/itil/lib/story-oversight.sh"
+  TMPD="$(mktemp -d)"
+  # shellcheck source=/dev/null
+  source "$LIB"
+}
+teardown() { rm -rf "$TMPD"; }
+
+@test "oversight_content_hash: identical content → identical hash" {
+  printf '# body\nline two\n' > "$TMPD/a"; printf '# body\nline two\n' > "$TMPD/b"
+  [ "$(oversight_content_hash "$TMPD/a")" = "$(oversight_content_hash "$TMPD/b")" ]
+}
+
+@test "oversight_content_hash: adding/changing the marker lines does NOT change the hash" {
+  printf -- '---\nstatus: accepted\n---\n# body\n' > "$TMPD/f"
+  before="$(oversight_content_hash "$TMPD/f")"
+  printf -- '---\nstatus: accepted\nhuman-oversight: confirmed\noversight-hash: %064d\n---\n# body\n' 0 > "$TMPD/f"
+  [ "$before" = "$(oversight_content_hash "$TMPD/f")" ]
+}
+
+@test "oversight_content_hash: a real content edit DOES change the hash" {
+  printf '# body\n' > "$TMPD/f"; before="$(oversight_content_hash "$TMPD/f")"
+  printf '# body EDITED\n' > "$TMPD/f"
+  [ "$before" != "$(oversight_content_hash "$TMPD/f")" ]
+}
+
+@test "is_story_map_ratified: confirmed + matching hash → ratified (md)" {
+  printf -- '---\nstatus: accepted\n---\n# body\n' > "$TMPD/f"
+  h="$(oversight_content_hash "$TMPD/f")"
+  printf -- '---\nstatus: accepted\nhuman-oversight: confirmed\noversight-hash: %s\n---\n# body\n' "$h" > "$TMPD/f"
+  run is_story_map_ratified "$TMPD/f"; [ "$status" -eq 0 ]
+}
+
+@test "is_story_map_ratified: confirmed but STALE hash (drifted) → not ratified" {
+  printf -- '---\nhuman-oversight: confirmed\noversight-hash: %064d\n---\n# body EDITED AFTER RATIFY\n' 1 > "$TMPD/f"
+  run is_story_map_ratified "$TMPD/f"; [ "$status" -ne 0 ]
+}
+
+@test "is_story_map_ratified: confirmed with NO hash (legacy hand-ratified) → not ratified" {
+  printf -- '---\nhuman-oversight: confirmed\n---\n# body\n' > "$TMPD/f"
+  run is_story_map_ratified "$TMPD/f"; [ "$status" -ne 0 ]
+}
+
+@test "is_story_map_ratified: unconfirmed → not ratified" {
+  printf -- '---\nhuman-oversight: unconfirmed\n---\n# body\n' > "$TMPD/f"
+  run is_story_map_ratified "$TMPD/f"; [ "$status" -ne 0 ]
+}
+
+@test "is_story_map_ratified: HTML map confirmed + matching hash → ratified" {
+  printf '<h1>map</h1>\n' > "$TMPD/m.html"
+  h="$(oversight_content_hash "$TMPD/m.html")"
+  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 ]
+}