@windyroad/itil 0.47.12 → 0.47.14

package/skills/work-problems/test/work-problems-step-0d-outbound-responses-staleness-behavioural.bats

@@ -0,0 +1,174 @@
+#!/usr/bin/env bats
+
+# Step 0d behavioural fixture per P220 + ADR-062 § JTBD-006 driver:
+# work-problems pre-flights /wr-itil:check-upstream-responses when the
+# outbound-responses cache is stale or missing AND there exist local
+# tickets carrying `## Reported Upstream` back-link sections. The
+# staleness decision lives in
+# `packages/itil/lib/check-outbound-responses-staleness.sh::should_promote_outbound_responses_preflight`
+# so the SKILL.md Step 0d prose is a thin source-and-call wrapper
+# around a behaviorally-testable shell function (P081 / user feedback:
+# prefer behavioural over structural-grep tests).
+#
+# Cases covered (symmetric to Step 0b cases plus the back-link discovery
+# axis that replaces channels-config):
+#   1. No tickets with `## Reported Upstream` section → "no-back-link-tickets"
+#      (downstream-adopter non-obligation; analogue to no-channels-config).
+#   2. Back-link ticket present, cache absent → "first-run-cache-absent".
+#   3. Back-link ticket present, cache present, last_checked null → "first-run-last-checked-null".
+#   4. Back-link ticket present, cache fresh within TTL → "fresh-within-ttl".
+#   5. Back-link ticket present, cache older than TTL → "ttl-expiry" (with age + ttl in the reason).
+#   6. Custom ttl_seconds in cache honored (not hardcoded default).
+#   7. Missing ttl_seconds field defaults to 86400 (24h symmetric with inbound).
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  HELPER="$REPO_ROOT/packages/itil/lib/check-outbound-responses-staleness.sh"
+
+  FIXTURE="$(mktemp -d)"
+  mkdir -p "$FIXTURE/docs/problems"
+}
+
+teardown() {
+  rm -rf "$FIXTURE"
+}
+
+# Helper: write a back-link ticket fixture under docs/problems/.
+_write_backlink_ticket() {
+  local ticket_path="$1"
+  cat > "$ticket_path" <<'EOF'
+# Problem 999: example back-link fixture
+
+**Status**: Open
+
+## Description
+
+Fixture for Step 0d behavioural test.
+
+## Reported Upstream
+
+- **Repo**: example/upstream
+- **URL**: https://github.com/example/upstream/issues/999
+- **Filed**: 2026-06-08
+EOF
+}
+
+@test "helper exists at the contracted path" {
+  [ -f "$HELPER" ]
+}
+
+@test "case 1: no back-link tickets → no-back-link-tickets" {
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_outbound_responses_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "no-back-link-tickets" ]
+}
+
+@test "case 1b: tickets without ## Reported Upstream section → no-back-link-tickets" {
+  cat > "$FIXTURE/docs/problems/100-no-back-link.open.md" <<'EOF'
+# Problem 100: no upstream link
+
+## Description
+
+Local-only ticket.
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_outbound_responses_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "no-back-link-tickets" ]
+}
+
+@test "case 2: back-link ticket present, cache absent → first-run-cache-absent" {
+  _write_backlink_ticket "$FIXTURE/docs/problems/100-back-link.open.md"
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_outbound_responses_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "first-run-cache-absent" ]
+}
+
+@test "case 2b: back-link in per-state subdir layout (RFC-002) is discovered" {
+  mkdir -p "$FIXTURE/docs/problems/known-error"
+  _write_backlink_ticket "$FIXTURE/docs/problems/known-error/220-cadence-gap.md"
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_outbound_responses_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "first-run-cache-absent" ]
+}
+
+@test "case 3: cache present, last_checked null → first-run-last-checked-null" {
+  _write_backlink_ticket "$FIXTURE/docs/problems/100-back-link.open.md"
+  cat > "$FIXTURE/docs/problems/.outbound-responses-cache.json" <<'EOF'
+{ "last_checked": null, "tickets": {} }
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_outbound_responses_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "first-run-last-checked-null" ]
+}
+
+@test "case 4: cache fresh within TTL → fresh-within-ttl (silent-pass)" {
+  _write_backlink_ticket "$FIXTURE/docs/problems/100-back-link.open.md"
+  # last_checked 1 hour ago — well within 24h default TTL.
+  local recent_iso
+  recent_iso="$(python3 -c "import datetime; print((datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(hours=1)).strftime('%Y-%m-%dT%H:%M:%SZ'))")"
+  cat > "$FIXTURE/docs/problems/.outbound-responses-cache.json" <<EOF
+{ "last_checked": "$recent_iso", "tickets": {} }
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_outbound_responses_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "fresh-within-ttl" ]
+}
+
+@test "case 5: cache older than TTL → ttl-expiry with age + ttl in the reason" {
+  _write_backlink_ticket "$FIXTURE/docs/problems/100-back-link.open.md"
+  # last_checked 2 days ago — past 24h default TTL.
+  local stale_iso
+  stale_iso="$(python3 -c "import datetime; print((datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(days=2)).strftime('%Y-%m-%dT%H:%M:%SZ'))")"
+  cat > "$FIXTURE/docs/problems/.outbound-responses-cache.json" <<EOF
+{ "last_checked": "$stale_iso", "tickets": {} }
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_outbound_responses_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  # Format: "ttl-expiry age=<N>s ttl=<M>s"
+  [[ "$output" =~ ^ttl-expiry\ age=[0-9]+s\ ttl=86400s$ ]]
+}
+
+@test "case 6: custom ttl_seconds in cache is honored (not hardcoded default)" {
+  # 1-hour TTL; last_checked 90 minutes ago → stale under the custom TTL,
+  # but would be FRESH under the 86400s default. Confirms the helper reads
+  # ttl_seconds from cache rather than hardcoding 86400.
+  _write_backlink_ticket "$FIXTURE/docs/problems/100-back-link.open.md"
+  local mid_iso
+  mid_iso="$(python3 -c "import datetime; print((datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(minutes=90)).strftime('%Y-%m-%dT%H:%M:%SZ'))")"
+  cat > "$FIXTURE/docs/problems/.outbound-responses-cache.json" <<EOF
+{ "last_checked": "$mid_iso", "tickets": {}, "ttl_seconds": 3600 }
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_outbound_responses_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [[ "$output" =~ ^ttl-expiry\ age=[0-9]+s\ ttl=3600s$ ]]
+}
+
+@test "case 7: missing ttl_seconds defaults to 86400 (symmetric with inbound)" {
+  _write_backlink_ticket "$FIXTURE/docs/problems/100-back-link.open.md"
+  local recent_iso
+  recent_iso="$(python3 -c "import datetime; print((datetime.datetime.now(datetime.timezone.utc) - datetime.timedelta(hours=1)).strftime('%Y-%m-%dT%H:%M:%SZ'))")"
+  cat > "$FIXTURE/docs/problems/.outbound-responses-cache.json" <<EOF
+{ "last_checked": "$recent_iso", "tickets": {} }
+EOF
+  # shellcheck disable=SC1090
+  source "$HELPER"
+  run should_promote_outbound_responses_preflight "$FIXTURE"
+  [ "$status" -eq 0 ]
+  [ "$output" = "fresh-within-ttl" ]
+}

package/skills/work-problems/test/work-problems-step-5-is-error-transient-halt.bats

@@ -0,0 +1,278 @@
+#!/usr/bin/env bats
+# tdd-review: structural-permitted (justification: the doc-lint slice below
+# asserts SKILL.md / ADR-032 prose contract — SKILL.md is the contract
+# document per ADR-037 Permitted Exception; these guards catch prose drift
+# away from the behavioural HALT-with-advisory contract exercised above. The
+# load-bearing core of this fixture is behavioural per ADR-052. harness-gap P012)
+#
+# Behavioural test: work-problems Step 5 exit-code semantics — the
+# is_error:true TRANSIENT-API-ERROR HALT branch (P214). When an iter
+# subprocess returns `is_error: true` with `total_cost_usd: 0` AND no staged
+# work in the tree (the 529 Overloaded / 429 rate-limit / 401 auth-expired
+# shape — the API call never landed; nothing was done; metadata records the
+# failure), the orchestrator MUST halt the loop with a class-appropriate
+# advisory line in the final summary — NOT silently treat exit-0 as success
+# and try to parse a missing ITERATION_SUMMARY block.
+#
+# This is the HALT counterpart to the existing P261 SALVAGE branch (covered
+# by work-problems-step-5-stream-timeout-salvage.bats):
+#   - SALVAGE: is_error:true + staged work + bats green (stream-timeout class)
+#   - HALT:    is_error:true + nothing staged (transient-API-error class — P214)
+# Both branches require the orchestrator to read `is_error` BEFORE the
+# Exit-0 → parse-ITERATION_SUMMARY path; without the explicit check-order
+# the loop silently miscounts and may spawn further subprocesses that fail
+# identically (the AFK-promise-breaking shape P214 reports).
+#
+# The fake-shim below re-creates the production 529 Overloaded shape:
+# is_error:true, total_cost_usd:0, no staged work, .result carrying the
+# upstream error string. The harness re-implements the orchestrator's
+# ordered-check decision contract (faithful to SKILL.md Step 5) and asserts
+# the HALT routing + class-appropriate advisory for each transient class.
+#
+# @problem P214
+# @jtbd JTBD-006
+#
+# Cross-reference:
+#   P214 (work-problems Step 5 exit-code rule doesn't handle is_error:true
+#     transient API failures) — driver ticket
+#   P261 (is_error:true stream-timeout salvage carve-out) — sibling SALVAGE
+#     branch; this fixture covers the HALT counterpart
+#   ADR-032 (governance skill invocation patterns — is_error:true class
+#     taxonomy: SALVAGE = stream-timeout; HALT = transient-API-error) — the
+#     amended contract this fixture pins
+#   ADR-013 Rule 6 (AFK fail-safe — HALT routing is non-interactive; no
+#     AskUserQuestion) — invariant honoured
+#   ADR-037 / ADR-052 (skill testing strategy — behavioural default; doc-lint
+#     contract assertion is the Permitted Exception, marked above)
+
+setup() {
+  TEST_TMP="$(mktemp -d)"
+  FAKE_BIN="${TEST_TMP}/bin"
+  mkdir -p "$FAKE_BIN"
+
+  # Fake `claude` binary simulating the transient-API-error shape: exits 0,
+  # emits an is_error:true JSON envelope with total_cost_usd:0 and the
+  # transient-class error string in `.result`. No staged work — the API call
+  # never landed; nothing was done.
+  cat > "$FAKE_BIN/claude" <<'FAKE_EOF'
+#!/usr/bin/env bash
+# Test fake for work-problems Step 5 P214 transient-API-error halt fixture.
+# Emits is_error:true with total_cost_usd:0 and a class-specific .result string.
+# FAKE_ERROR_CLASS selects the transient class: overloaded | rate-limit | auth-expired
+case "${FAKE_ERROR_CLASS:-overloaded}" in
+  overloaded)
+    RESULT='API Error (529): Overloaded'
+    ;;
+  rate-limit)
+    RESULT='API Error (429): Rate limit exceeded'
+    ;;
+  auth-expired)
+    RESULT='API Error (401): Authentication expired'
+    ;;
+  *)
+    RESULT='API Error: Unknown'
+    ;;
+esac
+printf '%s\n' "{\"is_error\":true,\"result\":\"${RESULT}\",\"total_cost_usd\":0,\"duration_ms\":1500,\"usage\":{\"input_tokens\":0,\"output_tokens\":0,\"cache_creation_input_tokens\":0,\"cache_read_input_tokens\":0}}"
+FAKE_EOF
+  chmod +x "$FAKE_BIN/claude"
+  export PATH="$FAKE_BIN:$PATH"
+
+  # A throwaway git repo so staged-work detection is real (and empty — no
+  # staged work is the load-bearing characteristic of this class).
+  REPO="${TEST_TMP}/repo"
+  mkdir -p "$REPO"
+  git -C "$REPO" init -q
+  git -C "$REPO" config user.email "test@example.com"
+  git -C "$REPO" config user.name "Test"
+  git -C "$REPO" commit -q --allow-empty -m "root"
+
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+  ADR_FILE="$(cd "${SKILL_DIR}/../../../.." && pwd)/docs/decisions/032-governance-skill-invocation-patterns.proposed.md"
+}
+
+teardown() {
+  if [ -n "${TEST_TMP:-}" ] && [ -d "$TEST_TMP" ]; then
+    rm -rf "$TEST_TMP"
+  fi
+}
+
+# Faithful re-implementation of SKILL.md Step 5's ORDERED-CHECK decision
+# contract (P214 amendment to the P261 carve-out). The orchestrator reads
+# (1) exit code, (2) is_error, (3) ITERATION_SUMMARY — in that order. On
+# is_error:true + nothing staged, emit a class-appropriate advisory.
+ordered_check_decision() {
+  local exit_code="$1"
+  local json="$2"
+  local repo="$3"
+
+  # (1) Non-zero exit → halt per the exit-code contract.
+  if [ "$exit_code" -ne 0 ]; then
+    printf 'DECISION=HALT reason=non-zero-exit\n'
+    return 0
+  fi
+
+  # (2) Parse is_error BEFORE attempting to parse ITERATION_SUMMARY (the
+  # ordered-check rule P214 amends in).
+  local is_error result
+  is_error=$(printf '%s' "$json" | python3 -c 'import json,sys; print(str(json.load(sys.stdin).get("is_error")).lower())')
+  result=$(printf '%s' "$json" | python3 -c 'import json,sys; print(json.load(sys.stdin).get("result",""))')
+
+  if [ "$is_error" = "true" ]; then
+    # is_error:true with staged work → defer to existing P261 SALVAGE branch
+    # (covered by sibling fixture work-problems-step-5-stream-timeout-salvage.bats).
+    local staged
+    staged=$(git -C "$repo" diff --cached --name-only)
+    if [ -n "$staged" ]; then
+      printf 'DECISION=DEFER_TO_SALVAGE_BRANCH\n'
+      return 0
+    fi
+
+    # is_error:true with NO staged work → HALT with class-appropriate advisory.
+    local advisory
+    case "$result" in
+      *"529"*|*"Overloaded"*|*"overloaded"*)
+        advisory='API overloaded; retry when service recovers'
+        ;;
+      *"429"*|*"Rate limit"*|*"rate limit"*|*"rate-limit"*)
+        advisory='API rate-limited; retry when limit window resets'
+        ;;
+      *"401"*|*"Authentication"*|*"auth"*)
+        advisory='API auth expired; refresh credentials before resuming'
+        ;;
+      *)
+        advisory='transient API error; inspect .result and resume manually'
+        ;;
+    esac
+    printf 'DECISION=HALT reason=is-error-transient advisory=%s\n' "$advisory"
+    return 0
+  fi
+
+  # (3) Exit 0 AND is_error:false → parse ITERATION_SUMMARY.
+  printf 'DECISION=PARSE_SUMMARY\n'
+  return 0
+}
+
+# ---------------------------------------------------------------------------
+# Behavioural cases (the load-bearing core per ADR-052).
+# ---------------------------------------------------------------------------
+
+@test "P214: is_error:true + 529 Overloaded + no staged work -> HALT with API-overloaded advisory" {
+  export FAKE_ERROR_CLASS=overloaded
+  local json
+  json=$( cd "$REPO" && claude -p --output-format json "TEST" < /dev/null )
+  run ordered_check_decision 0 "$json" "$REPO"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"DECISION=HALT"* ]]
+  [[ "$output" == *"reason=is-error-transient"* ]]
+  [[ "$output" == *"API overloaded"* ]]
+  [[ "$output" == *"retry when service recovers"* ]]
+}
+
+@test "P214: is_error:true + 429 rate-limit + no staged work -> HALT with rate-limited advisory" {
+  export FAKE_ERROR_CLASS=rate-limit
+  local json
+  json=$( cd "$REPO" && claude -p --output-format json "TEST" < /dev/null )
+  run ordered_check_decision 0 "$json" "$REPO"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"DECISION=HALT"* ]]
+  [[ "$output" == *"reason=is-error-transient"* ]]
+  [[ "$output" == *"rate-limited"* ]]
+}
+
+@test "P214: is_error:true + 401 auth-expired + no staged work -> HALT with refresh-credentials advisory" {
+  export FAKE_ERROR_CLASS=auth-expired
+  local json
+  json=$( cd "$REPO" && claude -p --output-format json "TEST" < /dev/null )
+  run ordered_check_decision 0 "$json" "$REPO"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"DECISION=HALT"* ]]
+  [[ "$output" == *"reason=is-error-transient"* ]]
+  [[ "$output" == *"auth expired"* ]]
+  [[ "$output" == *"refresh credentials"* ]]
+}
+
+@test "P214: is_error MUST be checked BEFORE ITERATION_SUMMARY parse on Exit 0 (ordered-check invariant)" {
+  # The load-bearing P214 invariant: when exit 0 AND is_error:true, the
+  # decision is HALT, NOT PARSE_SUMMARY. Without the ordered-check rule the
+  # loop would silently route to PARSE_SUMMARY and miss the failure.
+  export FAKE_ERROR_CLASS=overloaded
+  local json
+  json=$( cd "$REPO" && claude -p --output-format json "TEST" < /dev/null )
+  run ordered_check_decision 0 "$json" "$REPO"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"DECISION=PARSE_SUMMARY"* ]]
+  [[ "$output" == *"DECISION=HALT"* ]]
+}
+
+@test "P214: non-zero exit takes precedence over is_error check (HALT routing)" {
+  # Non-zero exit halts regardless of is_error value — the exit-code rule
+  # is check (1) in the ordered sequence.
+  export FAKE_ERROR_CLASS=overloaded
+  local json
+  json=$( cd "$REPO" && claude -p --output-format json "TEST" < /dev/null )
+  run ordered_check_decision 1 "$json" "$REPO"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"DECISION=HALT"* ]]
+  [[ "$output" == *"reason=non-zero-exit"* ]]
+}
+
+@test "P214: is_error:true + staged work -> defers to existing P261 SALVAGE branch (no double-handling)" {
+  # When staged work exists, the transient-API-error HALT branch must NOT
+  # fire — it MUST defer to the P261 SALVAGE branch. This guards against
+  # the new branch swallowing salvage-eligible work.
+  export FAKE_ERROR_CLASS=overloaded
+  printf 'salvageable work\n' > "$REPO/salvage-me.txt"
+  git -C "$REPO" add salvage-me.txt
+  local json
+  json=$( cd "$REPO" && claude -p --output-format json "TEST" < /dev/null )
+  run ordered_check_decision 0 "$json" "$REPO"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"DECISION=DEFER_TO_SALVAGE_BRANCH"* ]]
+}
+
+# ---------------------------------------------------------------------------
+# Doc-lint contract assertions (Permitted Exception per ADR-037; structural
+# slice marked at top of file per ADR-052 Surface 2). These guard the SKILL.md
+# / ADR-032 prose against drift away from the behavioural contract above.
+# ---------------------------------------------------------------------------
+
+@test "P214: SKILL.md Step 5 documents the ORDERED check sequence (exit-code, is_error, ITERATION_SUMMARY)" {
+  # The ordered-check rule must be explicit in the prose so an implementer
+  # reading Step 5 routes is_error:true to HALT before attempting to parse
+  # a missing ITERATION_SUMMARY block.
+  run grep -niE "(check|read|parse).{0,40}is_error.{0,80}before.{0,80}(ITERATION_SUMMARY|parse|\.result)|ordered check|check.order" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "P214: SKILL.md Step 5 names the transient-API-error classes (overloaded / rate-limit / auth-expired)" {
+  # The HALT advisory must enumerate the known transient classes so the
+  # final summary carries an actionable message rather than a generic
+  # "loop halted" line.
+  run grep -niE "529|Overloaded|overload" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -niE "429|rate.?limit" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -niE "401|auth.?expired|auth.*expir" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "P214: SKILL.md Step 5 cites P214 as the driver of the transient-API-error HALT branch" {
+  run grep -nE "P214" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "P214: SKILL.md HALT branch distinguishes the transient-API-error class from the P261 stream-timeout SALVAGE class" {
+  # The two is_error:true branches (SALVAGE vs HALT) must be cross-referenced
+  # so adopters reading either branch see the other.
+  run grep -niE "P261.{0,200}(transient|HALT|overload|class)|transient.{0,200}P261|salvage.{0,200}(transient|class)" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "P214: ADR-032 P261 section names the is_error:true class taxonomy (SALVAGE = stream-timeout; HALT = transient-API-error)" {
+  # ADR-032's P261 amendment should be extended with the broader class
+  # taxonomy so the SKILL prose and the ADR contract stay in sync.
+  run grep -niE "P214|transient.?(API.?)?error|class taxonomy|(overload|rate.?limit|auth.?expired).{0,80}HALT|HALT.{0,80}(overload|rate.?limit|auth.?expired)" "$ADR_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/work-problems/test/work-problems-step-5-prompt-body-re-grounding.bats

@@ -0,0 +1,128 @@
+#!/usr/bin/env bats
+# P211 — work-problems Step 5 iteration-prompt-body must EXPLICITLY re-ground
+# each iter's dispatch prompt against the CURRENT ticket only. The orchestrator
+# MUST NOT inline the ticket's `## Fix Strategy` text verbatim, and MUST NOT
+# leak prior-iter content (prior ticket ID, prior Fix Strategy text, prior
+# outcome reason, prior commit SHA, prior retro findings) across iterations.
+#
+# Reported as inbound from downstream consumer bbstats (their P194) on
+# 2026-05-15; covered by ADR-076 Origin field tier.
+#
+# Behavioural mechanism for the bug: AFK iter subprocesses inherit a stale
+# design-rationale frame and may attempt fixes anchored on the wrong ticket's
+# intent. Workaround the ticket names: user-in-the-loop verification after
+# each iter, reading the subprocess's commit and checking whether it cites
+# the correct ticket's design rationale — a manual-policing burden the AFK
+# loop is meant to eliminate. JTBD-006 (Progress the Backlog While I'm Away)
+# is load-bearing: the audit trail and trust in the AFK loop degrade if iters
+# work the wrong ticket's design rationale.
+#
+# tdd-review: structural-permitted (justification: SKILL.md is the named
+# contract document under ADR-052; behavioural alternative would require a
+# synthetic `claude -p` iter dispatch harness that simulates multiple
+# sequential iters and asserts no cross-iter prompt-body content leakage —
+# that harness sits outside the skill layer and depends on the Anthropic CLI
+# binary. Same Permitted Exception precedent as
+# `work-problems-step-5-iter-changeset-required.bats:14-21`,
+# `work-problems-step-5-delegation.bats:99-105`, and the P083 / P086 / P089
+# ScheduleWakeup / retro / stdin-redirect fixtures in the same directory.
+# P012 is the harness-gap ticket).
+#
+# @problem P211
+# @problem P012
+# @jtbd JTBD-006
+# @jtbd JTBD-001
+#
+# Cross-reference:
+#   P211 — this ticket (orchestrator carries prior-ticket Fix Strategy into
+#     next iter's dispatch context — pollutes the new iter's framing)
+#   bbstats#194 — inbound report from downstream consumer
+#   ADR-014 (single-commit grain — fix lands as one coherent commit)
+#   ADR-032 (governance skill invocation patterns — AFK iteration-isolation
+#     wrapper; re-grounding is a clarification of that isolation intent)
+#   ADR-052 (behavioural tests default; structural-permitted with comment)
+#   ADR-076 (inbound-reported problems rank ahead via sort tier — Origin
+#     field stamping)
+#   JTBD-006 (Progress the Backlog While I'm Away) — load-bearing
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+@test "SKILL.md cites P211 (re-grounding driver) in Related section" {
+  # Self-documenting contract — a future contributor weakening the
+  # re-grounding constraint reads P211 and understands why it exists.
+  run grep -nE 'P211' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 5 iteration prompt body names re-grounding per iter explicitly" {
+  # The "self-contained" opener at line 510 is the existing weaker form; the
+  # stricter "re-ground per iter" phrasing names the construction invariant
+  # the orchestrator MUST satisfy on each iter dispatch. P211's bug shape is
+  # exactly the case where "self-contained" was read as a subprocess-side
+  # property only, with the orchestrator-side construction leaking prior-iter
+  # content into the new iter's prompt body.
+  run grep -niE "re.?ground.{0,40}per iter|re.?grounded.{0,40}per iter|per.?iter.{0,40}re.?ground" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 5 iter prompt body forbids inlining Fix Strategy verbatim" {
+  # The bug shape: orchestrator reads target ticket's `## Fix Strategy` and
+  # cites it verbatim into the iteration subprocess's prompt body. The
+  # SKILL.md MUST explicitly forbid this so future contributors understand
+  # the subprocess reads Fix Strategy from disk via manage-problem inside
+  # its own context.
+  run grep -niE "(not|never|MUST NOT|does not).{0,40}inline.{0,40}Fix Strategy|Fix Strategy.{0,40}(not|never|MUST NOT|does not).{0,40}inline|do not.{0,40}cite.{0,40}Fix Strategy.{0,40}verbatim|Fix Strategy.{0,40}verbatim.{0,40}(not|never|forbid)" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 5 iter prompt body explicitly forbids prior-iter content leakage" {
+  # The cross-iter leakage class names: prior ticket ID, prior Fix Strategy
+  # text, prior outcome reason, prior commit SHA, prior retro findings. The
+  # SKILL.md MUST name the no-leakage invariant explicitly so the orchestrator
+  # main turn's prompt construction is constrained on every iter.
+  run grep -niE "(no prior|not.{0,20}prior|prior.?iter.{0,40}(leak|carry|inherit)|leak.{0,40}prior|carry.{0,40}prior.{0,40}iter)" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 5 names template-driven reset-per-iter construction" {
+  # The construction shape: template-driven, reset per iter, no global
+  # accumulator across iters. This is the structural invariant the
+  # orchestrator main turn must satisfy when building each iter's prompt.
+  run grep -niE "template.?driven|reset per iter|reset.{0,20}per.{0,20}iter|no.{0,20}(global )?accumulator" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md Step 5 iteration prompt body cites P211 inline" {
+  # The re-grounding clause must cite P211 inline so the contract document
+  # is self-documenting — a future contributor removing the clause reads the
+  # P211 reference and understands why it exists before deleting it. Same
+  # pattern as the P083 / P086 / P146 / P232 inline citations in the same
+  # block.
+  run grep -nE "re.?ground.{0,200}P211|P211.{0,200}re.?ground|P211.{0,200}Fix Strategy|Fix Strategy.{0,200}P211" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md re-grounding clause sits inside Step 5 iteration prompt body section" {
+  # Structural locality: the re-grounding clause must live INSIDE Step 5's
+  # Iteration prompt body section (after the "self-contained" opener at
+  # line 510), not free-floating elsewhere in SKILL.md. Locality matters
+  # because the rule is read alongside the rest of the prompt-body contract,
+  # and a future contributor refactoring Step 5 must encounter it inline.
+  # Assertion shape: the line containing "re-ground" sits after the line
+  # containing "Iteration prompt body" and before the line containing
+  # "Return-summary contract".
+  iter_line=$(grep -nE '^\*\*Iteration prompt body' "$SKILL_FILE" | head -1 | cut -d: -f1)
+  # Tightened regex: require the literal hyphenated form "re-ground" /
+  # "re-grounded" / "re-grounding" so partial-substring matches like
+  # "foreground" (line 33) don't satisfy the assertion.
+  reground_line=$(grep -niE "re-ground(ed|ing)?" "$SKILL_FILE" | head -1 | cut -d: -f1)
+  return_summary_line=$(grep -nE '^\*\*Return-summary contract' "$SKILL_FILE" | head -1 | cut -d: -f1)
+  [ -n "$iter_line" ]
+  [ -n "$reground_line" ]
+  [ -n "$return_summary_line" ]
+  [ "$reground_line" -gt "$iter_line" ]
+  [ "$reground_line" -lt "$return_summary_line" ]
+}