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

package/bin/wr-itil-check-rfc-stories-ratified

@@ -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/check-rfc-stories-ratified.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/check-rfc-stories-ratified.sh" "$@"

package/bin/wr-itil-detect-unratified-stories-maps

@@ -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/detect-unratified-stories-maps.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/detect-unratified-stories-maps.sh" "$@"

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.878",
+  "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

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# check-rfc-stories-ratified.sh — ADR-090 (an RFC may reference only RATIFIED stories).
+#
+# For each STORY-NNN in the RFC's `stories:` frontmatter, resolve the story file
+# under <stories-root>/*/STORY-NNN-*.md and verify it carries
+# `human-oversight: confirmed`. Exit non-zero (with a stderr directive naming the
+# offending stories) if any listed story is unratified, unconfirmed, or missing.
+#
+# Composes with check-rfc-has-stories.sh (ADR-089): has-stories checks >=1 story
+# exists; this checks each listed story is ratified. An empty `stories:` passes
+# vacuously here (the has-stories gate owns the emptiness rejection).
+#
+# Usage: check-rfc-stories-ratified.sh <rfc-file> [stories-root=docs/stories]
+# Exit:  0 = all listed stories ratified (or none listed); 1 = >=1 unratified/missing;
+#        2 = usage / file error.
+#
+# 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
+  echo "check-rfc-stories-ratified: usage: check-rfc-stories-ratified.sh <rfc-file> [stories-root]" >&2
+  exit 2
+fi
+if [ ! -f "$rfc" ]; then
+  echo "check-rfc-stories-ratified: file not found: $rfc" >&2
+  exit 2
+fi
+
+# Collect STORY-NNN ids from the stories: frontmatter (inline list OR block list).
+stories_line="$(awk '/^stories:/{print; exit}' "$rfc")"
+ids="$(printf '%s' "$stories_line" | grep -oE 'STORY-[0-9]+' || true)"
+if [ -z "$ids" ]; then
+  ids="$(awk '/^stories:/{f=1;next} f&&/^[[:space:]]*-/{print} f&&/^[^[:space:]-]/{exit}' "$rfc" | grep -oE 'STORY-[0-9]+' || true)"
+fi
+
+# No stories listed → vacuously ratified (has-stories gate owns emptiness).
+[ -z "$ids" ] && exit 0
+
+unratified=""
+for id in $ids; do
+  f="$(ls "$stories_root"/*/"$id"-*.md 2>/dev/null | head -1 || true)"
+  if [ -z "$f" ]; then
+    unratified="$unratified $id(missing)"
+    continue
+  fi
+  if ! is_story_map_ratified "$f"; then
+    unratified="$unratified $id(unratified)"
+  fi
+done
+
+if [ -n "$unratified" ]; then
+  echo "check-rfc-stories-ratified: $rfc references unratified stories:$unratified — ADR-090: an RFC may reference only ratified (human-oversight: confirmed) stories. Ratify them first." >&2
+  exit 1
+fi
+exit 0

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

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+# detect-unratified-stories-maps.sh — ADR-090 detector.
+#
+# 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 ratified.
+# Always exits 0 (detector, not a gate). Consumed by the work-problems Step 2.4
+# 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
+
+{
+  if [ -d "$STORIES_DIR" ]; then
+    for f in "$STORIES_DIR"/*.md "$STORIES_DIR"/*/*.md; do
+      [ "$(basename "$f")" = "README.md" ] && continue
+      is_story_map_ratified "$f" || echo "$f"
+    done
+  fi
+  if [ -d "$MAPS_DIR" ]; then
+    for f in "$MAPS_DIR"/*.html "$MAPS_DIR"/*/*.html; do
+      is_story_map_ratified "$f" || echo "$f"
+    done
+  fi
+} | sort
+
+exit 0

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

@@ -0,0 +1,82 @@
+#!/usr/bin/env bats
+# Behavioural test for check-rfc-stories-ratified.sh (ADR-090 — an RFC may
+# 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
+# @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=confirmed|unconfirmed|none
+  local f="$TMPD/stories/accepted/$1-x.md"
+  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"; }
+
+@test "check-rfc-stories-ratified: empty stories: [] passes vacuously (exit 0)" {
+  printf -- '---\nstatus: proposed\nstories: []\n---\n# rfc\n' > "$TMPD/RFC.proposed.md"
+  run bash "$SCRIPT" "$TMPD/RFC.proposed.md" "$TMPD/stories"
+  [ "$status" -eq 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" {
+  mkstory STORY-020 unconfirmed
+  mkrfc STORY-020
+  run bash "$SCRIPT" "$TMPD/RFC.proposed.md" "$TMPD/stories"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"STORY-020"* ]]
+}
+
+@test "check-rfc-stories-ratified: a story with NO oversight marker is REJECTED" {
+  mkstory STORY-020 none
+  mkrfc STORY-020
+  run bash "$SCRIPT" "$TMPD/RFC.proposed.md" "$TMPD/stories"
+  [ "$status" -ne 0 ]
+  [[ "$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"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"STORY-099"* ]]
+}
+
+@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"
+  run bash "$SCRIPT" "$TMPD/RFC.proposed.md" "$TMPD/stories"
+  [ "$status" -ne 0 ]
+  [[ "$output" == *"STORY-021"* ]]
+}

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

@@ -0,0 +1,60 @@
+#!/usr/bin/env bats
+# Behavioural test for detect-unratified-stories-maps.sh (ADR-090 detector).
+# 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
+# @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"
+
+  # 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"
+
+  # 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 + 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-4-drift.md"* ]]
+  [[ "$output" == *"STORY-MAP-3-none.html"* ]]
+  [[ "$output" != *"STORY-1-ok.md"* ]]
+  [[ "$output" != *"STORY-MAP-1-ok.html"* ]]
+}
+
+@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/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" ]
+}
+
+@test "detect: missing dirs are tolerated (exit 0, no crash)" {
+  run bash "$SCRIPT" "$TMPD/nope-stories" "$TMPD/nope-maps"
+  [ "$status" -eq 0 ]
+}

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 ]
+}

package/skills/manage-rfc/SKILL.md

@@ -118,7 +118,7 @@ Each transition is a `git mv` + Edit + `git add` (P057 staging trap) + README re
 
 | Transition | Checks |
 |------------|--------|
-| `proposed → accepted` | All `problems:` entries resolve. Architect re-review PASS. JTBD re-review PASS. `## Scope` populated (not "deferred"). `## Tasks` decomposed (≥ 1 task; not just deferred placeholder). **`stories:` non-empty — run `wr-itil-check-rfc-has-stories <rfc-file>`; hard-block on non-zero exit (empty `stories: []` or missing).** Per **ADR-089** the empty-stories fallback is removed: an atomic fix is an RFC with exactly one full story; an empty `stories:` is permitted only on a `proposed`/draft RFC before the fix is scoped, never at `accepted`. |
+| `proposed → accepted` | All `problems:` entries resolve. Architect re-review PASS. JTBD re-review PASS. `## Scope` populated (not "deferred"). `## Tasks` decomposed (≥ 1 task; not just deferred placeholder). **`stories:` non-empty — run `wr-itil-check-rfc-has-stories <rfc-file>`; hard-block on non-zero exit (empty `stories: []` or missing).** Per **ADR-089** the empty-stories fallback is removed: an atomic fix is an RFC with exactly one full story; an empty `stories:` is permitted only on a `proposed`/draft RFC before the fix is scoped, never at `accepted`. **Every listed story ratified — run `wr-itil-check-rfc-stories-ratified <rfc-file>`; hard-block on non-zero (any listed story carries `human-oversight: unconfirmed`, has no marker, or is missing).** Per **ADR-090** an RFC may reference only ratified stories; composes with the has-stories gate (has-stories checks ≥1 exists, ratified checks each is confirmed). |
 | `accepted → in-progress` | First commit referencing `Refs: RFC-<NNN>` exists OR is being authored in this same commit. I1 hard-block on missing/orphan trace. |
 | `in-progress → verifying` | All `## Tasks` checked. `## Verification` section drafted (release marker, user-side check, trace closure path). I1 hard-block on missing/orphan trace. |
 | `verifying → closed` | User explicitly confirms (or AFK Rule 6 fallback for evidence-based close per ADR-022 / ADR-044 framework-resolved silent dispatch). I1 advisory-with-escalation if driving problems Closed/Parked. |