@windyroad/itil 0.25.0 → 0.26.0

package/scripts/test/reconcile-rfcs.bats

@@ -0,0 +1,433 @@
+#!/usr/bin/env bats
+
+# @problem P170 — docs/rfcs/README.md needs a sibling drift-detector to
+# reconcile-readme.sh once `/wr-itil:capture-rfc` and `/wr-itil:manage-rfc`
+# start writing RFC files. P170 Slice 3 task B5.T6 ships this script;
+# B5.T7 ships the `wr-itil-reconcile-rfcs` $PATH shim per ADR-049.
+#
+# Contract: `reconcile-rfcs.sh [<rfcs-dir>]` is a diagnose-only mechanical
+# drift detector. It reads `<rfcs-dir>/RFC-<NNN>-*.<status>.md` files
+# (default `docs/rfcs`), parses the WSJF Rankings + Verification Queue
+# + Closed tables in `<rfcs-dir>/README.md`, and reports each
+# disagreement between README claim and filesystem ground truth.
+#
+# Exit codes:
+#   0 = clean (README matches filesystem for every parsed row)
+#   1 = drift detected (structured diff to stdout, one row per drift)
+#   2 = parse error (README missing or malformed beyond recovery)
+#
+# Drift line format per ADR-038 progressive-disclosure budget (≤150 bytes/row):
+#   DRIFT    RFC-<NNN> wsjf-rankings: claims=open actual=<status>
+#   MISSING  RFC-<NNN> wsjf-rankings: actual=<status>
+#   STALE    RFC-<NNN> verification-queue: actual=<status>
+#   MISMATCH RFC-<NNN> closed: actual=<status>
+#
+# Sibling to packages/itil/scripts/reconcile-readme.sh (P118) — same
+# parse + diff structure applied at the RFC tier instead of the
+# problems tier.
+#
+# @jtbd JTBD-008 (Decompose a Fix Into Coordinated Changes — RFC ranking
+# integrity supports the capture-time decomposition surface)
+# @jtbd JTBD-006 (Progress the Backlog While I'm Away — orchestrators
+# composing with RFC-level WSJF rankings need them to match disk truth)
+#
+# Cross-reference:
+#   P170: docs/problems/170-...open.md
+#   ADR-060 (Problem-RFC-Story framework — Phase 1 item 5)
+#   ADR-049 (Plugin script resolution via bin/ on PATH — paired bin shim)
+#   ADR-005 — Plugin testing strategy (script-level bats governance)
+
+setup() {
+  SCRIPTS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SCRIPT="$SCRIPTS_DIR/reconcile-rfcs.sh"
+  FIXTURE_DIR="$(mktemp -d)"
+  PROBLEMS_DIR="$(mktemp -d)"
+}
+
+teardown() {
+  rm -rf "$FIXTURE_DIR" "$PROBLEMS_DIR"
+}
+
+# Helper: write a minimal valid RFC README to fixture dir.
+write_minimal_readme() {
+  local body="$1"
+  cat > "$FIXTURE_DIR/README.md" <<EOF
+# RFC Backlog
+
+> Last reviewed: 2026-05-05
+
+## Status
+
+(intro)
+
+## RFC Rankings
+
+| WSJF | ID | Title | Severity | Status | Effort | Reported |
+|------|-----|-------|----------|--------|--------|----------|
+${body}
+
+## Verification Queue
+
+| ID | Title | Released | Verification check |
+|----|-------|----------|--------------------|
+
+## Closed
+
+| ID | Title | Closed | Driving problems |
+|----|-------|--------|------------------|
+EOF
+}
+
+# Helper: write an RFC ticket file with the given status suffix.
+# Optional 4th arg overrides the `problems:` list (default `[P168]`).
+write_rfc() {
+  local id="$1" slug="$2" status="$3"
+  local problems="${4:-[P168]}"
+  cat > "$FIXTURE_DIR/RFC-${id}-${slug}.${status}.md" <<EOF
+---
+status: ${status}
+rfc-id: ${slug}
+reported: 2026-05-05
+decision-makers: [test]
+problems: ${problems}
+---
+
+# RFC-${id}: ${slug}
+
+stub
+EOF
+}
+
+# Helper: write a problem ticket file with optional `## RFCs` table rows.
+# Args: <pid-num> <slug> <status> <rfcs-rows-block>
+# rfcs-rows-block is the markdown rows (already pipe-formatted) inserted under
+# the `## RFCs` table header — pass an empty string to omit the section
+# entirely (lazy-empty discipline per JTBD-101 atomic-fix-adopter friction guard).
+write_problem() {
+  local num="$1" slug="$2" status="$3" rfcs_rows="${4:-}"
+  local file="$PROBLEMS_DIR/${num}-${slug}.${status}.md"
+  cat > "$file" <<EOF
+# Problem ${num}: ${slug}
+
+**Status**: ${status}
+
+## Description
+
+stub
+
+## Related
+
+stub
+EOF
+  if [ -n "$rfcs_rows" ]; then
+    cat >> "$file" <<EOF
+
+## RFCs
+
+| RFC | Status | Title |
+|-----|--------|-------|
+${rfcs_rows}
+EOF
+  fi
+}
+
+# ── Existence + executable ──────────────────────────────────────────────────
+
+@test "reconcile-rfcs: script exists" {
+  [ -f "$SCRIPT" ]
+}
+
+@test "reconcile-rfcs: script is executable" {
+  [ -x "$SCRIPT" ]
+}
+
+# ── Parse-error path ────────────────────────────────────────────────────────
+
+@test "reconcile-rfcs: missing README → exit 2 (parse error)" {
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 2 ]
+  [[ "$output" == *"PARSE_ERROR"* ]]
+}
+
+@test "reconcile-rfcs: README without RFC Rankings header → exit 2" {
+  cat > "$FIXTURE_DIR/README.md" <<'EOF'
+# RFC Backlog
+
+(no Rankings section)
+EOF
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 2 ]
+}
+
+# ── Clean path ──────────────────────────────────────────────────────────────
+
+@test "reconcile-rfcs: empty filesystem + empty README → exit 0 (clean)" {
+  write_minimal_readme ""
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 0 ]
+}
+
+@test "reconcile-rfcs: README and filesystem agree on one proposed RFC → exit 0" {
+  write_rfc "001" "foo" "proposed"
+  write_minimal_readme "| 1.5 | RFC-001 | foo | 3 Med | Proposed | M | 2026-05-05 |"
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 0 ]
+}
+
+@test "reconcile-rfcs: accepted RFC matches Rankings (proposed/accepted/in-progress are all WSJF queue)" {
+  write_rfc "002" "bar" "accepted"
+  write_minimal_readme "| 2.0 | RFC-002 | bar | 4 High | Accepted | M | 2026-05-05 |"
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 0 ]
+}
+
+@test "reconcile-rfcs: in-progress RFC matches Rankings" {
+  write_rfc "003" "baz" "in-progress"
+  write_minimal_readme "| 1.5 | RFC-003 | baz | 3 Med | In-Progress | M | 2026-05-05 |"
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 0 ]
+}
+
+# ── Drift paths ─────────────────────────────────────────────────────────────
+
+@test "reconcile-rfcs: filesystem RFC missing from README → MISSING drift" {
+  write_rfc "004" "qux" "proposed"
+  write_minimal_readme ""
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"MISSING  RFC-004"* ]]
+  [[ "$output" == *"actual=proposed"* ]]
+}
+
+@test "reconcile-rfcs: README claims RFC in Rankings but filesystem says verifying → DRIFT" {
+  write_rfc "005" "blip" "verifying"
+  write_minimal_readme "| 0 | RFC-005 | blip | 3 Med | Proposed | M | 2026-05-05 |"
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"DRIFT    RFC-005"* ]]
+  [[ "$output" == *"actual=verifying"* ]]
+}
+
+@test "reconcile-rfcs: verifying RFC missing from Verification Queue → MISSING in queue" {
+  write_rfc "006" "ver" "verifying"
+  write_minimal_readme ""
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"MISSING  RFC-006"* ]]
+  [[ "$output" == *"verification-queue"* ]]
+}
+
+@test "reconcile-rfcs: closed RFC listed in Verification Queue → STALE" {
+  write_rfc "007" "stale" "closed"
+  cat > "$FIXTURE_DIR/README.md" <<'EOF'
+# RFC Backlog
+
+## RFC Rankings
+
+| WSJF | ID | Title | Severity | Status | Effort | Reported |
+|------|-----|-------|----------|--------|--------|----------|
+
+## Verification Queue
+
+| ID | Title | Released | Verification check |
+|----|-------|----------|--------------------|
+| RFC-007 | stale | 2026-05-05 | check |
+
+## Closed
+
+| ID | Title | Closed | Driving problems |
+|----|-------|--------|------------------|
+EOF
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"STALE    RFC-007"* ]]
+  [[ "$output" == *"actual=closed"* ]]
+}
+
+@test "reconcile-rfcs: open-shape RFC listed in Closed section → MISMATCH" {
+  write_rfc "008" "mis" "proposed"
+  cat > "$FIXTURE_DIR/README.md" <<'EOF'
+# RFC Backlog
+
+## RFC Rankings
+
+| WSJF | ID | Title | Severity | Status | Effort | Reported |
+|------|-----|-------|----------|--------|--------|----------|
+| 1.5 | RFC-008 | mis | 3 Med | Proposed | M | 2026-05-05 |
+
+## Verification Queue
+
+| ID | Title | Released | Verification check |
+|----|-------|----------|--------------------|
+
+## Closed
+
+| ID | Title | Closed | Driving problems |
+|----|-------|--------|------------------|
+| RFC-008 | mis | 2026-05-05 | P168 |
+EOF
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"MISMATCH RFC-008"* ]]
+}
+
+# ── Output format ───────────────────────────────────────────────────────────
+
+@test "reconcile-rfcs: drift output is per-line and ≤150 bytes per line (ADR-038)" {
+  write_rfc "010" "byte-budget-test-with-an-extra-long-slug-to-stress-row-width" "proposed"
+  write_minimal_readme ""
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 1 ]
+  while IFS= read -r line; do
+    [ ${#line} -le 150 ] || { echo "row exceeds 150 bytes: '$line' (${#line} bytes)"; return 1; }
+  done <<< "$output"
+}
+
+@test "reconcile-rfcs: stable sort order (deterministic for snapshot diffing)" {
+  write_rfc "020" "second" "proposed"
+  write_rfc "010" "first" "proposed"
+  write_minimal_readme ""
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 1 ]
+  # Both should appear; lower ID first per sort.
+  first_line=$(echo "$output" | head -1)
+  second_line=$(echo "$output" | sed -n '2p')
+  [[ "$first_line" == *"RFC-010"* ]]
+  [[ "$second_line" == *"RFC-020"* ]]
+}
+
+# ── Reverse-trace drift detection (B5.T8 — closes ADR-060 Confirmation criterion 3) ──
+#
+# Per architect Q5 verdict: when a problems-dir is provided as second positional
+# arg, reconcile-rfcs.sh extends to detect drift in the `## RFCs` reverse-trace
+# section on driving problem tickets. Three new drift conditions:
+#
+#   MISSING_REVERSE_TRACE  RFC-<NNN> in P<NNN> ## RFCs
+#     RFC frontmatter `problems:` claims P<NNN> but P<NNN>'s `## RFCs` table
+#     does not list RFC-<NNN>.
+#
+#   STALE_REVERSE_TRACE    RFC-<NNN> in P<NNN> ## RFCs
+#     P<NNN>'s `## RFCs` table lists RFC-<NNN> but the RFC's frontmatter
+#     `problems:` no longer claims P<NNN>.
+#
+#   STATUS_MISMATCH        RFC-<NNN> in P<NNN> ## RFCs claims=<X> actual=<Y>
+#     P<NNN>'s `## RFCs` row claims status <X> but RFC's filesystem suffix is <Y>.
+#
+# Backward-compat: when no problems-dir arg is supplied (or the dir is absent),
+# the script preserves the single-arg behaviour from B5.T6 (existing 18 cases
+# above pass unchanged).
+
+@test "reverse-trace: clean — RFC traces P, P has matching ## RFCs row → no drift" {
+  write_rfc "001" "foo" "accepted"
+  write_minimal_readme "| 2.0 | RFC-001 | foo | 3 Med | Accepted | M | 2026-05-05 |"
+  write_problem "168" "p168" "verifying" "| RFC-001 | accepted | foo |"
+  run bash "$SCRIPT" "$FIXTURE_DIR" "$PROBLEMS_DIR"
+  [ "$status" -eq 0 ]
+}
+
+@test "reverse-trace: MISSING_REVERSE_TRACE — RFC claims P, P has no ## RFCs section" {
+  write_rfc "001" "foo" "accepted"
+  write_minimal_readme "| 2.0 | RFC-001 | foo | 3 Med | Accepted | M | 2026-05-05 |"
+  write_problem "168" "p168" "verifying" ""
+  run bash "$SCRIPT" "$FIXTURE_DIR" "$PROBLEMS_DIR"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"MISSING_REVERSE_TRACE"* ]]
+  [[ "$output" == *"RFC-001"* ]]
+  [[ "$output" == *"P168"* ]]
+}
+
+@test "reverse-trace: MISSING_REVERSE_TRACE — RFC claims P, P has ## RFCs but RFC absent from table" {
+  write_rfc "001" "foo" "accepted"
+  write_rfc "002" "bar" "proposed"
+  write_minimal_readme "| 2.0 | RFC-001 | foo | 3 Med | Accepted | M | 2026-05-05 |"
+  # P168 has ## RFCs section listing RFC-002 but not RFC-001
+  write_problem "168" "p168" "verifying" "| RFC-002 | proposed | bar |"
+  run bash "$SCRIPT" "$FIXTURE_DIR" "$PROBLEMS_DIR"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"MISSING_REVERSE_TRACE"* ]]
+  [[ "$output" == *"RFC-001"* ]]
+  [[ "$output" == *"P168"* ]]
+}
+
+@test "reverse-trace: STALE_REVERSE_TRACE — P lists RFC, RFC frontmatter no longer claims P" {
+  # RFC-001 traces P169 only; P168's ## RFCs table still lists RFC-001
+  write_rfc "001" "foo" "accepted" "[P169]"
+  write_minimal_readme "| 2.0 | RFC-001 | foo | 3 Med | Accepted | M | 2026-05-05 |"
+  write_problem "168" "p168" "verifying" "| RFC-001 | accepted | foo |"
+  write_problem "169" "p169" "open" "| RFC-001 | accepted | foo |"
+  run bash "$SCRIPT" "$FIXTURE_DIR" "$PROBLEMS_DIR"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"STALE_REVERSE_TRACE"* ]]
+  [[ "$output" == *"RFC-001"* ]]
+  [[ "$output" == *"P168"* ]]
+}
+
+@test "reverse-trace: STATUS_MISMATCH — P ## RFCs row claims status X but RFC suffix is Y" {
+  write_rfc "001" "foo" "in-progress"
+  write_minimal_readme "| 1.5 | RFC-001 | foo | 3 Med | In-Progress | M | 2026-05-05 |"
+  # P168's ## RFCs table claims RFC-001 is `accepted` but the on-disk suffix is in-progress
+  write_problem "168" "p168" "verifying" "| RFC-001 | accepted | foo |"
+  run bash "$SCRIPT" "$FIXTURE_DIR" "$PROBLEMS_DIR"
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"STATUS_MISMATCH"* ]]
+  [[ "$output" == *"RFC-001"* ]]
+  [[ "$output" == *"P168"* ]]
+  [[ "$output" == *"claims=accepted"* ]]
+  [[ "$output" == *"actual=in-progress"* ]]
+}
+
+@test "reverse-trace: backward-compat — single-arg invocation skips reverse-trace check" {
+  # No problems-dir → existing 18-case behaviour
+  write_rfc "001" "foo" "accepted"
+  write_minimal_readme "| 2.0 | RFC-001 | foo | 3 Med | Accepted | M | 2026-05-05 |"
+  run bash "$SCRIPT" "$FIXTURE_DIR"
+  [ "$status" -eq 0 ]
+}
+
+@test "reverse-trace: problems-dir absent on disk → reverse-trace check skipped (warn-only)" {
+  write_rfc "001" "foo" "accepted"
+  write_minimal_readme "| 2.0 | RFC-001 | foo | 3 Med | Accepted | M | 2026-05-05 |"
+  rm -rf "$PROBLEMS_DIR"
+  run bash "$SCRIPT" "$FIXTURE_DIR" "$PROBLEMS_DIR"
+  # absent problems-dir does not promote to drift; treat as backward-compat
+  [ "$status" -eq 0 ]
+}
+
+@test "reverse-trace: RFC has no problems frontmatter → reverse-trace skipped for that RFC" {
+  # Empty problems list; RFC-001 frontmatter has no claims to validate
+  write_rfc "001" "foo" "accepted" "[]"
+  write_minimal_readme "| 2.0 | RFC-001 | foo | 3 Med | Accepted | M | 2026-05-05 |"
+  write_problem "168" "p168" "verifying" ""
+  run bash "$SCRIPT" "$FIXTURE_DIR" "$PROBLEMS_DIR"
+  [ "$status" -eq 0 ]
+}
+
+@test "reverse-trace: drift output is per-line and ≤150 bytes per line (ADR-038)" {
+  write_rfc "001" "byte-budget-test-with-an-extra-long-slug-to-stress-row-width" "accepted"
+  write_minimal_readme "| 2.0 | RFC-001 | byte-budget-test-with-an-extra-long-slug-to-stress-row-width | 3 Med | Accepted | M | 2026-05-05 |"
+  write_problem "168" "p168" "verifying" ""
+  run bash "$SCRIPT" "$FIXTURE_DIR" "$PROBLEMS_DIR"
+  [ "$status" -eq 1 ]
+  while IFS= read -r line; do
+    [ ${#line} -le 150 ] || { echo "row exceeds 150 bytes: '$line' (${#line} bytes)"; return 1; }
+  done <<< "$output"
+}
+
+# ── ADR-049 bin shim contract ───────────────────────────────────────────────
+
+@test "wr-itil-reconcile-rfcs bin shim exists" {
+  BIN_SHIM="$(cd "$SCRIPTS_DIR/../bin" && pwd)/wr-itil-reconcile-rfcs"
+  [ -f "$BIN_SHIM" ]
+}
+
+@test "wr-itil-reconcile-rfcs bin shim is executable" {
+  BIN_SHIM="$(cd "$SCRIPTS_DIR/../bin" && pwd)/wr-itil-reconcile-rfcs"
+  [ -x "$BIN_SHIM" ]
+}
+
+@test "wr-itil-reconcile-rfcs bin shim dispatches to canonical script" {
+  BIN_SHIM="$(cd "$SCRIPTS_DIR/../bin" && pwd)/wr-itil-reconcile-rfcs"
+  write_minimal_readme ""
+  run bash "$BIN_SHIM" "$FIXTURE_DIR"
+  [ "$status" -eq 0 ]
+}

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

@@ -0,0 +1,242 @@
+#!/usr/bin/env bats
+
+# @problem P170 — Slice 3 second half (B5.T8): the auto-maintained
+# `## RFCs` section refresh contract on problem ticket bodies. Library
+# helper called inline by /wr-itil:capture-rfc Step 6 and
+# /wr-itil:manage-rfc Step 7+9 so the cross-tier reverse-trace stays
+# current at every commit per ADR-014 single-commit grain.
+#
+# Behavioural per ADR-052: assert on file output state (idempotent
+# table; lazy empty discipline; placement) — not on script source
+# content (no structural greps per P081).
+#
+# Contract (per architect Q3 verdict):
+#   - Section position: between `## Related` and `## Fix Released`
+#     (or at EOF if neither sentinel present).
+#   - Table format: `| RFC | Status | Title |` with separator row.
+#   - Sort: RFC ID asc.
+#   - Lazy empty: zero traced RFCs → section absent (no header,
+#     no `_None._` prose).
+#   - Idempotent: re-run over current state is a no-op (cmp -s holds).
+#
+# @adr ADR-060 (Phase 1 item 10 + Confirmation criterion 3)
+# @adr ADR-052 (behavioural bats default)
+# @adr ADR-022 (`## Fix Released` is the trailing closure section)
+# @jtbd JTBD-008 (Decompose a Fix Into Coordinated Changes — reverse
+#   trace surface)
+# @jtbd JTBD-101 (atomic-fix-adopter friction guard — lazy empty)
+
+setup() {
+  SCRIPTS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HELPER="$SCRIPTS_DIR/update-problem-rfcs-section.sh"
+  RFCS_DIR="$(mktemp -d)"
+  PROBLEMS_DIR="$(mktemp -d)"
+}
+
+teardown() {
+  rm -rf "$RFCS_DIR" "$PROBLEMS_DIR"
+}
+
+write_rfc() {
+  local id="$1" slug="$2" status="$3"
+  local problems="${4:-[P168]}"
+  cat > "$RFCS_DIR/RFC-${id}-${slug}.${status}.md" <<EOF
+---
+status: ${status}
+rfc-id: ${slug}
+reported: 2026-05-05
+decision-makers: [test]
+problems: ${problems}
+---
+
+# RFC-${id}: ${slug}
+
+stub
+EOF
+}
+
+write_problem() {
+  local num="$1" slug="$2" trailing="${3:-}"
+  local file="$PROBLEMS_DIR/${num}-${slug}.open.md"
+  cat > "$file" <<EOF
+# Problem ${num}: ${slug}
+
+**Status**: Open
+
+## Description
+
+stub
+
+## Related
+
+stub
+EOF
+  if [ -n "$trailing" ]; then
+    printf '\n%s\n' "$trailing" >> "$file"
+  fi
+  echo "$file"
+}
+
+# ── Existence + executable ──────────────────────────────────────────────────
+
+@test "helper exists" {
+  [ -f "$HELPER" ]
+}
+
+@test "helper is executable" {
+  [ -x "$HELPER" ]
+}
+
+# ── Lazy-empty discipline (JTBD-101 friction guard) ─────────────────────────
+
+@test "no RFCs trace → section absent (lazy empty)" {
+  pf=$(write_problem "168" "p168")
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  ! grep -q '^## RFCs' "$pf"
+}
+
+@test "no RFCs trace and section exists → section removed" {
+  # A pre-existing stale section gets cleaned out when zero RFCs claim.
+  pf=$(write_problem "168" "p168" $'## RFCs\n\n| RFC | Status | Title |\n|-----|--------|-------|\n| RFC-001 | accepted | foo |')
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  ! grep -q '^## RFCs' "$pf"
+}
+
+# ── Single-RFC trace ────────────────────────────────────────────────────────
+
+@test "one RFC traces P → section appears with one row" {
+  write_rfc "001" "foo" "accepted"
+  pf=$(write_problem "168" "p168")
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  grep -q '^## RFCs' "$pf"
+  grep -q '| RFC-001 | accepted | foo |' "$pf"
+}
+
+@test "table includes header + separator + data row" {
+  write_rfc "001" "foo" "accepted"
+  pf=$(write_problem "168" "p168")
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  grep -q '| RFC | Status | Title |' "$pf"
+  grep -q '|-----|--------|-------|' "$pf"
+  grep -q '| RFC-001 | accepted | foo |' "$pf"
+}
+
+# ── Multi-RFC trace + sort order ─────────────────────────────────────────────
+
+@test "multiple RFCs trace P → all rows present, sorted by RFC ID asc" {
+  write_rfc "002" "second" "proposed"
+  write_rfc "001" "first" "accepted"
+  pf=$(write_problem "168" "p168")
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  # Both rows present.
+  grep -q '| RFC-001 | accepted | first |' "$pf"
+  grep -q '| RFC-002 | proposed | second |' "$pf"
+  # RFC-001 appears before RFC-002.
+  rfc_001_line=$(grep -n '| RFC-001 |' "$pf" | head -1 | cut -d: -f1)
+  rfc_002_line=$(grep -n '| RFC-002 |' "$pf" | head -1 | cut -d: -f1)
+  [ "$rfc_001_line" -lt "$rfc_002_line" ]
+}
+
+# ── Idempotency ─────────────────────────────────────────────────────────────
+
+@test "re-running with no claim change is a no-op (idempotent)" {
+  write_rfc "001" "foo" "accepted"
+  pf=$(write_problem "168" "p168")
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  hash1=$(shasum "$pf" | cut -d' ' -f1)
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  hash2=$(shasum "$pf" | cut -d' ' -f1)
+  [ "$hash1" = "$hash2" ]
+}
+
+# ── Status update on existing row ────────────────────────────────────────────
+
+@test "RFC status changes (proposed → accepted) → table row reflects new status" {
+  write_rfc "001" "foo" "proposed"
+  pf=$(write_problem "168" "p168")
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  grep -q '| RFC-001 | proposed | foo |' "$pf"
+  # Now transition the RFC to accepted (simulate by renaming on disk).
+  mv "$RFCS_DIR/RFC-001-foo.proposed.md" "$RFCS_DIR/RFC-001-foo.accepted.md"
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  grep -q '| RFC-001 | accepted | foo |' "$pf"
+  # Old status should no longer be present for that RFC row.
+  ! grep -q '| RFC-001 | proposed |' "$pf"
+}
+
+# ── Re-trace add/remove ─────────────────────────────────────────────────────
+
+@test "RFC newly added trace → row appended" {
+  write_rfc "001" "foo" "accepted"
+  pf=$(write_problem "168" "p168")
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  grep -q '| RFC-001 |' "$pf"
+
+  # Add a second RFC traced to P168.
+  write_rfc "002" "bar" "proposed"
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  grep -q '| RFC-001 |' "$pf"
+  grep -q '| RFC-002 |' "$pf"
+}
+
+@test "RFC trace removed (frontmatter no longer claims P) → row drops" {
+  write_rfc "001" "foo" "accepted" "[P168]"
+  write_rfc "002" "bar" "proposed" "[P168]"
+  pf=$(write_problem "168" "p168")
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  grep -q '| RFC-001 |' "$pf"
+  grep -q '| RFC-002 |' "$pf"
+
+  # Re-trace RFC-002 to P169 only.
+  rm -f "$RFCS_DIR/RFC-002-bar.proposed.md"
+  write_rfc "002" "bar" "proposed" "[P169]"
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  grep -q '| RFC-001 |' "$pf"
+  ! grep -q '| RFC-002 |' "$pf"
+}
+
+# ── Section placement ───────────────────────────────────────────────────────
+
+@test "## RFCs section sits before ## Fix Released when present" {
+  write_rfc "001" "foo" "verifying"
+  pf=$(write_problem "168" "p168" $'## Fix Released\n\nReleased trailer prose.')
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  rfcs_line=$(grep -n '^## RFCs' "$pf" | head -1 | cut -d: -f1)
+  fix_released_line=$(grep -n '^## Fix Released' "$pf" | head -1 | cut -d: -f1)
+  [ "$rfcs_line" -lt "$fix_released_line" ]
+}
+
+@test "## RFCs section appears at EOF when no ## Fix Released section" {
+  write_rfc "001" "foo" "accepted"
+  pf=$(write_problem "168" "p168")
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  # ## RFCs is the last `## ` heading in the file.
+  last_section=$(grep -E '^## ' "$pf" | tail -1)
+  [[ "$last_section" == "## RFCs" ]]
+}
+
+# ── Multi-problem RFC composition ────────────────────────────────────────────
+
+@test "RFC tracing two problems updates both ## RFCs sections" {
+  write_rfc "001" "foo" "accepted" "[P168, P169]"
+  pf168=$(write_problem "168" "p168")
+  pf169=$(write_problem "169" "p169")
+  bash "$HELPER" "$pf168" "$RFCS_DIR"
+  bash "$HELPER" "$pf169" "$RFCS_DIR"
+  grep -q '| RFC-001 |' "$pf168"
+  grep -q '| RFC-001 |' "$pf169"
+}
+
+# ── ## Related preservation ─────────────────────────────────────────────────
+
+@test "existing ## Related section is preserved when ## RFCs is added" {
+  write_rfc "001" "foo" "accepted"
+  pf=$(write_problem "168" "p168")
+  bash "$HELPER" "$pf" "$RFCS_DIR"
+  grep -q '^## Related' "$pf"
+  grep -q '^## RFCs' "$pf"
+  related_line=$(grep -n '^## Related' "$pf" | head -1 | cut -d: -f1)
+  rfcs_line=$(grep -n '^## RFCs' "$pf" | head -1 | cut -d: -f1)
+  # ## Related comes before ## RFCs.
+  [ "$related_line" -lt "$rfcs_line" ]
+}