@windyroad/itil 0.61.2 → 1.0.0

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

@@ -1,25 +1,21 @@
 #!/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:
+# Token-cheap detection of story maps that are NOT ratified, plus the stories
+# those maps leave unapproved. Mirrors wr-architect detect-unoversighted.sh.
+#
+# A MAP is ratified only when it carries a `confirmed` human-oversight marker AND
+# a stored oversight-hash matching its current substance, so three cases enter
+# the drain queue:
 #   - never ratified   (no marker)
-#   - drift-reopened   (marker says confirmed, but content changed → hash mismatch)
+#   - drift-reopened   (marker says confirmed, but substance changed → mismatch)
 #   - legacy confirmed  (confirmed but no fingerprint yet — needs one re-ratify)
 #
-# With `--with-afk-accepted` (ADR-101) it ALSO lists, on stderr, stories whose
-# `confirmed` marker was machine-written by the AFK pure-decomposition carve-out
-# rather than by a human — they are awaiting post-hoc human ratification. The
-# listing keys on the UNION of `afk-accept:` and `oversight-basis:`, because the
-# latter is excluded from the content hash and could otherwise be stripped to
-# hide a machine-accepted story from this drain; `afk-accept:` stays in the hash.
-# stdout is untouched by the flag, so the Step 2.4 drain consumer is unaffected.
+# A STORY carries no marker at all (ADR-103). It is listed when any map in its
+# `story-maps:` field is unratified, or when it names no map — and the remedy is
+# always to ratify the map, never the story.
 #
-# Usage: detect-unratified-stories-maps.sh [--with-afk-accepted] [STORIES_DIR=docs/stories] [MAPS_DIR=docs/story-maps]
+# 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.
@@ -31,12 +27,6 @@ LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
 # shellcheck source=/dev/null
 source "$LIB/story-oversight.sh"
 
-WITH_AFK=0
-if [ "${1:-}" = "--with-afk-accepted" ]; then
-  WITH_AFK=1
-  shift
-fi
-
 STORIES_DIR="${1:-docs/stories}"
 MAPS_DIR="${2:-docs/story-maps}"
 
@@ -46,7 +36,10 @@ 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"
+      # ADR-103: a story's approval may be its MAP's. Using the map predicate
+      # here would report every story as unratified — stories carry no marker at
+      # all — and send the drain to ratify a surface ADR-103 removed.
+      story_is_approved "$f" "$MAPS_DIR" || echo "$f"
     done
   fi
   if [ -d "$MAPS_DIR" ]; then
@@ -56,14 +49,4 @@ shopt -s nullglob
   fi
 } | sort
 
-# ADR-101 post-hoc drain — stderr only, so the stdout path contract is preserved.
-if [ "$WITH_AFK" = "1" ] && [ -d "$STORIES_DIR" ]; then
-  for f in "$STORIES_DIR"/*.md "$STORIES_DIR"/*/*.md; do
-    [ "$(basename "$f")" = "README.md" ] && continue
-    if oversight_declares_pure_decomposition "$f" || oversight_is_pure_decomposition "$f"; then
-      echo "AFK-ACCEPTED (awaiting post-hoc human ratification): $f" >&2
-    fi
-  done
-fi
-
 exit 0

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

@@ -8,19 +8,15 @@
 # stored fingerprint no longer matches → the artefact reads as drifted /
 # unratified until re-ratified (ADR-090 drift-invalidation).
 #
-# With `--pure-decomposition` (ADR-101) it additionally records
-# `oversight-basis: pure-decomposition` — the marker was written by an AFK loop
-# under the carve-out, not by a human ratification event. That field is
-# markdown-story-only (a map is always human-ratified and never carries a
-# decomposition basis) and is EXCLUDED from the content hash, exactly like
-# `oversight-hash`; the authored `afk-accept:` declaration stays INSIDE the hash.
-# Without the flag the basis line is dropped, so re-ratifying by hand clears a
-# stale basis rather than leaving a human-ratified story labelled AFK-accepted.
+# ADR-103 retired the ADR-101 `--pure-decomposition` flag and its
+# `oversight-basis:` record. Nothing here strips a stale one: the only writer
+# that did was the markdown leg, and markdown is a story, which is now refused
+# outright. No artefact in the corpus carries the field.
 #
-# Usage: mark-story-oversight-confirmed.sh [--pure-decomposition] <story-or-map-file>
+# Usage: mark-story-oversight-confirmed.sh <story-or-map-file>
 # Exit:  0 = ratified; 2 = usage / file error.
 #
-# Authority: ADR-090, ADR-101. Driver: P404 Phase 2, P456. Test: mark-story-oversight-confirmed.bats.
+# Authority: ADR-090, ADR-103. Driver: P404 Phase 2, P456. Test: mark-story-oversight-confirmed.bats.
 set -euo pipefail
 
 # Adopter-safe: source the shared hash lib RELATIVE TO THIS SCRIPT (P317), never
@@ -30,25 +26,85 @@ LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
 # shellcheck source=/dev/null
 source "$LIB/story-oversight.sh"
 
-basis=""
-if [ "${1:-}" = "--pure-decomposition" ]; then
-  basis="pure-decomposition"
-  shift
-fi
-
 f="${1:-}"
 if [ -z "$f" ]; then
-  echo "mark-story-oversight-confirmed: usage: mark-story-oversight-confirmed.sh [--pure-decomposition] <file>" >&2
+  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; }
 
+# ADR-103: only a story MAP is ratified. A story carries no oversight marker at
+# all — its approval is its map's. Marking a story would re-create the second
+# approval surface ADR-103 removed, so refuse rather than silently write one.
+# What ADR-103 removes is the STORY-tier marker, and a story is markdown. So the
+# refusal is keyed on the encoding, not on a `docs/stories/` path substring: a
+# caller working outside that tree — a test fixture, an adopter with a different
+# layout — must get the same answer.
+#
+# Deliberately NOT keyed on the ADR-102 data island, tempting as that is. A map
+# predating ADR-102 has no island, and an island test would lock those out of
+# ratification entirely. Marking some unrelated .html file is a user error; a
+# story marker is a governance hole, and only the second one is worth refusing.
+case "$f" in
+  *.md|*.markdown)
+    echo "mark-story-oversight-confirmed: refusing to mark $f (ADR-103). Only a story MAP is ratified. A story carries no oversight marker; its approval is derived from the maps named in its \`story-maps:\` field, so ratify the map instead." >&2
+    exit 2 ;;
+esac
+
 h="$(oversight_content_hash "$f")"
 tmp="$(mktemp)"
 
 case "$f" in
   *.html)
-    if grep -qi '<head' "$f"; then
+    if grep -qF '<script id="story-map-data"' "$f"; then
+      # ADR-102 map: the data island is the source of truth and every <meta> is
+      # GENERATED from it. Writing the marker to <meta> alone would be undone by
+      # the next render, silently destroying a human ratification — so the
+      # marker goes into the island and the <meta> follows on render.
+      #
+      # TWO passes, and the order matters. Normalising the island can move a
+      # trailing comma onto a line the marker filter does NOT exclude (removing
+      # a previously-appended key un-commas the key before it), which would
+      # change the very bytes being fingerprinted. So: normalise first, hash the
+      # normalised form, then write the hash — a marker-line-only edit, which
+      # the filter excludes, so the stored value stays valid.
+      _island_normalise() {
+        python3 - "$1" "$2" <<'PYMARK'
+import json, pathlib, sys
+path, digest = pathlib.Path(sys.argv[1]), sys.argv[2]
+OPEN = '<script id="story-map-data" type="application/json">'
+html = path.read_text()
+start = html.index(OPEN) + len(OPEN)
+end = html.index('</script>', start)
+data = json.loads(html[start:end].replace('\\u003c', '<'))
+# Marker keys FIRST, never appended: appending gives the previously-last key a
+# trailing comma, a punctuation-only change on an unfiltered line.
+MARKERS = ('humanOversight', 'oversightHash', 'oversightDate', 'oversightNote')
+ordered = {'humanOversight': 'confirmed', 'oversightHash': digest}
+for k in ('oversightDate', 'oversightNote'):
+    if k in data:
+        ordered[k] = data[k]
+ordered.update({k: v for k, v in data.items() if k not in MARKERS})
+island = json.dumps(ordered, indent=2, ensure_ascii=False).replace('<', '\\u003c')
+path.write_text(html[:start] + "\n" + island + "\n  " + html[end:])
+PYMARK
+      }
+      _island_normalise "$f" "pending"
+      h="$(oversight_content_hash "$f")"
+      _island_normalise "$f" "$h"
+      # Re-render so the generated <meta> block matches the island. Prefer the
+      # sibling script over $PATH: this runs from the same package, so the
+      # renderer is always beside it even when the bin shim is not on PATH.
+      _renderer="$(cd "$(dirname "$0")" && pwd)/render-story-map.sh"
+      if [ -x "$_renderer" ]; then
+        "$_renderer" "$f" >/dev/null 2>&1 || true
+      elif command -v wr-itil-render-story-map >/dev/null 2>&1; then
+        wr-itil-render-story-map "$f" >/dev/null 2>&1 || true
+      fi
+      printf 'mark-story-oversight-confirmed: ratified %s (oversight-hash %s…)\n' "$f" "${h:0:12}" >&2
+      rm -f "$tmp"
+      exit 0
+    elif 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 }
@@ -67,19 +123,12 @@ case "$f" in
     fi
     ;;
   *)
-    # Markdown: rewrite frontmatter — drop existing markers, insert both before
-    # the closing `---`.
-    awk -v H="$h" -v B="$basis" '
-      NR==1 && $0=="---" { infm=1; print; next }
-      infm && /^(human-oversight|oversight-hash|oversight-basis):/ { next }
-      infm && /^---[[:space:]]*$/ && !done {
-        print "human-oversight: confirmed"
-        print "oversight-hash: " H
-        if (B != "") print "oversight-basis: " B
-        print; done=1; infm=0; next
-      }
-      { print }
-    ' "$f" > "$tmp"
+    # The markdown-frontmatter writer that used to live here was a working
+    # writer for the story-level marker ADR-103 removed. It is deleted rather
+    # than left unreachable behind the guard above, so that a later relaxation
+    # of that guard fails loudly instead of silently restoring story markers.
+    echo "mark-story-oversight-confirmed: refusing to mark $f (ADR-103) — no recognised story-map encoding (expected a <script id=\"story-map-data\"> island, or a legacy HTML map)." >&2
+    rm -f "$tmp"; exit 2
     ;;
 esac
 

package/scripts/migrate-story-status-mirror.sh

@@ -40,7 +40,7 @@
 # Usage: migrate-story-status-mirror.sh [<stories-dir>...]   (default: docs/stories)
 # Exit:  0 = completed (including "nothing to do"); 2 = usage / missing lib.
 #
-# Authority: ADR-090 (oversight fingerprint), ADR-101 (oversight-basis).
+# Authority: ADR-090 (oversight fingerprint), ADR-103 (stories carry no marker).
 # Driver: P474. Test: migrate-story-status-mirror.bats.
 
 set -euo pipefail
@@ -105,8 +105,12 @@ for d in "${dirs[@]}"; do
 
     # Was this artefact ratified-and-valid BEFORE we touch it? Decide now: once
     # the line is gone the pre-migration hash is unreproducible.
+    #
+    # ADR-103: a story carries no fingerprint of its own, so this is always 0 on
+    # the story tier and the re-point branch below never runs there. The branch
+    # is retained for any artefact that does carry one.
     was_valid=0
-    if is_story_map_ratified "$f"; then was_valid=1; fi
+    if [ -n "$(oversight_stored_hash "$f")" ] && is_story_map_ratified "$f"; then was_valid=1; fi
 
     # Drop the FIRST matching mirror line and nothing else — surrounding blank
     # lines are left exactly as they are. The template puts the mirror in a run
@@ -132,7 +136,7 @@ for d in "${dirs[@]}"; do
       refingerprinted=$((refingerprinted + 1))
       printf 'MIGRATE %s — mirror removed, fingerprint re-pointed (ratification preserved)\n' "$f"
     else
-      printf 'MIGRATE %s — mirror removed (was not ratified-and-valid; left unratified)\n' "$f"
+      printf 'MIGRATE %s — mirror removed (no fingerprint of its own to re-point)\n' "$f"
     fi
     # STORY-*.md only. `README.md` documents the template and legitimately
     # contains a `**Status**: <status>` example; scanning it would report a

package/scripts/reconcile-stories.sh

@@ -7,13 +7,14 @@
 # Story Rankings + Done tables, and reports each disagreement.
 #
 # Usage:
-#   reconcile-stories.sh [<stories-dir> [<problems-dir> [<rfcs-dir> [<jtbd-dir>]]]]
+#   reconcile-stories.sh [<stories-dir> [<problems-dir> [<rfcs-dir> [<jtbd-dir> [<story-maps-dir>]]]]]
 #
 # Defaults:
 #   <stories-dir>   = ./docs/stories
 #   <problems-dir>  = ./docs/problems (when supplied + on disk; reverse trace)
 #   <rfcs-dir>      = ./docs/rfcs (when supplied + on disk; reverse trace)
 #   <jtbd-dir>      = ./docs/jtbd (when supplied + on disk; reverse trace)
+#   <story-maps-dir> = ./docs/story-maps (row-backed RFC resolution)
 #
 # Exit codes:
 #   0 = clean (README matches filesystem)
@@ -71,10 +72,12 @@
 
 set -uo pipefail
 
+HERE="$(cd "$(dirname "$0")" && pwd)"
 STORIES_DIR="${1:-docs/stories}"
 PROBLEMS_DIR="${2:-$(dirname "$STORIES_DIR")/problems}"
 RFCS_DIR="${3:-$(dirname "$STORIES_DIR")/rfcs}"
 JTBD_DIR="${4:-$(dirname "$STORIES_DIR")/jtbd}"
+MAPS_DIR="${5:-$(dirname "$STORIES_DIR")/story-maps}"
 README="${STORIES_DIR}/README.md"
 
 # ── Pre-checks ──────────────────────────────────────────────────────────────
@@ -183,6 +186,8 @@ done
 
 reverse_trace_pass() {
   local parent_dir="$1" parent_kind="$2" parent_id_pattern="$3"
+  local -a matches=()
+  local pfile row_json
   [ ! -d "$parent_dir" ] && return 0
 
   shopt -s nullglob globstar
@@ -198,19 +203,35 @@ reverse_trace_pass() {
     parent_claims=$(awk -v k="^${parent_kind}:" '$0 ~ k {gsub(/[][]/,""); gsub(/,/," "); for(i=2;i<=NF;i++)print $i; exit}' "$sf")
     for pid in $parent_claims; do
       # Resolve parent file under parent_dir
+      matches=()
       case "$parent_kind" in
         problems)
           pnum="${pid#P}"
-          pfile=$(ls "$parent_dir"/${pnum}-*.md "$parent_dir"/*/${pnum}-*.md 2>/dev/null | head -1)
+          matches=("$parent_dir"/${pnum}-*.md "$parent_dir"/*/${pnum}-*.md)
           ;;
         rfcs)
-          pfile=$(ls "$parent_dir"/${pid}-*.md 2>/dev/null | head -1)
+          matches=("$parent_dir"/${pid}-*.md)
           ;;
         jtbd)
-          pfile=$(ls "$parent_dir"/*/${pid}-*.md 2>/dev/null | head -1)
+          matches=("$parent_dir"/*/${pid}-*.md)
           ;;
-        *) pfile="" ;;
+        *) matches=() ;;
       esac
+      pfile="${matches[0]:-}"
+
+      # ADR-103: a release row may be the RFC, so no markdown parent exists.
+      # In that case the map row itself is the reverse trace and must contain
+      # this story. Query the canonical map island rather than scraping HTML.
+      if [ "$parent_kind" = rfcs ] && [ -z "$pfile" ]; then
+        row_json=$("$HERE/story-map-query.sh" find-rfc "$pid" --maps-dir "$MAPS_DIR" 2>/dev/null || true)
+        if [ -z "$row_json" ] || [ "$row_json" = "[]" ]; then
+          DRIFT_LINES+=("UNRESOLVED_RFC_TRACE ${sid} claims=${pid}")
+        elif ! grep -qF "\"${sid}\"" <<< "$row_json"; then
+          DRIFT_LINES+=("MISSING_REVERSE_TRACE ${sid} in ${pid} release row")
+        fi
+        continue
+      fi
+
       [ -z "$pfile" ] && continue
 
       # Check parent's ## Stories section contains this story's ID