@windyroad/itil 2.4.2-preview.1239 → 2.4.2-preview.1241

package/lib/story-oversight.sh

@@ -204,39 +204,61 @@ is_story_map_ratified() {
 #
 # 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.
+# The map ids a story DECLARES, one per line, empty output when it declares
+# none. Both frontmatter forms — inline `story-maps: [A, B]` and a block list of
+# `- A` continuation lines — are read here and nowhere else. A consumer that
+# wants to tell "declares no map" apart from "declares a map that is not
+# ratified" needs the ids, not just the verdict; parsing them again at the call
+# site would start the second enumeration this lib's header warns about, and a
+# copy covering only the inline form would silently file every block-form story
+# under "no map".
+story_declared_maps() {
+  local story="$1" line ids
   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)"
+  [ -n "$ids" ] && printf '%s\n' $ids
+  return 0
+}
+
+# Echo the ONE map file an id resolves to; non-zero when it resolves to zero
+# files or to more than one.
+#
+# Exactly one, never first-match. This USED to be `ls ... | head -1`, which
+# arbitrary-picks when an id resolves in more than one lifecycle directory —
+# silently, and in the permissive direction: the one branch in the approval
+# 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.
+story_map_file() {
+  local id="$1" maps_root="${2:-docs/story-maps}" 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
+  printf '%s' "$m"
+}
+
+story_is_approved() {
+  local story="$1" maps_root="${2:-docs/story-maps}" ids id m found=0
+
+  ids="$(story_declared_maps "$story")"
 
   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
+    m="$(story_map_file "$id" "$maps_root")" || return 1
     is_story_map_ratified "$m" || return 1
     found=1
   done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "2.4.2-preview.1239",
+  "version": "2.4.2-preview.1241",
   "description": "ITIL-aligned IT service management for Claude Code and Codex",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"
@@ -43,7 +43,6 @@
     "!hooks/test/",
     "!lib/test/",
     "!scripts/test/",
-    "!scripts/check-published-internal-ids.sh",
     "!scripts/codex-work-problems.md",
     "!scripts/sync-codex-skills.mjs",
     "!skills/*/test/"

package/scripts/reconcile-stories.sh

@@ -37,12 +37,33 @@
 #     Story's frontmatter claims <PARENT-ID> but parent's ## Stories
 #     table does not list STORY-<NNN>. Skill-side refresh contract
 #     was missed.
-#   STALE_REVERSE_TRACE    STORY-<NNN> in <PARENT-ID> ## Stories
-#     Parent's ## Stories lists STORY-<NNN> but the story frontmatter
-#     no longer claims this parent. Re-trace bookkeeping was missed.
-#   STATUS_MISMATCH        STORY-<NNN> in <PARENT-ID> ## Stories claims=<X> actual=<Y>
-#     Parent's ## Stories row claims story status <X> but story's
-#     filesystem subdir is <Y>. Status-column refresh contract was missed.
+#
+# WHICH POPULATION THE RFC LEG COVERS (reconcile-stories-reports-permanent-false-missing-reverse-trace-drift-against-s-ratified-stories-only-rule-problem / a-clean-reconciler-result-means-the-tier-really-is-clean-delivery-story). On the problems
+# and jtbd legs every story that names the parent is checked. On the rfcs leg
+# only APPROVED stories are, because story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule as amended by a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule forbids an
+# RFC from referencing a story whose story map is not ratified: for such a
+# story the `## Stories` row is CORRECTLY absent, and demanding it reported
+# correct work as drift — a finding no compliant action could ever clear,
+# since satisfying it meant breaking the rule it existed to protect.
+#
+# Approval reaches a story through its MAP (a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule), so `story_is_approved`
+# is the predicate. A `human-oversight:` field left on a story file is legacy
+# and is deliberately ignored; reading one would revive the second approval
+# surface a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule deleted.
+#
+# The release-row leg below is NOT gated. story-map-membership-and-story-content-completeness-are-enforced-at-capture-architecture-rule compels a story card onto
+# the map at capture and a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule took cards out of the fingerprint basis, so
+# a card's absence from its row is never correct.
+#
+# Every run of the rfcs leg says on STDERR how many pairs it checked and how
+# many it skipped, split by reason, so a reader of an exit-0 clean result can
+# tell "checked and clean" from "skipped because out of scope". Two of the
+# three skip reasons are corpus defects, not correct absences, and are
+# counted apart: a story that names NO map (story-map-membership-and-story-content-completeness-are-enforced-at-capture-architecture-rule), and a story naming a
+# map id that resolves to zero or to several files. Folding either into the
+# correct-absence bucket would be this ticket's own failure in the other
+# direction. STDOUT stays drift-lines-only — /wr-itil:reconcile-stories
+# redirects it to a file and parses it line by line.
 #
 # Read-only — does NOT mutate the README. The /wr-itil:manage-story skill
 # (problem-tickets-strain-as-fixes-decompose-into-multiple-coordinated-changes-need-an-rfc-framework-that-ties-all-changes-back-to-problems-and-unifies-technical-with-user-business-problems-problem Phase 2 Slice 8) applies edits with narrative-aware preservation;
@@ -73,6 +94,16 @@
 set -uo pipefail
 
 HERE="$(cd "$(dirname "$0")" && pwd)"
+
+# Adopter-safe: source the shared lazy-fingerprint lib RELATIVE TO THIS SCRIPT
+# (capture-problem-capture-rfc-manage-problem-step-2-create-gate-marker-step-sources-repo-relative-packages-itil-hooks-lib-sh-fails-in-adopter-installs-recurring-published-path-class-problem), matching check-rfc-stories-ratified.sh. `story_is_approved` and its
+# two accessors are the ONE definition of story ratification; this script adds
+# no second one.
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
+  echo "reconcile-stories: cannot locate lib dir" >&2; exit 2; }
+# shellcheck source=../lib/story-oversight.sh
+source "$LIB/story-oversight.sh"
+
 STORIES_DIR="${1:-docs/stories}"
 PROBLEMS_DIR="${2:-$(dirname "$STORIES_DIR")/problems}"
 RFCS_DIR="${3:-$(dirname "$STORIES_DIR")/rfcs}"
@@ -184,6 +215,42 @@ done
 
 # ── Reverse-trace pass — story frontmatter ↔ parent ## Stories section ─────
 
+# RFC-leg population accounting. Counted per (story, markdown-RFC) pair.
+RFC_MD_CHECKED=0
+RFC_MD_SKIP_UNRATIFIED=0
+RFC_MD_SKIP_NO_MAP=0
+RFC_MD_SKIP_UNRESOLVED_MAP=0
+declare -A MAP_RATIFIED_MEMO
+
+# Classify a story for the story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule RFC-markdown rule. Sets RFC_MD_BUCKET to one
+# of: approved | unratified | no-map | unresolved-map.
+#
+# Sets a global rather than echoing so the memo survives: a $(...) call runs in a
+# subshell and every MAP_RATIFIED_MEMO write inside one is discarded, which would
+# re-hash the same handful of maps once per claim.
+#
+# `story_is_approved` is false for three different reasons and only ONE of them
+# is a correct absence, so this asks the lib's accessors directly instead of
+# taking the verdict alone.
+_rfc_md_bucket() {
+  local sf="$1" ids id m verdict
+  RFC_MD_BUCKET=approved
+  ids="$(story_declared_maps "$sf")"
+  if [ -z "$ids" ]; then RFC_MD_BUCKET=no-map; return 0; fi
+  for id in $ids; do
+    if ! m="$(story_map_file "$id" "$MAPS_DIR")"; then
+      RFC_MD_BUCKET=unresolved-map; return 0
+    fi
+    verdict="${MAP_RATIFIED_MEMO[$m]:-}"
+    if [ -z "$verdict" ]; then
+      if is_story_map_ratified "$m"; then verdict=yes; else verdict=no; fi
+      MAP_RATIFIED_MEMO["$m"]="$verdict"
+    fi
+    if [ "$verdict" != yes ]; then RFC_MD_BUCKET=unratified; return 0; fi
+  done
+  return 0
+}
+
 reverse_trace_pass() {
   local parent_dir="$1" parent_kind="$2" parent_id_pattern="$3"
   local -a matches=()
@@ -234,6 +301,20 @@ reverse_trace_pass() {
 
       [ -z "$pfile" ] && continue
 
+      # story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule / a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule: an RFC references only approved stories, so an
+      # unapproved story's absence from this section is correct, not drift.
+      # Only the markdown-RFC leg is narrowed — the release-row branch above
+      # has already returned.
+      if [ "$parent_kind" = rfcs ]; then
+        _rfc_md_bucket "$sf"
+        case "$RFC_MD_BUCKET" in
+          approved)       RFC_MD_CHECKED=$((RFC_MD_CHECKED + 1)) ;;
+          unratified)     RFC_MD_SKIP_UNRATIFIED=$((RFC_MD_SKIP_UNRATIFIED + 1)); continue ;;
+          no-map)         RFC_MD_SKIP_NO_MAP=$((RFC_MD_SKIP_NO_MAP + 1)); continue ;;
+          unresolved-map) RFC_MD_SKIP_UNRESOLVED_MAP=$((RFC_MD_SKIP_UNRESOLVED_MAP + 1)); continue ;;
+        esac
+      fi
+
       # Check parent's ## Stories section contains this story's ID
       if ! awk '/^## Stories/{flag=1; next} /^## /{flag=0} flag{print}' "$pfile" | grep -qF "$sid"; then
         DRIFT_LINES+=("MISSING_REVERSE_TRACE ${sid} in ${pid} ## Stories")
@@ -247,6 +328,24 @@ reverse_trace_pass "$PROBLEMS_DIR" "problems" "P[0-9]{3}"
 reverse_trace_pass "$RFCS_DIR" "rfcs" "RFC-[0-9]{3}"
 reverse_trace_pass "$JTBD_DIR" "jtbd" "JTBD-[0-9]{3}"
 
+# ── Say which population the RFC leg checked ────────────────────────────────
+#
+# On stderr, so stdout stays drift-lines-only for the skill's line-by-line
+# parse. Printed whether or not there is drift: a clean result that never says
+# what it covered is the same defect this leg was narrowed to fix. Skip lines
+# are suppressed at zero — the checked-of-total line already carries that.
+
+if [ -d "$RFCS_DIR" ]; then
+  rfc_md_total=$(( RFC_MD_CHECKED + RFC_MD_SKIP_UNRATIFIED + RFC_MD_SKIP_NO_MAP + RFC_MD_SKIP_UNRESOLVED_MAP ))
+  echo "reconcile-stories: RFC ## Stories reverse trace checked ${RFC_MD_CHECKED} of ${rfc_md_total} story/RFC pairs." >&2
+  [ "$RFC_MD_SKIP_UNRATIFIED" -gt 0 ] && \
+    echo "reconcile-stories:   ${RFC_MD_SKIP_UNRATIFIED} skipped because the story's map is not ratified, so the row is correctly absent." >&2
+  [ "$RFC_MD_SKIP_NO_MAP" -gt 0 ] && \
+    echo "reconcile-stories:   ${RFC_MD_SKIP_NO_MAP} skipped because the story names no story map at all; that is a corpus defect, not a correct absence." >&2
+  [ "$RFC_MD_SKIP_UNRESOLVED_MAP" -gt 0 ] && \
+    echo "reconcile-stories:   ${RFC_MD_SKIP_UNRESOLVED_MAP} skipped because the story names a map id that does not resolve to exactly one file; also a corpus defect." >&2
+fi
+
 # ── Emit ─────────────────────────────────────────────────────────────────────
 
 if [ ${#DRIFT_LINES[@]} -eq 0 ]; then

package/scripts/update-rfc-references-section.sh

@@ -5,12 +5,35 @@
 # update-problem-references-section.sh with the lookup table tuned for
 # RFC-on-RFC reverse traces:
 #   - ## Story Maps : sources docs/story-maps/*/*.html via data attributes
-#   - ## Stories    : forward-trace from RFC's own frontmatter `stories:`
+#   - ## Stories    : sources docs/stories/*/STORY-*.md by each story's `rfcs:`
 #
 # Per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule § Phase 2 encoding amendment 2026-05-12 architect finding 4:
-# no per-section-name branching in body; lookup-table-driven dispatch.
+# no per-section-name branching in body; lookup-table-driven dispatch. The
+# approval gate below rides that table rather than a branch, for the same
+# reason.
 #
-# Usage: update-rfc-references-section.sh <rfc-file> <section-name>
+# APPROVAL GATE ON `## Stories` (reconcile-stories-reports-permanent-false-missing-reverse-trace-drift-against-s-ratified-stories-only-rule-problem / a-clean-reconciler-result-means-the-tier-really-is-clean-delivery-story). story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule as amended by
+# a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule forbids an RFC from referencing a story whose story map is not
+# ratified. This helper regenerates the WHOLE section from a reverse index over
+# every story claiming the RFC, and it is the prescribed repair for a
+# MISSING_REVERSE_TRACE finding — so ungated, repairing one legitimate finding
+# swept every unapproved sibling in with it, writing exactly the reference the
+# rule forbids. The narrowed detector in reconcile-stories.sh would then report
+# clean over it: a loud false positive traded for a silent true negative, which
+# is strictly worse. A withheld story is named on stderr, because a section
+# that silently shrinks is its own kind of unreadable.
+#
+# KNOWN DIVERGENCE, recorded on reconcile-stories-reports-permanent-false-missing-reverse-trace-drift-against-s-ratified-stories-only-rule-problem and deliberately not fixed here. problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule
+# line 288 and this header used to say `## Stories` is a FORWARD trace
+# projecting the RFC's own `stories:` array. The implementation has always
+# reverse-indexed story frontmatter instead. Projecting `stories:` was
+# considered: a corpus audit found 8 of 23 approved (story → markdown-RFC)
+# claims present in the RFC's `## Stories` but absent from its `stories:`, so
+# the projection would drop those rows and the reconciler would report
+# MISSING_REVERSE_TRACE on them with no mechanical repair — reconcile-stories-reports-permanent-false-missing-reverse-trace-drift-against-s-ratified-stories-only-rule-problem re-created in
+# the other direction. The header now states what the code does.
+#
+# Usage: update-rfc-references-section.sh <rfc-file> <section-name> [<story-maps-dir>]
 #
 # @adr problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule (Phase 2 encoding amendment 2026-05-12)
 # @problem problem-tickets-strain-as-fixes-decompose-into-multiple-coordinated-changes-need-an-rfc-framework-that-ties-all-changes-back-to-problems-and-unifies-technical-with-user-business-problems-problem (Phase 2 Slice 2b)
@@ -19,6 +42,14 @@ set -uo pipefail
 
 RFC_FILE="${1:-}"
 SECTION_NAME="${2:-}"
+MAPS_DIR="${3:-docs/story-maps}"
+
+# Adopter-safe: source the shared ratification lib RELATIVE TO THIS SCRIPT
+# (capture-problem-capture-rfc-manage-problem-step-2-create-gate-marker-step-sources-repo-relative-packages-itil-hooks-lib-sh-fails-in-adopter-installs-recurring-published-path-class-problem), matching check-rfc-stories-ratified.sh.
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
+  echo "ERROR: cannot locate lib dir" >&2; exit 1; }
+# shellcheck source=../lib/story-oversight.sh
+source "$LIB/story-oversight.sh"
 
 if [ -z "$RFC_FILE" ]; then
   echo "ERROR: missing rfc-file argument" >&2
@@ -33,19 +64,26 @@ if [ ! -f "$RFC_FILE" ]; then
   exit 1
 fi
 
-declare -A SECTION_GLOB SECTION_MODE SECTION_ID_PATTERN
+declare -A SECTION_GLOB SECTION_MODE SECTION_ID_PATTERN SECTION_ADMIT
+
+# A story is APPROVED when every story map it names is ratified (a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule). Any
+# `human-oversight:` field left on the story file is legacy and is ignored.
+admit_if_story_approved() { story_is_approved "$1" "$MAPS_DIR"; }
 
 SECTION_GLOB["Story Maps"]="docs/story-maps/*/STORY-MAP-*.html"
 SECTION_MODE["Story Maps"]="html-data-attribute-rfc"
 SECTION_ID_PATTERN["Story Maps"]="STORY-MAP-[0-9]+"
+SECTION_ADMIT["Story Maps"]=""
 
 SECTION_GLOB["Stories"]="docs/stories/*/STORY-*.md"
 SECTION_MODE["Stories"]="markdown-frontmatter-rfc"
 SECTION_ID_PATTERN["Stories"]="STORY-[0-9]+"
+SECTION_ADMIT["Stories"]="admit_if_story_approved"
 
 glob_pattern="${SECTION_GLOB[$SECTION_NAME]:-}"
 extraction_mode="${SECTION_MODE[$SECTION_NAME]:-}"
 id_pattern="${SECTION_ID_PATTERN[$SECTION_NAME]:-}"
+admit_filter="${SECTION_ADMIT[$SECTION_NAME]:-}"
 
 if [ -z "$glob_pattern" ]; then
   echo "ERROR: unknown section-name '$SECTION_NAME'. Supported: Story Maps, Stories" >&2
@@ -60,7 +98,7 @@ if [ -z "$rfc_id" ]; then
   exit 1
 fi
 
-declare -a matched_ids=() matched_titles=() matched_statuses=()
+declare -a matched_ids=() matched_titles=() matched_statuses=() withheld_ids=()
 
 extract_from_html_rfcs_meta() {
   local file="$1"
@@ -107,6 +145,10 @@ for artefact in $glob_pattern; do
   if "$extract_match" "$artefact"; then
     aid=$(extract_id_from_filename "$artefact")
     [ -n "$aid" ] || continue
+    if [ -n "$admit_filter" ] && ! "$admit_filter" "$artefact"; then
+      withheld_ids+=("$aid")
+      continue
+    fi
     matched_ids+=("$aid")
     matched_titles+=("$("$extract_title" "$artefact" 2>/dev/null || echo "")")
     matched_statuses+=("$("$extract_status" "$artefact" 2>/dev/null || echo "unknown")")
@@ -114,6 +156,10 @@ for artefact in $glob_pattern; do
 done
 shopt -u nullglob
 
+if [ ${#withheld_ids[@]} -gt 0 ]; then
+  echo "update-rfc-references-section: withheld from ${rfc_id} ## ${SECTION_NAME}: ${withheld_ids[*]} — each names a story map that is not ratified, and an RFC references only approved stories. To list one, ratify its map; never hand-add the row." >&2
+fi
+
 new_section=""
 if [ ${#matched_ids[@]} -gt 0 ]; then
   new_section="## ${SECTION_NAME}"$'\n\n| ID | Title | Status |\n|----|-------|--------|\n'

package/skills/reconcile-stories/SKILL.md

@@ -12,11 +12,21 @@ Sibling to `/wr-itil:reconcile-readme` (the "`docs/problems/README.md` drifts fr
 
 **Reverse-trace pass** — when the parent directories exist, the reconciler checks auto-maintained `## Stories` sections on problem, JTBD and legacy RFC files. For an the "A release row is the RFC, and the map is the approval surface" architecture rule row-backed RFC, it checks the map row instead: the RFC must resolve and the row must contain the story card.
 - `MISSING_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — story claims parent but parent's `## Stories` table doesn't list the story
-- `STALE_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — parent lists the story but story no longer claims the parent
-- `STATUS_MISMATCH STORY-NNN in <PARENT-ID> ## Stories claims=<X> actual=<Y>` — parent's row claims one lifecycle status; story's filesystem subdir is a different state
 - `UNRESOLVED_RFC_TRACE STORY-NNN claims=RFC-NNN` — neither a legacy RFC file nor a story-map release row exists
 - `MISSING_REVERSE_TRACE STORY-NNN in RFC-NNN release row` — the release row exists but does not contain the story card
 
+**Which stories the legacy-RFC leg covers** — only APPROVED ones, and a story is approved when every story map it names is ratified (the "A release row is the RFC, and the map is the approval surface" architecture rule). the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule forbids an RFC from referencing a story whose map is not ratified, so for such a story the `## Stories` row is *correctly absent* — a `MISSING_REVERSE_TRACE` against it would be a finding no compliant action could clear, since satisfying it means breaking the rule it exists to protect (the "reconcile-stories reports permanent false MISSING_REVERSE_TRACE drift against 's ratified-stories-only rule" problem / the ": A clean reconciler result means the tier really is clean" delivery story). The problem and JTBD legs are not narrowed; no ratification rule governs those pairs. The release-row leg is not narrowed either: a story card is compelled onto its map at capture (the "Story-map membership and story-content completeness are enforced at capture" architecture rule) and cards sit outside the map's fingerprint basis (the "A release row is the RFC, and the map is the approval surface" architecture rule), so a card's absence from its row is never correct.
+
+**The run says which population it checked**, on stderr, whether or not there was drift — so a clean result can be read as "checked and clean" rather than "quietly skipped":
+
+```
+reconcile-stories: RFC ## Stories reverse trace checked 15 of 30 story/RFC pairs.
+reconcile-stories:   12 skipped because the story's map is not ratified, so the row is correctly absent.
+reconcile-stories:   3 skipped because the story names no story map at all; that is a corpus defect, not a correct absence.
+```
+
+The two corpus-defect counts — a story naming no map, and a story naming a map id that does not resolve to exactly one file — are reported apart from the correct-absence count on purpose. Folding either in would hide a real defect behind an explanation that does not apply to it.
+
 ## When to invoke
 
 - **Drift detected by another skill's preflight** — `/wr-itil:manage-story` or `/wr-itil:work-problems` Step 0 preflight may surface `docs/stories/README.md` drift; this skill is the recovery path.
@@ -46,9 +56,7 @@ Read `/tmp/wr-itil-stories-drift-$$.txt` line by line. Each line is one of:
 - `DRIFT    STORY-NNN rankings: claims=<X> actual=<Y>` — Story Rankings row has wrong Status; update the row.
 - `STALE    STORY-NNN rankings: actual=<state>` — Story Rankings table is missing a row; add it.
 - `MISMATCH STORY-NNN done: actual=<state>` — Done table has wrong row OR an extra row; remove/adjust.
-- `MISSING_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — parent's `## Stories` section needs the story added; call `update-<parent-kind>-references-section.sh <parent-file> "Stories"` to refresh.
-- `STALE_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — parent's `## Stories` section needs the story removed; same helper call (idempotent, lazy-empty discipline removes when no traces remain).
-- `STATUS_MISMATCH STORY-NNN in <PARENT-ID> ## Stories claims=<X> actual=<Y>` — same helper call refreshes the status column.
+- `MISSING_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — parent's `## Stories` section needs the story added; call `update-<parent-kind>-references-section.sh <parent-file> "Stories"` to refresh. The helper regenerates the whole section and admits only approved stories, so it can never write in a reference the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule forbids. When it withholds one it says so on stderr: the remedy is to **ratify that story's MAP** (the "A release row is the RFC, and the map is the approval surface" architecture rule), never to hand-add the row.
 - `UNRESOLVED_RFC_TRACE` / row `MISSING_REVERSE_TRACE` — repair the map's release row or card through `/wr-itil:manage-story-map`; do not create an empty RFC file.
 
 ### 3. Apply edits
@@ -103,11 +111,14 @@ After commit, report:
 - **the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule** — plugin-bundled scripts via `bin/` on `$PATH`. `wr-itil-reconcile-stories` shim follows this grammar.
 - **the "Governance Skills Commit Their Own Completed Work" architecture rule** — single-commit grain. The reconciliation pass is a single coherent action; one commit per pass.
 - **the "Behavioural-tests-default for skill testing" architecture rule** — behavioural-tests default. Bats coverage at `packages/itil/scripts/test/reconcile-stories.bats` (the "Problem tickets strain as fixes decompose into multiple coordinated changes — need an RFC framework that ties all changes back to problems (and unifies technical with user/business problems)" problem Phase 2 Slice 9).
-- **the "Session-start briefing surface — SessionStart hook over tiered directory + indexed README" architecture rule** — diagnose-only advisory-exit contract. `reconcile-stories.sh` is exit-1 on drift, exit-0 on clean, exit-2 on parse error.
+- **Exit-code convention** — exit-1 on drift, exit-0 on clean, exit-2 on parse error. Shared unchanged with `reconcile-readme.sh`, `reconcile-rfcs.sh` and `check-rfc-stories-ratified.sh`; no ADR records it, and none should — a convention with one viable shape, already implemented uniformly, is not decision-bearing. (This line cited the "Session-start briefing surface — SessionStart hook over tiered directory + indexed README" architecture rule until 2026-09-19; the "Session-start briefing surface — SessionStart hook over tiered directory + indexed README" architecture rule is the session-start briefing surface and says nothing about exit codes.)
+- **the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule** / **the "A release row is the RFC, and the map is the approval surface" architecture rule** / **the "Story-map membership and story-content completeness are enforced at capture" architecture rule** — the rules that set the legacy-RFC leg's population: an RFC references only approved stories; approval reaches a story through its map; a story card is on its map from capture.
+- **the "reconcile-stories reports permanent false MISSING_REVERSE_TRACE drift against 's ratified-stories-only rule" problem** / **the ": A clean reconciler result means the tier really is clean" delivery story** — the narrowing, and the stderr population report that makes a clean result readable.
 - **the "`docs/problems/README.md` drifts from filesystem truth across sessions despite (refresh-on-create) and (refresh-on-transition) both Closed" problem** / `reconcile-readme.sh` — sibling at the problems tier.
 - **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule Phase 1 item 5** / `reconcile-rfcs.sh` — sibling at the RFC tier.
 - **Slice 2a/2b helpers** — `update-problem-references-section.sh`, `update-rfc-references-section.sh`, `update-jtbd-references-section.sh` are the load-bearing reverse-trace refresh helpers this skill invokes; all three accept `"Stories"` as a section-name token per their lookup tables.
 - **the ": Enforce Governance Without Slowing Down" user outcome** — Enforce Governance Without Slowing Down. Drift detection is an automated governance enforcement surface; mechanical repair preserves the spirit while removing manual toil.
+- **the ": Progress the Backlog While I'm Away" user outcome** — Progress the Backlog While I'm Away. The legacy-RFC-leg narrowing (the "reconcile-stories reports permanent false MISSING_REVERSE_TRACE drift against 's ratified-stories-only rule" problem / the ": A clean reconciler result means the tier really is clean" delivery story) exists so an unattended loop can read a clean result as "checked and clean" rather than "quietly skipped", and so no finding demands an action the ratified-stories rule forbids.
 - **the ": Decompose a Fix Into Coordinated Changes" user outcome** — Decompose a Fix Into Coordinated Changes. Story tier reverse-trace integrity is load-bearing for the working-the-problem flow's per-story dispatch (Slice 13 traversal).
 
 $ARGUMENTS

package/skills-codex/reconcile-stories/SKILL.md

@@ -23,11 +23,21 @@ Sibling to `/wr-itil:reconcile-readme` (the "`docs/problems/README.md` drifts fr
 
 **Reverse-trace pass** — when the parent directories exist, the reconciler checks auto-maintained `## Stories` sections on problem, JTBD and legacy RFC files. For an the "A release row is the RFC, and the map is the approval surface" architecture rule row-backed RFC, it checks the map row instead: the RFC must resolve and the row must contain the story card.
 - `MISSING_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — story claims parent but parent's `## Stories` table doesn't list the story
-- `STALE_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — parent lists the story but story no longer claims the parent
-- `STATUS_MISMATCH STORY-NNN in <PARENT-ID> ## Stories claims=<X> actual=<Y>` — parent's row claims one lifecycle status; story's filesystem subdir is a different state
 - `UNRESOLVED_RFC_TRACE STORY-NNN claims=RFC-NNN` — neither a legacy RFC file nor a story-map release row exists
 - `MISSING_REVERSE_TRACE STORY-NNN in RFC-NNN release row` — the release row exists but does not contain the story card
 
+**Which stories the legacy-RFC leg covers** — only APPROVED ones, and a story is approved when every story map it names is ratified (the "A release row is the RFC, and the map is the approval surface" architecture rule). the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule forbids an RFC from referencing a story whose map is not ratified, so for such a story the `## Stories` row is *correctly absent* — a `MISSING_REVERSE_TRACE` against it would be a finding no compliant action could clear, since satisfying it means breaking the rule it exists to protect (the "reconcile-stories reports permanent false MISSING_REVERSE_TRACE drift against 's ratified-stories-only rule" problem / the ": A clean reconciler result means the tier really is clean" delivery story). The problem and JTBD legs are not narrowed; no ratification rule governs those pairs. The release-row leg is not narrowed either: a story card is compelled onto its map at capture (the "Story-map membership and story-content completeness are enforced at capture" architecture rule) and cards sit outside the map's fingerprint basis (the "A release row is the RFC, and the map is the approval surface" architecture rule), so a card's absence from its row is never correct.
+
+**The run says which population it checked**, on stderr, whether or not there was drift — so a clean result can be read as "checked and clean" rather than "quietly skipped":
+
+```
+reconcile-stories: RFC ## Stories reverse trace checked 15 of 30 story/RFC pairs.
+reconcile-stories:   12 skipped because the story's map is not ratified, so the row is correctly absent.
+reconcile-stories:   3 skipped because the story names no story map at all; that is a corpus defect, not a correct absence.
+```
+
+The two corpus-defect counts — a story naming no map, and a story naming a map id that does not resolve to exactly one file — are reported apart from the correct-absence count on purpose. Folding either in would hide a real defect behind an explanation that does not apply to it.
+
 ## When to invoke
 
 - **Drift detected by another skill's preflight** — `/wr-itil:manage-story` or `/wr-itil:work-problems` Step 0 preflight may surface `docs/stories/README.md` drift; this skill is the recovery path.
@@ -57,9 +67,7 @@ Read `/tmp/wr-itil-stories-drift-$$.txt` line by line. Each line is one of:
 - `DRIFT    STORY-NNN rankings: claims=<X> actual=<Y>` — Story Rankings row has wrong Status; update the row.
 - `STALE    STORY-NNN rankings: actual=<state>` — Story Rankings table is missing a row; add it.
 - `MISMATCH STORY-NNN done: actual=<state>` — Done table has wrong row OR an extra row; remove/adjust.
-- `MISSING_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — parent's `## Stories` section needs the story added; call `update-<parent-kind>-references-section.sh <parent-file> "Stories"` to refresh.
-- `STALE_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — parent's `## Stories` section needs the story removed; same helper call (idempotent, lazy-empty discipline removes when no traces remain).
-- `STATUS_MISMATCH STORY-NNN in <PARENT-ID> ## Stories claims=<X> actual=<Y>` — same helper call refreshes the status column.
+- `MISSING_REVERSE_TRACE STORY-NNN in <PARENT-ID> ## Stories` — parent's `## Stories` section needs the story added; call `update-<parent-kind>-references-section.sh <parent-file> "Stories"` to refresh. The helper regenerates the whole section and admits only approved stories, so it can never write in a reference the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule forbids. When it withholds one it says so on stderr: the remedy is to **ratify that story's MAP** (the "A release row is the RFC, and the map is the approval surface" architecture rule), never to hand-add the row.
 - `UNRESOLVED_RFC_TRACE` / row `MISSING_REVERSE_TRACE` — repair the map's release row or card through `/wr-itil:manage-story-map`; do not create an empty RFC file.
 
 ### 3. Apply edits
@@ -114,11 +122,14 @@ After commit, report:
 - **the "Plugin-bundled scripts invoked from SKILL.md resolve via `bin/` on `$PATH`" architecture rule** — plugin-bundled scripts via `bin/` on `$PATH`. `<itil-plugin-root>/bin/wr-itil-reconcile-stories` shim follows this grammar.
 - **the "Governance Skills Commit Their Own Completed Work" architecture rule** — single-commit grain. The reconciliation pass is a single coherent action; one commit per pass.
 - **the "Behavioural-tests-default for skill testing" architecture rule** — behavioural-tests default. Bats coverage at `<itil-plugin-root>/scripts/test/reconcile-stories.bats` (the "Problem tickets strain as fixes decompose into multiple coordinated changes — need an RFC framework that ties all changes back to problems (and unifies technical with user/business problems)" problem Phase 2 Slice 9).
-- **the "Session-start briefing surface — SessionStart hook over tiered directory + indexed README" architecture rule** — diagnose-only advisory-exit contract. `reconcile-stories.sh` is exit-1 on drift, exit-0 on clean, exit-2 on parse error.
+- **Exit-code convention** — exit-1 on drift, exit-0 on clean, exit-2 on parse error. Shared unchanged with `reconcile-readme.sh`, `reconcile-rfcs.sh` and `check-rfc-stories-ratified.sh`; no ADR records it, and none should — a convention with one viable shape, already implemented uniformly, is not decision-bearing. (This line cited the "Session-start briefing surface — SessionStart hook over tiered directory + indexed README" architecture rule until 2026-09-19; the "Session-start briefing surface — SessionStart hook over tiered directory + indexed README" architecture rule is the session-start briefing surface and says nothing about exit codes.)
+- **the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule** / **the "A release row is the RFC, and the map is the approval surface" architecture rule** / **the "Story-map membership and story-content completeness are enforced at capture" architecture rule** — the rules that set the legacy-RFC leg's population: an RFC references only approved stories; approval reaches a story through its map; a story card is on its map from capture.
+- **the "reconcile-stories reports permanent false MISSING_REVERSE_TRACE drift against 's ratified-stories-only rule" problem** / **the ": A clean reconciler result means the tier really is clean" delivery story** — the narrowing, and the stderr population report that makes a clean result readable.
 - **the "`docs/problems/README.md` drifts from filesystem truth across sessions despite (refresh-on-create) and (refresh-on-transition) both Closed" problem** / `reconcile-readme.sh` — sibling at the problems tier.
 - **the "Problem-RFC-Story framework with mandatory problem-trace and unified problem ontology" architecture rule Phase 1 item 5** / `reconcile-rfcs.sh` — sibling at the RFC tier.
 - **Slice 2a/2b helpers** — `update-problem-references-section.sh`, `update-rfc-references-section.sh`, `update-jtbd-references-section.sh` are the load-bearing reverse-trace refresh helpers this skill invokes; all three accept `"Stories"` as a section-name token per their lookup tables.
 - **the ": Enforce Governance Without Slowing Down" user outcome** — Enforce Governance Without Slowing Down. Drift detection is an automated governance enforcement surface; mechanical repair preserves the spirit while removing manual toil.
+- **the ": Progress the Backlog While I'm Away" user outcome** — Progress the Backlog While I'm Away. The legacy-RFC-leg narrowing (the "reconcile-stories reports permanent false MISSING_REVERSE_TRACE drift against 's ratified-stories-only rule" problem / the ": A clean reconciler result means the tier really is clean" delivery story) exists so an unattended loop can read a clean result as "checked and clean" rather than "quietly skipped", and so no finding demands an action the ratified-stories rule forbids.
 - **the ": Decompose a Fix Into Coordinated Changes" user outcome** — Decompose a Fix Into Coordinated Changes. Story tier reverse-trace integrity is load-bearing for the working-the-problem flow's per-story dispatch (Slice 13 traversal).
 
 $ARGUMENTS