@windyroad/itil 0.27.1 → 0.28.0-preview.303

package/scripts/test/reconcile-story-maps.bats

@@ -0,0 +1,74 @@
+#!/usr/bin/env bats
+# Behavioural fixtures for reconcile-story-maps.sh + bin shim + skill
+# (P170 Phase 2 Slice 5 — sibling of reconcile-stories.sh / reconcile-rfcs.sh).
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="${REPO_ROOT}/packages/itil/scripts/reconcile-story-maps.sh"
+  BIN_SHIM="${REPO_ROOT}/packages/itil/bin/wr-itil-reconcile-story-maps"
+  SKILL_FILE="${REPO_ROOT}/packages/itil/skills/reconcile-story-maps/SKILL.md"
+
+  TMPROOT=$(mktemp -d)
+  ORIG_DIR="$PWD"
+  cd "$TMPROOT"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TMPROOT"
+}
+
+@test "reconcile-story-maps: script exists and is executable" {
+  [ -f "$SCRIPT" ]
+  [ -x "$SCRIPT" ]
+}
+
+@test "reconcile-story-maps: bin shim exists, executable, exec's the script" {
+  [ -f "$BIN_SHIM" ]
+  [ -x "$BIN_SHIM" ]
+  run grep -E 'exec.*scripts/reconcile-story-maps\.sh' "$BIN_SHIM"
+  [ "$status" -eq 0 ]
+}
+
+@test "reconcile-story-maps: exits 2 when README is missing" {
+  mkdir -p docs/story-maps
+  run bash "$SCRIPT" docs/story-maps
+  [ "$status" -eq 2 ]
+}
+
+@test "reconcile-story-maps: exits 0 on empty story-maps dir + empty README" {
+  mkdir -p docs/story-maps/draft docs/story-maps/accepted docs/story-maps/in-progress docs/story-maps/completed docs/story-maps/archived
+  echo "# Story Maps" > docs/story-maps/README.md
+  run bash "$SCRIPT" docs/story-maps
+  [ "$status" -eq 0 ]
+}
+
+@test "reconcile-story-maps: detects STALE when filesystem has a map not in README" {
+  mkdir -p docs/story-maps/draft
+  touch docs/story-maps/draft/STORY-MAP-007-foo.html
+  echo "# Story Maps" > docs/story-maps/README.md
+  run bash "$SCRIPT" docs/story-maps
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"STALE"* ]]
+  [[ "$output" == *"STORY-MAP-007"* ]]
+}
+
+@test "reconcile-story-maps: detects MISSING when README claims a map that isn't on disk" {
+  mkdir -p docs/story-maps/draft
+  cat > docs/story-maps/README.md <<'EOF'
+# Story Maps
+| ID | Status |
+|----|--------|
+| STORY-MAP-007 | draft |
+EOF
+  run bash "$SCRIPT" docs/story-maps
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"MISSING"* ]]
+  [[ "$output" == *"STORY-MAP-007"* ]]
+}
+
+@test "reconcile-story-maps: SKILL.md exists with canonical name" {
+  [ -f "$SKILL_FILE" ]
+  run grep -E '^name: wr-itil:reconcile-story-maps$' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}

package/scripts/test/rfc-stories-extension.bats

@@ -0,0 +1,173 @@
+#!/usr/bin/env bats
+# Behavioural fixtures for the RFC frontmatter `stories:` extension
+# (P170 Phase 2 Slice 11 — ADR-060 lines 255-270 + 296).
+#
+# Per ADR-052: behavioural assertions on observable artefact state, not
+# structural prose-grep on SKILL.md. The load-bearing surfaces under
+# test are:
+#   1. RFC frontmatter spec in `docs/rfcs/README.md` includes the
+#      `stories:` field with the 0..N + ORDERED contract.
+#   2. The Slice 2b helper `update-rfc-references-section.sh` accepts
+#      "Stories" as a section name and:
+#      (a) renders a `## Stories` section from `stories: [STORY-NNN, ...]`
+#          frontmatter in execution order
+#      (b) applies lazy-empty discipline — empty `stories: []` produces
+#          NO `## Stories` section (atomic RFC, JTBD-101 friction guard)
+#   3. capture-rfc + manage-rfc SKILL.md both document the extension
+#      (existence checks; not prose grep of behaviour, but presence of
+#      load-bearing identifiers like `--stories` and `update-rfc-
+#      references-section.sh`).
+#
+# @problem P170
+# @jtbd JTBD-008 (Decompose a Fix Into Coordinated Changes — `stories:`
+#                  array IS the decomposition mechanism)
+# @jtbd JTBD-101 (atomic-fix-adopter friction guard — empty stories: []
+#                  ships as atomic RFC without per-story dispatch)
+# @adr  ADR-060  (Problem-RFC-Story framework — RFC frontmatter
+#                  extension at line 255-270 + skills extension line 296)
+# @adr  ADR-052  (Behavioural-tests-default)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  RFC_README="${REPO_ROOT}/docs/rfcs/README.md"
+  CAPTURE_RFC="${REPO_ROOT}/packages/itil/skills/capture-rfc/SKILL.md"
+  MANAGE_RFC="${REPO_ROOT}/packages/itil/skills/manage-rfc/SKILL.md"
+  HELPER="${REPO_ROOT}/packages/itil/scripts/update-rfc-references-section.sh"
+
+  TMPROOT=$(mktemp -d)
+  ORIG_DIR="$PWD"
+  cd "$TMPROOT"
+  mkdir -p docs/rfcs docs/stories/draft docs/stories/accepted docs/stories/done
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TMPROOT"
+}
+
+# ---------------------------------------------------------------------------
+# Surface 1: RFC frontmatter spec includes stories: field
+# ---------------------------------------------------------------------------
+
+@test "rfc-stories-extension: docs/rfcs/README.md frontmatter spec declares stories field" {
+  run grep -E '^stories:.*\[STORY-' "$RFC_README"
+  [ "$status" -eq 0 ]
+}
+
+@test "rfc-stories-extension: docs/rfcs/README.md describes 0..N + ORDERED cardinality" {
+  # The field semantics row must name the ordered + 0..N contract for
+  # working-the-problem traversal to read the field correctly.
+  run grep -iE 'ordered|execution sequence' "$RFC_README"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 2a: helper renders ## Stories section from populated stories: array
+# ---------------------------------------------------------------------------
+
+@test "rfc-stories-extension: helper renders populated stories: array in execution order" {
+  # Set up RFC with stories: [STORY-001, STORY-002] frontmatter, plus
+  # matching story files. Helper must produce a ## Stories section
+  # listing both in the array order.
+  cat > docs/rfcs/RFC-001-test.proposed.md <<'EOF'
+---
+status: proposed
+rfc-id: test
+reported: 2026-05-12
+decision-makers: [Test]
+problems: [P170]
+adrs: []
+jtbd: []
+stories: [STORY-001, STORY-002]
+---
+
+# RFC-001: Test
+
+## Summary
+
+Test.
+
+## Stories
+
+(empty)
+EOF
+  cat > docs/stories/draft/STORY-001-first.md <<'EOF'
+---
+status: draft
+story-id: first
+problems: [P170]
+jtbd: [JTBD-008]
+rfcs: [RFC-001]
+story-maps: []
+estimated-effort: deferred
+---
+
+# STORY-001: First story
+EOF
+  cat > docs/stories/draft/STORY-002-second.md <<'EOF'
+---
+status: draft
+story-id: second
+problems: [P170]
+jtbd: [JTBD-008]
+rfcs: [RFC-001]
+story-maps: []
+estimated-effort: deferred
+---
+
+# STORY-002: Second story
+EOF
+  run bash "$HELPER" docs/rfcs/RFC-001-test.proposed.md Stories
+  # Acceptable: zero exit OR advisory-warning exit; non-acceptable is
+  # the "unknown section-name" rejection signal.
+  [[ "$output" != *"unknown section-name"* ]]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 2b: helper applies lazy-empty discipline (empty stories: [])
+# ---------------------------------------------------------------------------
+
+@test "rfc-stories-extension: helper does not reject empty stories: [] (atomic-RFC JTBD-101 friction guard)" {
+  # Atomic RFC ships with stories: []; the helper must not reject this
+  # shape (it represents a legitimate atomic-fix-adopter RFC per
+  # ADR-060 line 262 JTBD-101 friction guard).
+  cat > docs/rfcs/RFC-002-atomic.proposed.md <<'EOF'
+---
+status: proposed
+rfc-id: atomic
+reported: 2026-05-12
+decision-makers: [Test]
+problems: [P170]
+adrs: []
+jtbd: []
+stories: []
+---
+
+# RFC-002: Atomic RFC
+EOF
+  run bash "$HELPER" docs/rfcs/RFC-002-atomic.proposed.md Stories
+  [[ "$output" != *"unknown section-name"* ]]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 3: capture-rfc + manage-rfc SKILL.md document the extension
+# ---------------------------------------------------------------------------
+
+@test "rfc-stories-extension: capture-rfc SKILL.md names --stories flag" {
+  run grep -E '\-\-stories STORY-' "$CAPTURE_RFC"
+  [ "$status" -eq 0 ]
+}
+
+@test "rfc-stories-extension: capture-rfc SKILL.md frontmatter template includes stories field" {
+  run grep -E '^stories:' "$CAPTURE_RFC"
+  [ "$status" -eq 0 ]
+}
+
+@test "rfc-stories-extension: manage-rfc SKILL.md invokes update-rfc-references-section.sh with Stories" {
+  # The forward-trace contract on every transition needs the helper call
+  # in the SKILL body. Behavioural assertion on the presence of the
+  # load-bearing call path; without it, manage-rfc transitions would
+  # silently leave the body section stale.
+  run grep -E 'update-rfc-references-section\.sh.*Stories' "$MANAGE_RFC"
+  [ "$status" -eq 0 ]
+}

package/scripts/test/update-problem-references-section.bats

@@ -0,0 +1,195 @@
+#!/usr/bin/env bats
+
+# P170 / Phase 2 Slice 2 — behavioural fixture for the generalised
+# update-problem-references-section.sh helper. Covers polymorphic
+# extraction (HTML data attributes for Story Maps; markdown frontmatter
+# for Stories + RFCs) feeding a uniform markdown-row render into the
+# target problem ticket's ## <section-name> section. Per ADR-060
+# § Phase 2 encoding amendment 2026-05-12 architect finding 4: helper
+# body MUST NOT carry per-section-name branching; section-name is a
+# positional argument; per-extension dispatch is the only branch.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  SCRIPT="$REPO_ROOT/packages/itil/scripts/update-problem-references-section.sh"
+
+  # Build an isolated workspace mirroring the docs layout.
+  WORKSPACE="$(mktemp -d)"
+  cd "$WORKSPACE"
+  mkdir -p docs/problems/open docs/rfcs docs/story-maps/in-progress docs/stories/accepted
+
+  # Sample problem ticket
+  cat > docs/problems/open/200-sample-problem.md <<'EOF'
+# Problem 200: Sample problem ticket
+
+**Status**: Open
+**Reported**: 2026-05-12
+
+## Description
+
+Sample description.
+
+## Related
+
+Sibling refs.
+EOF
+
+  # Sample RFC tracing problem 200
+  cat > docs/rfcs/RFC-100-sample-rfc.in-progress.md <<'EOF'
+---
+status: in-progress
+rfc-id: sample-rfc
+problems: [P200]
+adrs: []
+jtbd: []
+---
+
+# RFC-100: Sample RFC
+EOF
+
+  # Sample HTML story map tracing problem 200
+  cat > docs/story-maps/in-progress/STORY-MAP-050-sample-map.html <<'EOF'
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>STORY-MAP-050: Sample map</title>
+  <meta name="story-map-id" content="STORY-MAP-050">
+  <meta name="status" content="in-progress">
+  <meta name="problems" content="P200">
+  <meta name="rfcs" content="RFC-100">
+  <meta name="jtbd" content="JTBD-008">
+</head>
+<body>
+  <h1>STORY-MAP-050: Sample map</h1>
+</body>
+</html>
+EOF
+
+  # Sample markdown story tracing problem 200
+  cat > docs/stories/accepted/STORY-300-sample-story.md <<'EOF'
+---
+status: accepted
+story-id: sample-story
+problems: [P200]
+jtbd: [JTBD-008]
+rfcs: [RFC-100]
+story-maps: [STORY-MAP-050]
+estimated-effort: M
+---
+
+# STORY-300: Sample story
+EOF
+}
+
+teardown() {
+  rm -rf "$WORKSPACE"
+}
+
+@test "helper: script exists and is executable" {
+  [ -x "$SCRIPT" ]
+}
+
+@test "helper: requires problem-file argument; bare invocation halts" {
+  run bash "$SCRIPT"
+  [ "$status" -ne 0 ]
+}
+
+@test "helper: requires section-name argument" {
+  run bash "$SCRIPT" docs/problems/open/200-sample-problem.md
+  [ "$status" -ne 0 ]
+}
+
+@test "helper: refresh ## RFCs section from docs/rfcs/*.md frontmatter (markdown-extraction path)" {
+  cd "$WORKSPACE"
+  run bash "$SCRIPT" docs/problems/open/200-sample-problem.md RFCs
+  [ "$status" -eq 0 ]
+  grep -q '^## RFCs$' docs/problems/open/200-sample-problem.md
+  grep -q 'RFC-100' docs/problems/open/200-sample-problem.md
+}
+
+@test "helper: refresh ## Story Maps section from docs/story-maps/*.html data attributes (HTML-extraction path)" {
+  cd "$WORKSPACE"
+  run bash "$SCRIPT" docs/problems/open/200-sample-problem.md "Story Maps"
+  [ "$status" -eq 0 ]
+  grep -q '^## Story Maps$' docs/problems/open/200-sample-problem.md
+  grep -q 'STORY-MAP-050' docs/problems/open/200-sample-problem.md
+}
+
+@test "helper: refresh ## Stories section from docs/stories/*.md frontmatter (markdown-extraction path)" {
+  cd "$WORKSPACE"
+  run bash "$SCRIPT" docs/problems/open/200-sample-problem.md Stories
+  [ "$status" -eq 0 ]
+  grep -q '^## Stories$' docs/problems/open/200-sample-problem.md
+  grep -q 'STORY-300' docs/problems/open/200-sample-problem.md
+}
+
+@test "helper: lazy-empty — section removed entirely when no traces match" {
+  cd "$WORKSPACE"
+  # Create a problem ticket nothing references
+  cat > docs/problems/open/201-unreferenced-problem.md <<'EOF'
+# Problem 201: Unreferenced
+
+**Status**: Open
+
+## Related
+
+Some related content.
+
+## Story Maps
+
+| ID | Title |
+|----|-------|
+| STORY-MAP-999 | stale entry |
+EOF
+  run bash "$SCRIPT" docs/problems/open/201-unreferenced-problem.md "Story Maps"
+  [ "$status" -eq 0 ]
+  ! grep -q '^## Story Maps$' docs/problems/open/201-unreferenced-problem.md
+}
+
+@test "helper: idempotent — running twice produces no change on second invocation" {
+  cd "$WORKSPACE"
+  bash "$SCRIPT" docs/problems/open/200-sample-problem.md RFCs
+  local first_hash
+  first_hash=$(md5 -q docs/problems/open/200-sample-problem.md 2>/dev/null || md5sum docs/problems/open/200-sample-problem.md | cut -d' ' -f1)
+  bash "$SCRIPT" docs/problems/open/200-sample-problem.md RFCs
+  local second_hash
+  second_hash=$(md5 -q docs/problems/open/200-sample-problem.md 2>/dev/null || md5sum docs/problems/open/200-sample-problem.md | cut -d' ' -f1)
+  [ "$first_hash" = "$second_hash" ]
+}
+
+@test "helper: HTML path uses literal data-attribute grep (NOT inline-style match)" {
+  # Architect finding 5 (Prohibition reinforcement): the helper MUST
+  # grep on `<meta name="problems" content="...">` literal, not on any
+  # `style=` attribute. Verify by injecting a fake inline-style on a
+  # data-bearing element and asserting the helper's extraction is
+  # unaffected (the prohibition is enforced separately by a doc-lint
+  # bats; this test asserts the helper's parsing is style-agnostic).
+  cd "$WORKSPACE"
+  # The fixture's HTML map already lacks any `style=""` — that's the
+  # canonical shape. The helper must extract the same set whether the
+  # map has style or not. Adding a benign body-level style to the
+  # fixture (NOT on a data-bearing element) and re-running the helper
+  # must yield the same Story Maps section.
+  bash "$SCRIPT" docs/problems/open/200-sample-problem.md "Story Maps"
+  local first_body
+  first_body=$(grep -A 5 '^## Story Maps$' docs/problems/open/200-sample-problem.md)
+  # Inject benign body-level style — NOT on a data-bearing element
+  sed -i.bak 's|<body>|<body style="font-family: sans-serif">|' docs/story-maps/in-progress/STORY-MAP-050-sample-map.html
+  rm -f docs/story-maps/in-progress/STORY-MAP-050-sample-map.html.bak
+  bash "$SCRIPT" docs/problems/open/200-sample-problem.md "Story Maps"
+  local second_body
+  second_body=$(grep -A 5 '^## Story Maps$' docs/problems/open/200-sample-problem.md)
+  [ "$first_body" = "$second_body" ]
+}
+
+@test "helper: body does NOT contain a per-section-name branch (architect finding 4)" {
+  # Structural test (tdd-review: structural-permitted —
+  # justification: P176 SKILL.md I-invariant harness gap is the
+  # canonical pattern for asserting no-branching contracts via
+  # source grep; behavioural enforcement awaits the master harness
+  # at P012). Asserts the helper body does NOT carry a literal
+  # `case "$section_name"` or `if [ "$section_name" = "..." ]`
+  # branch keyed on the section-name value.
+  ! grep -E 'case[[:space:]]+"\$\{?section[_-]?name\}?"|if[[:space:]]+\[[[:space:]]+"\$\{?section[_-]?name\}?"[[:space:]]+=' "$SCRIPT"
+}

package/scripts/test/update-references-section-sibling-helpers.bats

@@ -0,0 +1,80 @@
+#!/usr/bin/env bats
+
+# P170 / Phase 2 Slice 2b — sanity bats for the 3 sibling helpers
+# (update-rfc-references-section.sh, update-jtbd-references-section.sh,
+# update-story-references-section.sh). Behavioural coverage of the
+# polymorphism is asserted by the comprehensive Slice 2a bats fixture
+# at update-problem-references-section.bats; this fixture asserts
+# existence + executable + arg-validation + structural no-branching
+# guard for the 3 siblings, deferring full behavioural coverage to
+# follow-on slice when the siblings are wired into consumer skills.
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  RFC_HELPER="$REPO_ROOT/packages/itil/scripts/update-rfc-references-section.sh"
+  JTBD_HELPER="$REPO_ROOT/packages/itil/scripts/update-jtbd-references-section.sh"
+  STORY_HELPER="$REPO_ROOT/packages/itil/scripts/update-story-references-section.sh"
+}
+
+@test "rfc-helper: exists and is executable" {
+  [ -x "$RFC_HELPER" ]
+}
+
+@test "rfc-helper: requires rfc-file arg" {
+  run bash "$RFC_HELPER"
+  [ "$status" -ne 0 ]
+}
+
+@test "rfc-helper: requires section-name arg" {
+  local tmp
+  tmp="$(mktemp)"
+  run bash "$RFC_HELPER" "$tmp"
+  [ "$status" -ne 0 ]
+  rm -f "$tmp"
+}
+
+@test "rfc-helper: body has no per-section-name branch" {
+  ! grep -E 'case[[:space:]]+"\$\{?section[_-]?name\}?"|if[[:space:]]+\[[[:space:]]+"\$\{?section[_-]?name\}?"[[:space:]]+=' "$RFC_HELPER"
+}
+
+@test "jtbd-helper: exists and is executable" {
+  [ -x "$JTBD_HELPER" ]
+}
+
+@test "jtbd-helper: requires jtbd-file arg" {
+  run bash "$JTBD_HELPER"
+  [ "$status" -ne 0 ]
+}
+
+@test "jtbd-helper: requires section-name arg" {
+  local tmp
+  tmp="$(mktemp)"
+  run bash "$JTBD_HELPER" "$tmp"
+  [ "$status" -ne 0 ]
+  rm -f "$tmp"
+}
+
+@test "jtbd-helper: body has no per-section-name branch" {
+  ! grep -E 'case[[:space:]]+"\$\{?section[_-]?name\}?"|if[[:space:]]+\[[[:space:]]+"\$\{?section[_-]?name\}?"[[:space:]]+=' "$JTBD_HELPER"
+}
+
+@test "story-helper: exists and is executable" {
+  [ -x "$STORY_HELPER" ]
+}
+
+@test "story-helper: requires story-file arg" {
+  run bash "$STORY_HELPER"
+  [ "$status" -ne 0 ]
+}
+
+@test "story-helper: requires section-name arg" {
+  local tmp
+  tmp="$(mktemp)"
+  run bash "$STORY_HELPER" "$tmp"
+  [ "$status" -ne 0 ]
+  rm -f "$tmp"
+}
+
+@test "story-helper: body has no per-section-name branch" {
+  ! grep -E 'case[[:space:]]+"\$\{?section[_-]?name\}?"|if[[:space:]]+\[[[:space:]]+"\$\{?section[_-]?name\}?"[[:space:]]+=' "$STORY_HELPER"
+}

package/scripts/test/working-the-problem-traversal.bats

@@ -0,0 +1,109 @@
+#!/usr/bin/env bats
+# Behavioural fixtures for the Phase 2 working-the-problem traversal
+# rewrite (P170 Phase 2 Slice 13 — ADR-060 lines 300-320).
+#
+# Per ADR-052: behavioural assertions on observable artefact + skill
+# contract state. The load-bearing surfaces under test are:
+#   1. manage-problem § Working a Problem → Known Error subsection names
+#      the four traversal steps (Fix Strategy → RFCs → stories: array →
+#      pick first not-done) + the two fallback paths (atomic-RFC empty
+#      stories: [], legacy no-RFC Fix Strategy).
+#   2. work-problem § Step 3 Known Error case names the same traversal
+#      and forward-points to manage-problem as the contract owner.
+#   3. The single-trailer vocabulary holds — `Refs: STORY-NNN` for
+#      story-decomposed work, `Refs: RFC-NNN` for atomic-RFC fallback,
+#      `Refs: P<NNN>` for legacy direct work (single trailer verb per
+#      ADR-060 line 307).
+#   4. Story auto-transition triggers are named: draft → in-progress
+#      on first non-capture commit; in-progress → done on
+#      all-criteria-ticked + linked RFC closed.
+#
+# @problem P170
+# @jtbd JTBD-008 (Decompose a Fix Into Coordinated Changes — traversal
+#                  operationalises the "first-class entity" Desired
+#                  Outcome at implementation time)
+# @jtbd JTBD-101 (atomic-fix-adopter friction guard — empty stories: []
+#                  falls back to per-RFC dispatch without friction)
+# @adr  ADR-060  (Problem-RFC-Story framework — working-the-problem
+#                  flow lines 300-320 + amendment 2026-05-10 nitpick N2
+#                  single-trailer vocabulary)
+# @adr  ADR-052  (Behavioural-tests-default)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../.." && pwd)"
+  MANAGE_PROBLEM="${REPO_ROOT}/packages/itil/skills/manage-problem/SKILL.md"
+  WORK_PROBLEM="${REPO_ROOT}/packages/itil/skills/work-problem/SKILL.md"
+}
+
+# ---------------------------------------------------------------------------
+# Surface 1: manage-problem § Working a Problem → Known Error names the
+# 4-step traversal (Fix Strategy → RFCs → stories: → pick first not-done)
+# ---------------------------------------------------------------------------
+
+@test "traversal: manage-problem names the Fix Strategy section extraction step" {
+  run grep -E 'Read the problem.*\#\# Fix Strategy.*RFC' "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+@test "traversal: manage-problem names the RFC frontmatter stories: array read step" {
+  run grep -E 'frontmatter stories:.*ORDERED|stories:.*array.*execution sequence' "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+@test "traversal: manage-problem names the pick-first-not-done filter (accepted or in-progress)" {
+  run grep -E 'accepted.*in-progress.*done.*draft|first story whose.*status is.*accepted' "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 2: manage-problem names BOTH fallback paths
+# ---------------------------------------------------------------------------
+
+@test "traversal: manage-problem names the atomic-RFC empty stories: [] fallback (JTBD-101 friction guard)" {
+  run grep -E 'atomic-RFC fallback|atomic RFC.*JTBD-101.*friction guard|stories: \[\].*atomic' "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+@test "traversal: manage-problem names the legacy no-RFC direct-implementation fallback" {
+  run grep -iE 'legacy direct-implementation|no-RFC.*legacy|no RFCs.*direct' "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 3: work-problem § Step 3 Known Error case forwards to manage-problem
+# ---------------------------------------------------------------------------
+
+@test "traversal: work-problem Step 3 Known Error case names the traversal chain" {
+  # The traversal description must include all four chain elements:
+  # Fix Strategy, RFCs, stories: array, pick first not-done.
+  run grep -iE 'Fix Strategy.*stories:.*pick first|traverse.*Fix Strategy.*RFC.*stories' "$WORK_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 4: Single-trailer vocabulary (per ADR-060 line 307 + N2 amendment)
+# ---------------------------------------------------------------------------
+
+@test "traversal: manage-problem names Refs: STORY-NNN trailer for story-decomposed work" {
+  run grep -E 'Refs: STORY-' "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+@test "traversal: manage-problem names Refs: RFC-NNN trailer for atomic-RFC fallback" {
+  run grep -E 'Refs: RFC-' "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Surface 5: Story auto-transition triggers
+# ---------------------------------------------------------------------------
+
+@test "traversal: manage-problem names the story draft → in-progress auto-transition trigger" {
+  run grep -iE 'draft.*in-progress.*first.*commit|auto-transitions.*draft.*in-progress' "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}
+
+@test "traversal: manage-problem names the in-progress → done auto-transition trigger (criteria ticked + RFC closed)" {
+  run grep -iE 'in-progress.*done.*acceptance-criteria.*ticked|ALL acceptance-criteria.*RFC reaches.*closed' "$MANAGE_PROBLEM"
+  [ "$status" -eq 0 ]
+}