@windyroad/itil 0.61.2 → 1.0.0

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.61.2"
+  "version": "1.0.0"
 }

package/README.md

@@ -93,7 +93,7 @@ See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for th
 | `/wr-itil:capture-story` | Lightweight story-capture skill — mandatory problem-trace AND JTBD-trace per ADR-060 I6 + I9 invariants; optional `--rfc` / `--story-map` flags (I7 + I8 enforce at `accepted` transition); drafts an INVEST-shaped sub-workstream entity under a parent RFC (Phase 2 of the Problem-RFC-Story framework, P170 / ADR-060) | Experimental |
 | `/wr-itil:list-stories` | Read-only display of stories grouped by lifecycle state, with optional `--rfc RFC-<NNN>` filter rendering the RFC's ordered story list per ADR-060 line 259 (Phase 2 / P170) | Experimental |
 | `/wr-itil:reconcile-stories` | Detect and correct drift between `docs/stories/README.md` and on-disk story inventory + reverse-trace `## Stories` sections on driving problems / RFCs / JTBDs (Phase 2 / P170) | Experimental |
-| `/wr-itil:manage-story` | Heavyweight story lifecycle management — draft → accepted → in-progress → done → archived; I7+I8+I10+I12 hard-block at accepted transition; INVEST 4-axis check; auto-transitions on `Refs: STORY-NNN` commit trailer + linked RFC closure (Phase 2 / P170). **I12 (ADR-101)**: `accepted` requires a recorded ratification basis, and an implementing commit against an unratified story is blocked. The basis is a human ratification event by default; an `oversight-basis: pure-decomposition` marker is written instead only where the project has opted in AND the story decomposes nothing but already-confirmed substance — see the config key below | Experimental |
+| `/wr-itil:manage-story` | Heavyweight story lifecycle management — draft → accepted → in-progress → done → archived; I7+I8+I10+I12 hard-block at accepted transition; INVEST 4-axis check; auto-transitions on `Refs: STORY-NNN` commit trailer + linked RFC closure (Phase 2 / P170). **I12 (ADR-103)**: `accepted` requires the story to be approved, and an implementing commit against an unapproved story is blocked. Approval is the story map's — ratify the map and every story on it is approved with it | Experimental |
 | `/wr-itil:capture-story-map` | Lightweight story-map-capture skill — mandatory problem-trace AND JTBD-trace per ADR-060 I3 + I4 invariants; HTML skeleton at `docs/story-maps/draft/STORY-MAP-NNN-<slug>.html` per ADR-060 § Phase 2 encoding amendment 2026-05-12 (Phase 2 / P170) | Experimental |
 | `/wr-itil:manage-story-map` | Heavyweight story-map lifecycle management — draft → accepted → in-progress → completed → archived; backbone/ribs/slices authoring guidance; reverse-trace `## Story Maps` refresh on driving problems + JTBDs (Phase 2 / P170) | Experimental |
 | `/wr-itil:reconcile-story-maps` | Detect and correct drift between `docs/story-maps/README.md` and on-disk story-map HTML inventory (Phase 2 / P170) | Experimental |
@@ -105,19 +105,7 @@ See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for th
 
 ## Configuration
 
-Optional. Create `.claude/itil.config.json` in your project (or `~/.claude/itil.config.json` for all your projects); a project key wins over a machine key, and both are optional.
-
-| Key | Default | What it does |
-|---|---|---|
-| `afk_accept_pure_decomposition` | `false` | Lets an unattended run accept and implement a story **without** asking you first — but only when that story adds no new thinking. Every decision, job and map it draws on must already be one you confirmed, and each of its acceptance criteria must name the confirmed clause it breaks down. Anything that introduces a new design choice, persona or decision is still held for you. Off unless you turn it on. |
-
-```json
-{ "afk_accept_pure_decomposition": true }
-```
-
-Only the literal `true` turns it on. Stories accepted this way are marked `oversight-basis: pure-decomposition`, listed by `wr-itil-detect-unratified-stories-maps --with-afk-accepted`, and shown distinctly by `/wr-itil:list-stories`, so you can review them afterwards. Nothing ever writes this file for you. Background: ADR-101.
-
-Independently of this setting, an implementing commit against a story you have not ratified is blocked for everyone.
+An implementing commit against a story you have not approved is blocked. A story's approval is its story map's: ratify the map and every story on it is approved with it.
 
 ## Updating and Uninstalling
 

package/bin/{wr-itil-check-afk-accept-eligible → wr-itil-render-story-map}

@@ -30,7 +30,7 @@ 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-afk-accept-eligible.sh" "$@"
+  exec "$SHIM_DIR/../scripts/render-story-map.sh" "$@"
 fi
 
 # Cache execution: pick the highest-semver sibling under CACHE_PARENT.
@@ -48,4 +48,4 @@ if [[ -z "$HIGHEST" ]]; then
   exit 127
 fi
 
-exec "$CACHE_PARENT/$HIGHEST/scripts/check-afk-accept-eligible.sh" "$@"
+exec "$CACHE_PARENT/$HIGHEST/scripts/render-story-map.sh" "$@"

package/bin/wr-itil-story-map-edit

@@ -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/story-map-edit.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/story-map-edit.sh" "$@"

package/bin/wr-itil-story-map-query

@@ -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/story-map-query.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/story-map-query.sh" "$@"

package/hooks/itil-no-implement-draft-gate.sh

@@ -4,7 +4,8 @@
 # story still in docs/stories/draft/ — implementation requires `accepted` (where
 # the INVEST + RFC-trace gates + ADR-090 ratification fire). Capture commits are
 # exempt (they CREATE the draft story). Bootstrap-exempt commits bypass
-# (ADR-060 A4). Fail-open on every abnormal path (ADR-013 Rule 6).
+# (ADR-060 A4). Degrades to a no-op on abnormal paths — characterised, not
+# authorised; see the header note below.
 #
 # This is the enforcement locus the architect named as the ONLY one that catches
 # the exact P404 bypass — a direct implementing commit against a draft story,
@@ -14,25 +15,27 @@
 # (P465): a commit against an `accepted`/`in-progress` story is blocked unless
 # that story is ratified. This half is UNCONDITIONAL — a pure tightening, no
 # config, no opt-in — because putting an ADR-090-mandated check behind a flag
-# would be the decision conflict. Where the marker was machine-written under the
-# ADR-101 pure-decomposition carve-out, the gate additionally re-asserts the
-# story-LOCAL structure of that carve-out. It never re-evaluates the carve-out's
-# shared-artefact conditions: those are accept-time only, because unrelated churn
-# on a shared story map must not block an unrelated story (that is P456's shape).
+# would be the decision conflict. Under ADR-103 the approval surface is the story
+# MAP: a story carries no oversight marker of its own, and is approved when every
+# map in its `story-maps:` field is ratified.
 #
 # Bypass: BYPASS_NO_IMPLEMENT_DRAFT=1.
 #
-# @adr ADR-096 (no-implement-while-draft) ADR-060 (lifecycle) ADR-013 (Rule 6)
+# @adr ADR-096 (no-implement-while-draft) ADR-060 (lifecycle)
 #      ADR-095 (sibling capture-time gates) ADR-052 (bats)
-#      ADR-090 (drift-invalidated ratification) ADR-101 (AFK carve-out)
+#      ADR-090 (drift-invalidated ratification) ADR-103 (map is the approval surface)
 # @problem P404 P465 P456
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=lib/command-detect.sh
 source "$SCRIPT_DIR/lib/command-detect.sh" 2>/dev/null || exit 0
-# Fail-open per ADR-013 Rule 6. A missing story-oversight lib degrades to the
-# draft-only gate; a missing command-detect lib (sourced above with the same
-# guard) exits before the draft check too, so that path degrades to no gate at
-# all. Both fail in the safe direction — never blocking every commit.
+# Degrades to a no-op on a missing lib. NOT authorised by any in-force decision:
+# ADR-013 (Structured user interaction for governance-skill decisions) Rule 6
+# governs a skill that cannot reach AskUserQuestion, and its Continue clause
+# reads "Do NOT silently fail-soft-skip". This posture is CHARACTERISED, not
+# endorsed — see "the gate degrades to a no-op when its predicate lib is
+# missing" in hooks/test/. Both source guards are terminal and both precede
+# every check, so a missing lib — either one — degrades to no gate at all.
+# Open question queued at P369.
 # shellcheck source=../lib/story-oversight.sh
 source "$SCRIPT_DIR/../lib/story-oversight.sh" 2>/dev/null || exit 0
 
@@ -92,22 +95,10 @@ while IFS= read -r id; do
   [ ${#livefiles[@]} -gt 0 ] || continue
   story="${livefiles[0]}"
 
-  if ! is_story_map_ratified "$story"; then
-    deny "BLOCKED (ADR-090 / ADR-096 / P465): this commit references ${id}, but ${id} is not ratified — it carries no confirmed human-oversight marker, or its content has drifted since it was ratified. ADR-096 requires ratification before any implementation. Ratify it via /wr-itil:manage-story ${id} ratify, then re-commit. Bypass: BYPASS_NO_IMPLEMENT_DRAFT=1."
-  fi
-
-  # ADR-101 belt-and-braces. The load-bearing catch for a post-accept edit is
-  # the hash above (both `afk-accept:` and `## Decomposition basis` sit inside
-  # it). This adds a specific, actionable deny reason instead of a generic drift
-  # deny, on a story-local structure no shared-artefact churn can invalidate.
-  if oversight_is_pure_decomposition "$story"; then
-    oversight_declares_pure_decomposition "$story" || deny \
-      "BLOCKED (ADR-101): ${id} carries a machine-written pure-decomposition marker but no longer declares \`afk-accept: pure-decomposition\`. Re-accept it, or ratify it as a human via /wr-itil:manage-story ${id} ratify."
-    crit=$(awk '/^##[[:space:]]+Acceptance criteria/{i=1;next} i&&/^##[[:space:]]/{exit} i' "$story" | grep -cE '^- \[[ xX]\]')
-    basis=$(awk '/^##[[:space:]]+Decomposition basis/{i=1;next} i&&/^##[[:space:]]/{exit} i' "$story" | grep -cE '^- ')
-    if [ "$crit" -eq 0 ] || [ "$basis" -ne "$crit" ]; then
-      deny "BLOCKED (ADR-101): ${id} was AFK-accepted as pure decomposition, but its \`## Decomposition basis\` (${basis} entries) no longer matches its acceptance criteria (${crit}). Every criterion must name the already-confirmed clause it decomposes. Re-run /wr-itil:manage-story ${id} accepted, or ratify it as a human."
-    fi
+  # ADR-103: a story's approval is its story MAP's. The story itself carries no
+  # oversight marker, so there is one question to ask and one place to fix it.
+  if ! story_is_approved "$story"; then
+    deny "BLOCKED (ADR-103 / ADR-096 / P465): this commit references ${id}, but ${id} is not approved. A story is approved by its story map: every map in its \`story-maps:\` field must be ratified, and ${id} either names no map or names one that is unratified or has drifted since it was ratified. Ratify the map via /wr-itil:manage-story-map <MAP-ID> ratify, then re-commit. Bypass: BYPASS_NO_IMPLEMENT_DRAFT=1."
   fi
 done <<< "$STORIES"
 

package/lib/story-oversight.sh

@@ -5,7 +5,7 @@
 # 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
+# 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
@@ -19,6 +19,12 @@
 # encodings in one filter:
 #   - markdown: `human-oversight:` / `oversight-hash:` frontmatter lines
 #   - HTML:     <meta name="human-oversight" ...> / <meta name="oversight-hash" ...>
+#   - ADR-102 data island: the same fields as JSON keys, `"humanOversight":` /
+#     `"oversightHash":` / `"oversightDate":` / `"oversightNote":`. Since ADR-102
+#     scopes a map's hash to the island, the marker now lives INSIDE the hashed
+#     region — so without this third spelling, ratifying a map mutated the very
+#     bytes it was fingerprinting and the stored hash could never match. Every
+#     map would have read as drifted the instant it was ratified.
 # 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
@@ -40,7 +46,7 @@
 # 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)"' \
+  grep -vE '^(human-oversight|oversight-hash|oversight-basis|status):|<meta[^>]*name="(human-oversight|oversight-hash|oversight-basis|status)"|^[[:space:]]*"(humanOversight|oversightHash|oversightBasis|oversightDate|oversightNote|status)"[[:space:]]*:' \
     | sed -E 's/- \[[ xX]\]/- [ ]/g; s/data-status="[^"]*"/data-status=""/g'
 }
 
@@ -51,77 +57,113 @@ oversight_excluded_keys() {
   printf '%s\n' human-oversight oversight-hash oversight-basis status
 }
 
-oversight_content_hash() {
-  # 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
-# data-story-id is in the caller-supplied set (ADR-101 condition (a), map leg).
+# The MAP-SUBSTANCE key set: the island keys a story map's ratification hangs on.
 #
-# ADR-095 requires story-map membership at capture, so authoring a story ALWAYS
-# adds a card to its map — which, under ADR-090 drift-invalidation, re-opens the
-# map's ratification by construction. Requiring a hash-matching map would make
-# the AFK-accept carve-out unsatisfiable: capturing the story would break the
-# very condition the story must satisfy.
+# Editing this set — here or in the SUBSTANCE tuple below — changes ADR-090's
+# Decision Outcome as amended by ADR-103, not merely a mechanism. It IS the drift
+# trigger. A change here needs an ADR-090 amendment, and the bidirectional test
+# will NOT catch that: it asserts the accessor and the tuple agree, so it passes
+# whenever both move together, which is the shape of exactly that edit. The
+# sibling notice on _oversight_filter says the same thing for the same reason.
 #
-# This COARSENS the drift trigger to a coherent edit-set — the remedy ADR-090's
-# own Reassessment Criteria authorises — rather than dropping to write-once,
-# which ADR-090 explicitly forbids. Any map edit OTHER than adding the named
-# cards still drifts the hash, so the condition stays load-bearing.
-oversight_content_hash_excluding_stories() {
-  local f="$1"; shift
-  local filtered id
-  filtered="$(cat "$f")"
-  for id in "$@"; do
-    [ -n "$id" ] || continue
-    # 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
-  # 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}'
+# SCOPE: island keys only. Unlike oversight_excluded_keys, which strips keys from
+# every artefact in three encodings, this set is meaningless for anything with no
+# island — stories and pre-ADR-102 maps fall through to whole-file bytes. The two
+# are not complements; `excluded ∪ substance` is not the key space.
+#
+# THIS IS THE ONLY ENUMERATION. Six documents used to restate it (ADR-090,
+# ADR-103, ADR-105, capture-story-map, and manage-story-map twice) and by
+# 2026-08-08 it had drifted in both directions at once: the ADRs still named
+# `lead` and `traceProse`, dead the day before, while manage-story-map had lost
+# `storyMapId` and `secondaryPersona`, both live. The prose now states the rule
+# and points here — which is what the excluded-key set has always done, and it
+# has never drifted.
+#
+# Consumers DERIVE from this rather than restating it, the way the corpus lint
+# derives its pattern from oversight_excluded_keys. A consumer that hardcodes the
+# list starts a seventh enumeration.
+oversight_map_substance_keys() {
+  printf '%s\n' storyMapId title persona secondaryPersona traces backbone caption
 }
 
-# True (0) if this artefact's `confirmed` marker was written by the ADR-101 AFK
-# pure-decomposition carve-out rather than by a human ratification event.
-# BSD grep has no \s — use [[:space:]] (the P334 portability class).
-oversight_is_pure_decomposition() {
-  grep -qE '^oversight-basis:[[:space:]]*pure-decomposition([[:space:]]|$)' "$1" 2>/dev/null
+# Emit the bytes a fingerprint should cover.
+#
+# For a story map under ADR-102 that is the DATA ISLAND alone, not the whole
+# file: the grid, the <style> block and the <meta> block are all generated from
+# the island, so hashing the whole file would let a template change regenerate
+# every map, drift every stored fingerprint, and silently revoke ratification
+# across the corpus (ADR-090's marker is drift-invalidated). A presentation
+# change must never revoke a substance approval.
+#
+# Anything with no island — stories (.md), and maps predating ADR-102 — falls
+# through to whole-file bytes, so the story leg and the legacy corpus are
+# untouched.
+_oversight_hashable() {
+  local f="$1"
+  if grep -qF '<script id="story-map-data"' "$f" 2>/dev/null; then
+    # ADR-103: the fingerprint covers SUBSTANCE only — the map's identity and
+    # prose, its traces, and its backbone (the activity columns). Releases and
+    # the cards in them are SCHEDULING: drawing a row, or putting a story in
+    # one, is not a revision of what a human approved.
+    #
+    # This is what retires the ADR-101 carve-out. That existed because
+    # capturing a story onto its map drifted the map's hash, which broke the
+    # very condition the story had to satisfy. With cards outside the basis,
+    # the drift never happens and the carve-out has nothing to carve.
+    #
+    # NOT a sed range and not a JS reimplementation — see the awk note below
+    # and story-map-query.sh's header.
+    awk '
+      !inside && index($0, "<script id=\"story-map-data\"") { inside=1; next }
+      inside && index($0, "</script>") { exit }
+      inside { print }
+    ' "$f" | python3 -c '
+import json, sys
+try:
+    d = json.loads(sys.stdin.read().replace("\\u003c", "<"))
+except Exception:
+    sys.exit(0)          # unparseable island → empty basis, reads as drifted
+# Only keys PRESENT in the island are included, so a key listed here that no
+# map carries contributes nothing — which is why `lead` and `traceProse` could
+# be removed on 2026-08-08 without moving a single stored hash. They had left
+# the format the day before and were a live re-introduction vector: a field
+# nothing documents would still have been ratification-bearing.
+SUBSTANCE = ("storyMapId", "title", "persona", "secondaryPersona",
+             "traces", "backbone", "caption")
+print(json.dumps({k: d[k] for k in SUBSTANCE if k in d}, sort_keys=True, indent=2))
+'
+  else
+    cat "$f"
+  fi
 }
 
-# True (0) if the story DECLARES itself eligible for the ADR-101 carve-out.
-# Unlike `oversight-basis:` (marker-adjacent, excluded from the hash), this is an
-# AUTHORED claim and stays INSIDE the hash — editing it re-opens ratification,
-# and it cannot be stripped to hide the story from the post-hoc drain.
-oversight_declares_pure_decomposition() {
-  grep -qE '^afk-accept:[[:space:]]*pure-decomposition([[:space:]]|$)' "$1" 2>/dev/null
+oversight_content_hash() {
+  # Input path: bytes are 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_hashable "$1" | _oversight_filter | shasum -a 256 | awk '{print $1}'
 }
 
-# ADR-101 map leg. Satisfied when the map is fully ratified (card already present
-# at ratification time), OR when it is `confirmed` and its stored hash matches the
-# content hash with THIS story's card excluded (card added after ratification).
-oversight_map_leg_ok() {
-  local map="$1" story_id="$2"
-  is_story_map_ratified "$map" && return 0
-  oversight_is_confirmed "$map" || return 1
-  [ "$(oversight_stored_hash "$map")" = "$(oversight_content_hash_excluding_stories "$map" "$story_id")" ]
-}
+# ADR-103 retired the ADR-101 AFK pure-decomposition carve-out and its map leg.
+# The carve-out existed because ADR-095 compels a card onto the map at capture,
+# which under ADR-090 drift-invalidation re-opened the map's ratification by
+# construction — the condition a story had to satisfy was broken by authoring the
+# story. ADR-103 took cards out of the fingerprint basis entirely, so that no
+# longer happens and there is nothing left to exclude. Removed with it:
+# oversight_content_hash_excluding_stories, oversight_map_leg_ok,
+# oversight_is_pure_decomposition, oversight_declares_pure_decomposition.
 
-# Echo the stored oversight-hash (md frontmatter OR HTML meta), empty if none.
+# Echo the stored oversight-hash, empty if none. Three spellings carry the same
+# fact: md frontmatter, an HTML <meta>, and — for an ADR-102 map — the data
+# island, which is where mark-story-oversight-confirmed actually writes. The
+# island MUST be read here: the <meta> is a projection the renderer regenerates
+# from it, so a map marked but not yet re-rendered would otherwise read as
+# unratified the instant it was ratified.
 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)"
+  [ -z "$h" ] && h="$(grep -oE '"oversightHash"[[:space:]]*:[[:space:]]*"[a-f0-9]{64}"' "$1" 2>/dev/null | grep -oE '[a-f0-9]{64}' | head -1)"
   printf '%s' "$h"
 }
 
@@ -129,6 +171,8 @@ oversight_stored_hash() {
 oversight_is_confirmed() {
   grep -qiE '^human-oversight:[[:space:]]*confirmed([[:space:]]|$)' "$1" && return 0
   grep -qiE '<meta[^>]*name="human-oversight"[^>]*content="confirmed"' "$1" && return 0
+  # ADR-102 island spelling — see oversight_stored_hash for why this is load-bearing.
+  grep -qiE '"humanOversight"[[:space:]]*:[[:space:]]*"confirmed"' "$1" && return 0
   return 1
 }
 
@@ -142,3 +186,53 @@ is_story_map_ratified() {
   [ -z "$stored" ] && return 1
   [ "$stored" = "$(oversight_content_hash "$f")" ]
 }
+
+# Is this STORY approved? ADR-103 made the story map the approval surface, and a
+# story carries no oversight marker of its own — not even one saying it inherits.
+# A story is approved exactly when every map it names is ratified.
+#
+# Any `human-oversight:` line left on a story is legacy and is IGNORED here. It
+# is not consulted as a fallback: a story-level marker that could still approve a
+# story on an unratified map would keep alive the second approval surface this
+# decision removed, and the drain would never finish.
+#
+# A story naming no map is NOT approved — otherwise dropping the `story-maps:`
+# field would be a way to self-approve.
+story_is_approved() {
+  local story="$1" maps_root="${2:-docs/story-maps}" line ids id f found=0
+
+  # `story-maps:` in inline `[A, B]` or block `- A` form.
+  line="$(awk '/^story-maps:/{print; exit}' "$story")"
+  ids="$(printf '%s' "$line" | grep -oE 'STORY-MAP-[0-9]+' || true)"
+  [ -n "$ids" ] || ids="$(awk '/^story-maps:/{g=1;next} g&&/^[[:space:]]*-/{print} g&&/^[^[:space:]-]/{exit}' "$story" \
+    | grep -oE 'STORY-MAP-[0-9]+' || true)"
+
+  for id in $ids; do
+    # Exactly one file must match under a lifecycle directory. This USED to be
+    # `ls ... | head -1`, which arbitrary-picks when an id resolves in more than
+    # one of them — silently, and in the permissive direction: the one branch in
+    # this predicate that could grant an approval nobody gave. Which copy wins is
+    # just glob sort order, so whether it lands on the live map or a stale one is
+    # luck. An ambiguous id is a corpus defect; deny and let it surface.
+    #
+    # Known gap, pre-existing and unreachable today (no map sits at the top
+    # level of docs/story-maps/): the detector walks BOTH "$MAPS_DIR"/*.html and
+    # "$MAPS_DIR"/*/*.html, so a top-level map is visible to it but invisible
+    # here, and a story naming one would read unapproved forever.
+    #
+    # No `shopt nullglob` here on purpose. This function is sourced, so toggling
+    # it would mutate the CALLER's shell — and one caller
+    # (detect-unratified-stories-maps.sh) sets nullglob once at the top and
+    # relies on it for a later glob. The `-e` test does the same job locally: an
+    # unmatched glob stays literal, and a literal path does not exist.
+    local cand n=0 m=""
+    for cand in "$maps_root"/*/"${id}"-*.html; do
+      [ -e "$cand" ] || continue
+      n=$((n + 1)); m="$cand"
+    done
+    [ "$n" -eq 1 ] || return 1
+    is_story_map_ratified "$m" || return 1
+    found=1
+  done
+  [ "$found" = 1 ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.61.2",
+  "version": "1.0.0",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"
@@ -25,6 +25,7 @@
     "hooks/",
     "skills/",
     "scripts/",
+    "templates/",
     ".claude-plugin/",
     "lib/",
     "!skills/*/eval/",

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

@@ -1,10 +1,12 @@
 #!/usr/bin/env bash
-# check-rfc-stories-ratified.sh — ADR-090 (an RFC may reference only RATIFIED stories).
+# check-rfc-stories-ratified.sh — ADR-103 (an RFC may reference only APPROVED 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.
+# under <stories-root>/*/STORY-NNN-*.md and ask `story_is_approved`: is every map
+# in that story's `story-maps:` field ratified? A story carries no oversight
+# marker of its own (ADR-103), so the remedy for a failure is always to ratify
+# the MAP. Exit non-zero, with a stderr directive naming the offending stories,
+# if any listed story is unapproved 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
@@ -14,7 +16,7 @@
 # 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.
+# Authority: ADR-090, ADR-103. 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).
@@ -25,8 +27,9 @@ source "$LIB/story-oversight.sh"
 
 rfc="${1:-}"
 stories_root="${2:-docs/stories}"
+maps_root="${3:-docs/story-maps}"
 if [ -z "$rfc" ]; then
-  echo "check-rfc-stories-ratified: usage: check-rfc-stories-ratified.sh <rfc-file> [stories-root]" >&2
+  echo "check-rfc-stories-ratified: usage: check-rfc-stories-ratified.sh <rfc-file> [stories-root] [maps-root]" >&2
   exit 2
 fi
 if [ ! -f "$rfc" ]; then
@@ -51,13 +54,16 @@ for id in $ids; do
     unratified="$unratified $id(missing)"
     continue
   fi
-  if ! is_story_map_ratified "$f"; then
-    unratified="$unratified $id(unratified)"
+  # ADR-103: approval reaches a story through its map. Judging it by the story
+  # predicate alone would re-create the P456 deadlock one tier up — the RFC tier
+  # would block on a story ADR-103 approves.
+  if ! story_is_approved "$f" "$maps_root"; then
+    unratified="$unratified $id(unapproved)"
   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
+  echo "check-rfc-stories-ratified: $rfc references unapproved stories:$unratified — ADR-103: an RFC may reference only approved stories, and a story is approved by its story MAP. Ratify the map named in the story's story-maps: field via /wr-itil:manage-story-map <MAP-ID> ratify — a story carries no oversight marker of its own." >&2
   exit 1
 fi
 exit 0