@windyroad/itil 0.27.1 → 0.28.0-preview.304

package/lib/migrate-problems-layout.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# Canonical shared migration routine — adopter `docs/problems/` flat → per-state subdir.
+# P170 / RFC-002 / ADR-031 (accepted 2026-05-12).
+#
+# Adopter repos that installed `@windyroad/itil` before ADR-031 acceptance
+# carry the flat-layout `docs/problems/<NNN>-<slug>.<state>.md` shape. The
+# `manage-problem` and `work-problems` skills source this file at Step 1
+# (ADR-032 foreground-synchronous) and call `migrate_problems_to_per_state_layout`
+# before any layout-dependent logic, so adopter trees auto-migrate on first
+# invocation post-update.
+#
+# Distribution: ADR-017 sync pattern. Canonical lives at
+#   packages/shared/lib/migrate-problems-layout.sh
+# Synced into each consumer's lib/ (currently only `packages/itil/lib/`)
+# by `scripts/sync-migrate-problems-layout.sh`. Drift is asserted by
+# `packages/shared/test/sync-migrate-problems-layout.bats` and the
+# `npm run check:migrate-problems-layout` CI step.
+#
+# Dependencies: bash 4+ (uses `shopt -s nullglob`), git, standard core utils.
+# Not POSIX-portable — the architect advisory at T7 review explicitly
+# scoped this to bash (compgen / nullglob are bash builtins).
+#
+# Source this file, then call `migrate_problems_to_per_state_layout`:
+#   . packages/itil/lib/migrate-problems-layout.sh
+#   migrate_problems_to_per_state_layout "$PWD"
+
+# detect_flat_layout REPO_ROOT
+# Returns 0 if any docs/problems/*.<state>.md exists at top level of
+# docs/problems/ (flat layout present — migration needed); 1 otherwise.
+# Partial-migration-safe: returns 0 even when some files have already
+# moved into subdirs, so re-invocation completes any tail iteration.
+detect_flat_layout() {
+  local repo_root="${1:-$PWD}"
+  local problems_dir="$repo_root/docs/problems"
+  [ -d "$problems_dir" ] || return 1
+
+  local state
+  shopt -s nullglob
+  for state in open known-error verifying parked closed; do
+    local matches=( "$problems_dir"/*."$state".md )
+    if [ ${#matches[@]} -gt 0 ]; then
+      shopt -u nullglob
+      return 0
+    fi
+  done
+  shopt -u nullglob
+  return 1
+}
+
+# migrate_problems_to_per_state_layout REPO_ROOT
+# Idempotent + partial-migration-safe entrypoint.
+# Returns 0 when already-migrated (no-op) OR migration completed cleanly.
+# Returns non-zero on git failure. Writes a standalone commit with
+# subject `docs(problems): auto-migrate to per-state subdirectory layout (ADR-031)`
+# and a footer `RISK_BYPASS: adr-031-migration` trailer recognised by the
+# commit-gate hook (T11). Standalone-commit grain per ADR-031 §
+# Backward Compatibility (line 124).
+migrate_problems_to_per_state_layout() {
+  local repo_root="${1:-$PWD}"
+  local problems_dir="$repo_root/docs/problems"
+
+  if [ ! -d "$problems_dir" ]; then
+    return 0
+  fi
+
+  if ! detect_flat_layout "$repo_root"; then
+    return 0
+  fi
+
+  if ! command -v git >/dev/null 2>&1; then
+    echo "ERROR: git not available; cannot auto-migrate docs/problems/ layout" >&2
+    return 1
+  fi
+
+  if ! (cd "$repo_root" && git rev-parse --git-dir >/dev/null 2>&1); then
+    echo "ERROR: not a git repository at $repo_root; cannot auto-migrate" >&2
+    return 1
+  fi
+
+  local state f base target moved_count=0
+  shopt -s nullglob
+  for state in open known-error verifying parked closed; do
+    mkdir -p "$problems_dir/$state"
+    for f in "$problems_dir"/*."$state".md; do
+      [ -e "$f" ] || continue
+      base="$(basename "$f" ".$state.md")"
+      target="$problems_dir/$state/$base.md"
+      if [ -e "$target" ]; then
+        echo "WARNING: target $target already exists; skipping $f" >&2
+        continue
+      fi
+      (cd "$repo_root" && git mv "$f" "$target") || {
+        shopt -u nullglob
+        echo "ERROR: git mv failed for $f" >&2
+        return 1
+      }
+      moved_count=$((moved_count + 1))
+    done
+  done
+  shopt -u nullglob
+
+  if (cd "$repo_root" && git diff --cached --quiet); then
+    return 0
+  fi
+
+  # JTBD-006 AFK transparency (T8 jtbd-review nitpick c): single stderr
+  # line on first-fire so AFK orchestrator output records the action.
+  echo "migrate-problems-layout: relocated $moved_count tickets to per-state subdirs (ADR-031)" >&2
+
+  # JTBD-201 audit-trail forward-pointer (T8 jtbd-review nitpick b):
+  # commit body cites ADR-031 so future `git log` readers have the
+  # semantic context without needing to grep the trailer.
+  # T10 fix: use sequential `-m` paragraphs instead of `--trailer`; the
+  # `--trailer` mechanism in git 2.47.x appended a spurious trailing
+  # colon to the token line, breaking ^RISK_BYPASS:\s*adr-031-migration$
+  # parsers downstream. Sequential `-m` paragraphs write a clean
+  # `RISK_BYPASS: adr-031-migration` line in the body.
+  (cd "$repo_root" && git commit \
+    -m "docs(problems): auto-migrate to per-state subdirectory layout (ADR-031)" \
+    -m "See: docs/decisions/031-problem-ticket-directory-layout.accepted.md" \
+    -m "Policy-authorised under ADR-013 Rule 6 + ADR-019 precedent (pure-rename + pure-mkdir; fully reversible via git revert)." \
+    -m "RISK_BYPASS: adr-031-migration") || {
+    echo "ERROR: migration commit failed" >&2
+    return 1
+  }
+
+  return 0
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.27.1",
+  "version": "0.28.0-preview.304",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/scripts/reconcile-stories.sh

@@ -0,0 +1,236 @@
+#!/usr/bin/env bash
+# packages/itil/scripts/reconcile-stories.sh
+#
+# Diagnose-only drift detector for docs/stories/README.md vs filesystem
+# truth. Reads <stories-dir>/<state>/STORY-<NNN>-*.md (per-state subdirs:
+# draft, accepted, in-progress, done, archived), parses the README's
+# Story Rankings + Done tables, and reports each disagreement.
+#
+# Usage:
+#   reconcile-stories.sh [<stories-dir> [<problems-dir> [<rfcs-dir> [<jtbd-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)
+#
+# Exit codes:
+#   0 = clean (README matches filesystem)
+#   1 = drift detected (structured diff to stdout)
+#   2 = parse error (README missing or malformed)
+#
+# Output format on drift (one line per drift entry, ≤ 150 bytes per
+# ADR-038 progressive-disclosure budget):
+#   DRIFT    STORY-<NNN> rankings: claims=<status> actual=<status>
+#   STALE    STORY-<NNN> rankings: actual=<status>
+#   MISMATCH STORY-<NNN> done: actual=<status>
+#
+# Reverse-trace pass (P170 Phase 2 Slice 9 — closes ADR-060 line 270):
+# When <problems-dir> / <rfcs-dir> / <jtbd-dir> are provided AND on
+# disk, the reconciler also checks the auto-maintained `## Stories`
+# section on each parent artefact against the story frontmatter's
+# `problems:` / `rfcs:` / `jtbd:` claims. Three drift kinds per parent
+# tier:
+#   MISSING_REVERSE_TRACE  STORY-<NNN> in <PARENT-ID> ## Stories
+#     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.
+#
+# Read-only — does NOT mutate the README. The /wr-itil:manage-story skill
+# (P170 Phase 2 Slice 8) applies edits with narrative-aware preservation;
+# this script's only job is to report ground truth.
+#
+# Sibling to packages/itil/scripts/reconcile-rfcs.sh (ADR-060 Phase 1
+# item 5) and reconcile-readme.sh (P118 / ADR-014): same parse + diff
+# structure, applied at the story tier instead of the RFC / problem
+# tier. Differences from reconcile-rfcs:
+#   - Filename pattern: <state>/STORY-NNN-*.md (5 states: draft, accepted,
+#     in-progress, done, archived) — per-state subdir layout (NOT
+#     dual-tolerant flat — story tier is post-RFC-002, native-subdir)
+#   - ID format: STORY-<NNN>
+#   - No WSJF column (I11 invariant per ADR-060 line 253)
+#   - Story Rankings covers draft/accepted/in-progress (story dev queue)
+#   - Done covers done (matches RFC closed semantics)
+#   - No Verification Queue (stories don't have a verifying status —
+#     done is end-of-lifecycle for stories per ADR-060)
+#   - No Parked tier (stories don't have a Parked status; only Problems do)
+#
+# @problem P170
+# @adr ADR-060 (Problem-RFC-Story framework — Phase 2 amendment 2026-05-10
+#                 story tier; reconcile-stories is the story-tier sibling
+#                 of reconcile-rfcs)
+# @adr ADR-049 (Plugin script resolution via bin/ on PATH — paired bin shim
+#                at packages/itil/bin/wr-itil-reconcile-stories)
+
+set -uo pipefail
+
+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}"
+README="${STORIES_DIR}/README.md"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -f "$README" ]; then
+  echo "PARSE_ERROR: README not found at ${README}" >&2
+  exit 2
+fi
+
+if ! grep -q '^## Story Rankings' "$README"; then
+  echo "PARSE_ERROR: '## Story Rankings' header missing in ${README}" >&2
+  exit 2
+fi
+
+# ── Build filesystem truth: ID → status ─────────────────────────────────────
+
+declare -A FS_STATUS
+shopt -s nullglob
+for state in draft accepted in-progress done archived; do
+  for f in "$STORIES_DIR"/"$state"/STORY-[0-9][0-9][0-9]-*.md; do
+    base="$(basename "$f")"
+    num="${base#STORY-}"
+    num="${num%%-*}"
+    id="STORY-${num}"
+    FS_STATUS["$id"]="$state"
+  done
+done
+shopt -u nullglob
+
+# ── Parse README sections into ID buckets ───────────────────────────────────
+
+RANKINGS_START=$(grep -nE '^## Story Rankings' "$README" | head -1 | cut -d: -f1)
+DONE_START=$(grep -n '^## Done' "$README" | head -1 | cut -d: -f1)
+END_LINE=$(wc -l < "$README")
+
+RANKINGS_END=${DONE_START:-$END_LINE}
+DONE_END=$END_LINE
+
+extract_section_ids() {
+  local start="$1" end="$2"
+  [ -z "$start" ] && return 0
+  sed -n "${start},${end}p" "$README" \
+    | grep -oE '\| *STORY-[0-9]{3} *\|' \
+    | grep -oE 'STORY-[0-9]{3}' \
+    | sort -u
+}
+
+README_RANKINGS_IDS="$(extract_section_ids "$RANKINGS_START" "$RANKINGS_END")"
+README_DONE_IDS="$(extract_section_ids "$DONE_START" "$DONE_END")"
+
+# ── Diff ─────────────────────────────────────────────────────────────────────
+
+DRIFT_LINES=()
+
+# (1) Each ID listed in Story Rankings must be draft / accepted /
+#     in-progress on disk. Other statuses (done / archived) → drift.
+while read -r id; do
+  [ -z "$id" ] && continue
+  actual="${FS_STATUS[$id]:-missing}"
+  case "$actual" in
+    draft|accepted|in-progress)
+      : # ok
+      ;;
+    *)
+      DRIFT_LINES+=("DRIFT    ${id} rankings: claims=active actual=${actual}")
+      ;;
+  esac
+done <<< "$README_RANKINGS_IDS"
+
+# (2) Each ID listed in Done section must be done on disk.
+while read -r id; do
+  [ -z "$id" ] && continue
+  actual="${FS_STATUS[$id]:-missing}"
+  case "$actual" in
+    done)
+      : # ok
+      ;;
+    *)
+      DRIFT_LINES+=("MISMATCH ${id} done: actual=${actual}")
+      ;;
+  esac
+done <<< "$README_DONE_IDS"
+
+# (3) Each ID on disk in draft/accepted/in-progress must appear in
+#     Story Rankings. Each done on disk must appear in Done.
+for id in "${!FS_STATUS[@]}"; do
+  state="${FS_STATUS[$id]}"
+  case "$state" in
+    draft|accepted|in-progress)
+      if ! grep -qF "$id" <<< "$README_RANKINGS_IDS"; then
+        DRIFT_LINES+=("STALE    ${id} rankings: actual=${state}")
+      fi
+      ;;
+    done)
+      if ! grep -qF "$id" <<< "$README_DONE_IDS"; then
+        DRIFT_LINES+=("STALE    ${id} done: actual=done")
+      fi
+      ;;
+    archived)
+      : # archived stories are intentionally hidden from both tables
+      ;;
+  esac
+done
+
+# ── Reverse-trace pass — story frontmatter ↔ parent ## Stories section ─────
+
+reverse_trace_pass() {
+  local parent_dir="$1" parent_kind="$2" parent_id_pattern="$3"
+  [ ! -d "$parent_dir" ] && return 0
+
+  shopt -s nullglob globstar
+  # Extract frontmatter trace claims from each story and verify parents
+  # carry the matching ## Stories row.
+  for sf in "$STORIES_DIR"/*/STORY-[0-9][0-9][0-9]-*.md; do
+    sbase="$(basename "$sf")"
+    snum="${sbase#STORY-}"; snum="${snum%%-*}"
+    sid="STORY-${snum}"
+    sstatus="${FS_STATUS[$sid]:-missing}"
+
+    # Parse the frontmatter parent list ($parent_kind = problems|rfcs|jtbd)
+    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
+      case "$parent_kind" in
+        problems)
+          pnum="${pid#P}"
+          pfile=$(ls "$parent_dir"/${pnum}-*.md "$parent_dir"/*/${pnum}-*.md 2>/dev/null | head -1)
+          ;;
+        rfcs)
+          pfile=$(ls "$parent_dir"/${pid}-*.md 2>/dev/null | head -1)
+          ;;
+        jtbd)
+          pfile=$(ls "$parent_dir"/*/${pid}-*.md 2>/dev/null | head -1)
+          ;;
+        *) pfile="" ;;
+      esac
+      [ -z "$pfile" ] && continue
+
+      # 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")
+      fi
+    done
+  done
+  shopt -u nullglob globstar
+}
+
+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}"
+
+# ── Emit ─────────────────────────────────────────────────────────────────────
+
+if [ ${#DRIFT_LINES[@]} -eq 0 ]; then
+  exit 0
+fi
+
+printf '%s\n' "${DRIFT_LINES[@]}"
+exit 1

package/scripts/reconcile-story-maps.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# packages/itil/scripts/reconcile-story-maps.sh
+#
+# Diagnose-only drift detector for docs/story-maps/README.md vs
+# filesystem truth. Reads <story-maps-dir>/<state>/STORY-MAP-<NNN>-*.html
+# files across 5 lifecycle subdirs (draft, accepted, in-progress,
+# completed, archived) and reports each disagreement against the README.
+#
+# Sibling to reconcile-stories.sh (P170 Phase 2 Slice 9) and
+# reconcile-rfcs.sh (ADR-060 Phase 1 item 5). Differences:
+#   - File extension: .html (not .md)
+#   - ID format: STORY-MAP-<NNN>
+#   - No WSJF (I5 invariant per ADR-060 line 145)
+#   - No Rankings table — story-maps are planning artefacts, not work items;
+#     README has only a single lifecycle-grouped table
+#   - 5 lifecycle subdirs (vs story tier's 5 + RFC tier's 5)
+#   - <meta> block parse (HTML) not YAML frontmatter parse
+#
+# Usage:
+#   reconcile-story-maps.sh [<story-maps-dir>]
+#
+# Default <story-maps-dir> is ./docs/story-maps.
+#
+# Exit codes:
+#   0 = clean
+#   1 = drift detected (structured stdout)
+#   2 = parse error (README missing or malformed)
+#
+# @problem P170
+# @adr ADR-060 (Problem-RFC-Story framework — Phase 2 amendment 2026-05-10
+#                story-map tier; reconcile-story-maps is the story-map-tier
+#                sibling of reconcile-stories + reconcile-rfcs)
+# @adr ADR-049 (Plugin-bundled scripts via bin/ on PATH — paired bin shim
+#                at packages/itil/bin/wr-itil-reconcile-story-maps)
+
+set -uo pipefail
+
+STORY_MAPS_DIR="${1:-docs/story-maps}"
+README="${STORY_MAPS_DIR}/README.md"
+
+# ── Pre-checks ──────────────────────────────────────────────────────────────
+
+if [ ! -f "$README" ]; then
+  echo "PARSE_ERROR: README not found at ${README}" >&2
+  exit 2
+fi
+
+# ── Build filesystem truth: ID → status ─────────────────────────────────────
+
+declare -A FS_STATUS
+shopt -s nullglob
+for state in draft accepted in-progress completed archived; do
+  for f in "$STORY_MAPS_DIR"/"$state"/STORY-MAP-[0-9][0-9][0-9]-*.html; do
+    base="$(basename "$f")"
+    num="${base#STORY-MAP-}"
+    num="${num%%-*}"
+    id="STORY-MAP-${num}"
+    FS_STATUS["$id"]="$state"
+  done
+done
+shopt -u nullglob
+
+# ── Extract README ID claims (single lifecycle-grouped table) ──────────────
+
+# The README has lifecycle-grouped sections; extract STORY-MAP-NNN tokens
+# from anywhere in the README and verify each appears in the correct
+# state's section.
+README_IDS=$(grep -oE 'STORY-MAP-[0-9]{3}' "$README" | sort -u)
+
+# ── Diff ─────────────────────────────────────────────────────────────────────
+
+DRIFT_LINES=()
+
+# (1) Each ID listed in README must exist on filesystem with a state.
+while read -r id; do
+  [ -z "$id" ] && continue
+  actual="${FS_STATUS[$id]:-missing}"
+  if [ "$actual" = "missing" ]; then
+    DRIFT_LINES+=("MISSING  ${id} README claims it exists but no file on disk")
+  fi
+done <<< "$README_IDS"
+
+# (2) Each ID on disk must appear in README.
+for id in "${!FS_STATUS[@]}"; do
+  state="${FS_STATUS[$id]}"
+  if ! grep -qF "$id" <<< "$README_IDS"; then
+    DRIFT_LINES+=("STALE    ${id} README missing entry; actual=${state}")
+  fi
+done
+
+# ── Emit ─────────────────────────────────────────────────────────────────────
+
+if [ ${#DRIFT_LINES[@]} -eq 0 ]; then
+  exit 0
+fi
+
+printf '%s\n' "${DRIFT_LINES[@]}"
+exit 1

package/scripts/test/reconcile-stories.bats

@@ -0,0 +1,173 @@
+#!/usr/bin/env bats
+# Behavioural fixtures for reconcile-stories.sh + bin shim + skill
+# (P170 Phase 2 Slice 9 — ADR-060 amendment 2026-05-10 line 270 +
+# reconcile-rfcs.sh / reconcile-readme.sh sibling).
+#
+# Per ADR-052: behavioural tests on observable script outputs. The
+# load-bearing surfaces under test are:
+#   1. Script existence + executable + valid Bash.
+#   2. README parse error (exit 2) on missing README or missing
+#      Story Rankings header.
+#   3. Clean run (exit 0) on a fresh stories directory + empty README.
+#   4. Drift detection (exit 1) when README claims a story that isn't
+#      on filesystem in the right lifecycle state.
+#   5. STALE detection when filesystem has a story not listed in
+#      either Story Rankings (active) or Done section.
+#   6. Bin shim resolves to the script.
+#   7. SKILL.md presence + canonical name + read-only contract.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="${REPO_ROOT}/packages/itil/scripts/reconcile-stories.sh"
+  BIN_SHIM="${REPO_ROOT}/packages/itil/bin/wr-itil-reconcile-stories"
+  SKILL_FILE="${REPO_ROOT}/packages/itil/skills/reconcile-stories/SKILL.md"
+
+  TMPROOT=$(mktemp -d)
+  ORIG_DIR="$PWD"
+  cd "$TMPROOT"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TMPROOT"
+}
+
+# ---------------------------------------------------------------------------
+# Surface 1: Script + bin shim existence
+# ---------------------------------------------------------------------------
+
+@test "reconcile-stories: script exists and is executable" {
+  [ -f "$SCRIPT" ]
+  [ -x "$SCRIPT" ]
+}
+
+@test "reconcile-stories: bin shim exists, is executable, and exec's the script" {
+  [ -f "$BIN_SHIM" ]
+  [ -x "$BIN_SHIM" ]
+  run grep -E 'exec.*scripts/reconcile-stories\.sh' "$BIN_SHIM"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 2: Parse errors (exit 2)
+# ---------------------------------------------------------------------------
+
+@test "reconcile-stories: exits 2 when README is missing" {
+  mkdir -p docs/stories
+  run bash "$SCRIPT" docs/stories
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"PARSE_ERROR"* ]] || [[ "$stderr" == *"PARSE_ERROR"* ]]
+}
+
+@test "reconcile-stories: exits 2 when README missing Story Rankings header" {
+  mkdir -p docs/stories
+  echo "# Stories" > docs/stories/README.md
+  run bash "$SCRIPT" docs/stories
+  [ "$status" -eq 2 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 3: Clean run (exit 0)
+# ---------------------------------------------------------------------------
+
+@test "reconcile-stories: exits 0 on empty stories dir with empty README tables" {
+  mkdir -p docs/stories/draft docs/stories/accepted docs/stories/in-progress docs/stories/done docs/stories/archived
+  cat > docs/stories/README.md <<'EOF'
+# Story Backlog
+
+## Story Rankings
+
+| ID | Title | Status |
+|----|-------|--------|
+
+## Done
+
+| ID | Title | Done |
+|----|-------|------|
+EOF
+  run bash "$SCRIPT" docs/stories
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 4: Drift detection on filesystem vs README mismatch (exit 1)
+# ---------------------------------------------------------------------------
+
+@test "reconcile-stories: detects STALE when filesystem has a draft story not in README" {
+  mkdir -p docs/stories/draft docs/stories/done
+  touch docs/stories/draft/STORY-007-foo.md
+  cat > docs/stories/README.md <<'EOF'
+# Story Backlog
+
+## Story Rankings
+
+| ID | Title | Status |
+|----|-------|--------|
+
+## Done
+
+| ID | Title | Done |
+|----|-------|------|
+EOF
+  run bash "$SCRIPT" docs/stories
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"STALE"* ]]
+  [[ "$output" == *"STORY-007"* ]]
+}
+
+@test "reconcile-stories: detects DRIFT when README claims a story in Rankings but it's actually done on disk" {
+  mkdir -p docs/stories/draft docs/stories/done
+  touch docs/stories/done/STORY-007-foo.md
+  cat > docs/stories/README.md <<'EOF'
+# Story Backlog
+
+## Story Rankings
+
+| ID | Title | Status |
+|----|-------|--------|
+| STORY-007 | Foo | draft |
+
+## Done
+
+| ID | Title | Done |
+|----|-------|------|
+EOF
+  run bash "$SCRIPT" docs/stories
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"DRIFT"* ]]
+  [[ "$output" == *"STORY-007"* ]]
+  [[ "$output" == *"actual=done"* ]]
+}
+
+@test "reconcile-stories: archived stories are hidden from both tables (no drift)" {
+  mkdir -p docs/stories/archived
+  touch docs/stories/archived/STORY-007-foo.md
+  cat > docs/stories/README.md <<'EOF'
+# Story Backlog
+
+## Story Rankings
+
+| ID | Title | Status |
+|----|-------|--------|
+
+## Done
+
+| ID | Title | Done |
+|----|-------|------|
+EOF
+  run bash "$SCRIPT" docs/stories
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 5: SKILL.md presence + read-only contract
+# ---------------------------------------------------------------------------
+
+@test "reconcile-stories: SKILL.md exists" {
+  [ -f "$SKILL_FILE" ]
+}
+
+@test "reconcile-stories: SKILL.md declares canonical name wr-itil:reconcile-stories" {
+  run grep -E '^name: wr-itil:reconcile-stories$' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}