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

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.56.0-preview.877",
+  "version": "0.56.0-preview.879",
   "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,57 @@
+#!/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
+
+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 ! grep -qE '^human-oversight:[[:space:]]*confirmed([[:space:]]|$)' "$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,44 @@
+#!/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.
+#
+# 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.
+# Always exits 0 (detector, not a gate). Consumed by the work-problems Step 2.4
+# oversight-unconfirmed drain (mirror of the architect/jtbd detectors).
+set -euo pipefail
+
+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"
+    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"
+    done
+  fi
+} | sort
+
+exit 0

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

@@ -0,0 +1,70 @@
+#!/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.
+#
+# @adr ADR-090 (story maps and stories carry a drift-invalidated human-oversight marker)
+# @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"
+  TMPD="$(mktemp -d)"
+  mkdir -p "$TMPD/stories/accepted"
+}
+teardown() { rm -rf "$TMPD"; }
+
+mkstory() { # $1=id $2=oversight-value(or "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"
+}
+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 confirmed 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)" {
+  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 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 confirmed 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,50 @@
+#!/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.
+#
+# @adr ADR-090 (drift-invalidated story-map/story human-oversight marker)
+# @problem P404 (implement ADR-089 + ADR-090) — Phase 2
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="${REPO_ROOT}/packages/itil/scripts/detect-unratified-stories-maps.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"
+  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"
+}
+teardown() { rm -rf "$TMPD"; }
+
+@test "detect: lists unconfirmed + unmarked, omits confirmed; exits 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-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" {
+  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"
+  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/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. |