bigpowers 2.84.1 → 2.85.0

package/scripts/validate-agentic-ste.sh

@@ -0,0 +1,229 @@
+#!/usr/bin/env bash
+# story: e79s02
+# validate-agentic-ste.sh — mechanical Agentic STE checks for instructional prose.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+MAX_WORDS=20
+BANNED_RE='\b(should|might|could|may|consider|try|generally|typically)\b'
+
+STRICT=false
+AUDIT=false
+SELF_TEST=false
+TARGETS=()
+
+ste_usage() {
+  echo "Usage: bash scripts/validate-agentic-ste.sh [--self-test|--strict|--audit] [file|dir ...]"
+  echo "  (no args)     Run built-in fixture self-test"
+  echo "  --strict      Exit 1 on violations (craft-skill gate)"
+  echo "  --audit       WARN-only catalog scan (stocktake)"
+  exit 2
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --strict) STRICT=true; shift ;;
+    --audit) AUDIT=true; shift ;;
+    --self-test) SELF_TEST=true; shift ;;
+    -h|--help) ste_usage ;;
+    --) shift; TARGETS+=("$@"); break ;;
+    -*) echo "Unknown flag: $1" >&2; ste_usage ;;
+    *) TARGETS+=("$1"); shift ;;
+  esac
+done
+
+VIOLATIONS=0
+WARNINGS=0
+
+ste_report_fail() {
+  echo "FAIL: $1" >&2
+  VIOLATIONS=$((VIOLATIONS + 1))
+}
+
+ste_report_warn() {
+  echo "WARN: $1" >&2
+  WARNINGS=$((WARNINGS + 1))
+}
+
+ste_strip_frontmatter() {
+  awk '
+    BEGIN { n=0; emit=0 }
+    /^---$/ { n++; if (n==1) next; if (n==2) { emit=1; next } }
+    emit { print }
+  ' "$1"
+}
+
+ste_extract_prose() {
+  local file="$1"
+  local body
+  if [[ "$(basename "$file")" == "SKILL.md" ]]; then
+    body="$(ste_strip_frontmatter "$file")"
+  else
+    body="$(cat "$file")"
+  fi
+  printf '%s\n' "$body" | awk '
+    BEGIN { in_code=0 }
+    /^```/ { in_code = !in_code; next }
+    in_code { next }
+    /^[[:space:]]*#/ { next }
+    /^[[:space:]]*\|/ { next }
+    /^[[:space:]]*<!--/ { next }
+    /^[[:space:]]*$/ { next }
+    /^# story:/ { next }
+    /^<!-- story:/ { next }
+    { print }
+  '
+}
+
+ste_count_words() {
+  # shellcheck disable=SC2207
+  local words=($1)
+  echo "${#words[@]}"
+}
+
+ste_audit_line() {
+  local file="$1"
+  local line_no="$2"
+  local line="$3"
+  local label="${file}:${line_no}"
+
+  if echo "$line" | grep -qiE "$BANNED_RE"; then
+    local word
+    word="$(echo "$line" | grep -oiE "$BANNED_RE" | head -1)"
+    if $STRICT; then
+      ste_report_fail "$label — banned hedge modal '$word'"
+    else
+      ste_report_warn "$label — banned hedge modal '$word'"
+    fi
+  fi
+
+  local sentence
+  while IFS= read -r sentence; do
+    [[ -z "$sentence" ]] && continue
+    local trimmed
+    trimmed="$(echo "$sentence" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+    [[ -z "$trimmed" ]] && continue
+    local wc
+    wc="$(ste_count_words "$trimmed")"
+    if (( wc > MAX_WORDS )); then
+      if $STRICT; then
+        ste_report_fail "$label — sentence has ${wc} words (max ${MAX_WORDS}): ${trimmed:0:60}..."
+      else
+        ste_report_warn "$label — sentence has ${wc} words (max ${MAX_WORDS}): ${trimmed:0:60}..."
+      fi
+    fi
+  done < <(echo "$line" | sed 's/[.!?]/&\n/g')
+}
+
+ste_audit_file() {
+  local file="$1"
+  [[ -f "$file" ]] || { ste_report_fail "not found: $file"; return; }
+
+  local prose line_no=0
+  prose="$(ste_extract_prose "$file")"
+  while IFS= read -r line; do
+    line_no=$((line_no + 1))
+    ste_audit_line "$file" "$line_no" "$line"
+  done <<< "$prose"
+}
+
+ste_collect_files() {
+  local path="$1"
+  if [[ -f "$path" ]]; then
+    echo "$path"
+  elif [[ -d "$path" ]]; then
+    find "$path" -type f \( -name 'SKILL.md' -o -name 'CLAUDE.md' -o -name 'CONVENTIONS.md' -o -name 'AGENTS.md' \) | sort
+  fi
+}
+
+ste_run_self_test() {
+  local tmp
+  tmp="$(mktemp -d)"
+  trap 'rm -rf "$tmp"' RETURN
+
+  cat > "$tmp/good-skill.md" <<'EOF'
+---
+name: fixture-good
+description: Test fixture for Agentic STE validator. Use when running self-test.
+---
+# Fixture Good
+> **HARD GATE** — Run Preflight before forward work.
+Run tests after every change.
+Write specs to specs/ at project root.
+EOF
+
+  cat > "$tmp/bad-hedge.md" <<'EOF'
+---
+name: fixture-bad
+description: Bad fixture.
+---
+You should consider running tests generally.
+EOF
+
+  cat > "$tmp/bad-long.md" <<'EOF'
+---
+name: fixture-long
+description: Long sentence fixture.
+---
+Run the full local green stack including compliance verification gates sync skills trace stories and catalog drift check before any forward implementation work on this repository.
+EOF
+
+  local saved_strict=$STRICT saved_audit=$AUDIT
+  STRICT=true
+  AUDIT=false
+  VIOLATIONS=0
+
+  ste_audit_file "$tmp/good-skill.md"
+  if (( VIOLATIONS > 0 )); then
+    echo "SELF-TEST FAIL: good fixture should pass" >&2
+    return 1
+  fi
+
+  VIOLATIONS=0
+  ste_audit_file "$tmp/bad-hedge.md"
+  if (( VIOLATIONS == 0 )); then
+    echo "SELF-TEST FAIL: hedge fixture should fail" >&2
+    return 1
+  fi
+
+  VIOLATIONS=0
+  ste_audit_file "$tmp/bad-long.md"
+  if (( VIOLATIONS == 0 )); then
+    echo "SELF-TEST FAIL: long-sentence fixture should fail" >&2
+    return 1
+  fi
+
+  STRICT=$saved_strict
+  AUDIT=$saved_audit
+  VIOLATIONS=0
+  echo "validate-agentic-ste: self-test PASS"
+  return 0
+}
+
+if $SELF_TEST || [[ ${#TARGETS[@]} -eq 0 ]]; then
+  ste_run_self_test
+  exit $?
+fi
+
+if $AUDIT; then
+  STRICT=false
+fi
+
+for target in "${TARGETS[@]}"; do
+  while IFS= read -r f; do
+    [[ -n "$f" ]] && ste_audit_file "$f"
+  done < <(ste_collect_files "$target")
+done
+
+if (( VIOLATIONS > 0 )); then
+  echo "validate-agentic-ste: $VIOLATIONS violation(s)" >&2
+  exit 1
+fi
+
+if $AUDIT; then
+  echo "validate-agentic-ste: audit complete ($WARNINGS warning(s))"
+else
+  echo "validate-agentic-ste: PASS"
+fi

package/skills/craft-skill/SKILL.md

@@ -1,5 +1,6 @@
 # story: e45s02
 <!-- story: e45s12 -->
+<!-- story: e79s02 -->
 ---
 name: craft-skill
 model: sonnet
@@ -9,7 +10,7 @@ description: Create new bigpowers skills with proper structure, progressive disc
 
 # Craft Skill
 
-> **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh` — the generated `.cursor/rules/` and `.gemini/` artifacts must match the source SKILL.md.
+> **HARD GATE** — Do NOT name a skill without a two-word verb-noun pair. Do NOT merge a new skill without running `sync-skills.sh`. Generated `.cursor/rules/` and `.gemini/` artifacts MUST match the source SKILL.md.
 
 ## CSO Description Discipline (e45s02)
 
@@ -24,11 +25,25 @@ The YAML `description` is the **Catalog Selection Object** — the only field ag
 
 Move process detail into the SKILL.md body or REFERENCE.md — never into `description`.
 
+## Agentic STE body discipline (e79s02)
+
+Skill-body instructional prose MUST follow [AGENTIC-STE.md](../../docs/AGENTIC-STE.md).
+
+| Rule | Limit |
+|------|-------|
+| Sentence length | ≤20 words per instruction sentence |
+| Voice | Imperative, active |
+| Directive terms | MUST, MUST NOT, NEVER, ALWAYS, DO, DO NOT |
+| Banned modals | should, might, could, may, consider, try, generally, typically |
+| Scope | SKILL.md body only — not YAML `description`, not `terse-mode` output |
+
+> **HARD GATE** — Do NOT merge a new or edited skill until `bash scripts/validate-agentic-ste.sh --strict skills/<name>/SKILL.md` exits 0. Fix violations before `sync-skills.sh`.
+
 ## Process
 
 1. **Gather requirements** — ask user about:
    - What task/domain does the skill cover?
-   - What specific use cases should it handle?
+   - Which use cases must the skill handle?
    - Does it need executable scripts or just instructions?
    - Any reference materials to include?
    - What specs/ output does it produce (if any)?
@@ -44,7 +59,8 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr
    - Additional reference files if content exceeds 100 lines
    - Utility scripts if deterministic operations needed
 
-   **Auto-skill from library README:** When user provides a library README or API docs URL, extract: triggers, HARD GATEs, verify commands, specs/ output — draft SKILL.md without inventing APIs not in the source.
+   **Auto-skill from library README:** When user provides a library README or API docs URL, extract triggers and HARD GATEs.
+   Draft verify commands and specs/ output into SKILL.md. Do NOT invent APIs not in the source.
 
 4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/model-profiles.md).
 
@@ -53,10 +69,11 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr
 5. **Review with user** — present draft and ask:
    - Does this cover your use cases?
    - Anything missing or unclear?
-   - Should any section be more/less detailed?
+   - Does any section need more or less detail?
 
 6. **Completion-honesty gate (HARD GATE — e45s02)** — Before declaring done:
    - Run `bash scripts/validate-skill-description.sh skills/<name>/SKILL.md` — must exit 0
+   - Run `bash scripts/validate-agentic-ste.sh --strict skills/<name>/SKILL.md` — must exit 0 (e79s02)
    - Run `bash scripts/sync-skills.sh` — must complete without error
    - Run `bash scripts/run-skill-verify.sh <name>` if the skill defines a verify command
    - Show terminal output for each — narration without evidence is rejected
@@ -81,6 +98,7 @@ After drafting, verify:
 - [ ] Consistent terminology with CONVENTIONS.md
 - [ ] specs/ output documented if applicable
 - [ ] `validate-skill-description.sh` exits 0
+- [ ] `validate-agentic-ste.sh --strict` exits 0 (e79s02)
 - [ ] `sync-skills.sh` run to propagate to Cursor/Gemini
 - [ ] `bash scripts/validate-skill-catalog.sh` passes for the new skill (HARD GATE — completion honesty)
 

package/skills/seed-conventions/SKILL.md

@@ -10,6 +10,7 @@ description: Generate CLAUDE.md and CONVENTIONS.md for a brand-new project throu
 # story: e10s02
 # story: e51s02
 # story: e45s21
+# story: e79s03
 
 
 # Seed Conventions
@@ -33,13 +34,25 @@ Ask the user these questions (one at a time, wait for each answer):
 2. **Stack** — "What language, framework, and runtime? (e.g. TypeScript / Next.js / Node 22)"
 2b. **Stack profile (optional)** — Offer: `swift`, `typescript-vue`, `node-service`, or none. If chosen, merge the matching fragment from `profiles/<name>.md` into generated `CONVENTIONS.md`.
 3. **Commands** — "What commands do you use for: run, test, build, lint?"
-3b. **Preflight (optional)** — "What single command runs your full local green stack (test + lint + build)? If you don't have one, we'll chain your Test + Lint + Build answers into a **Preflight** row in the Commands table."
+3b. **Preflight (optional)** — "What command runs test, lint, and build together? If none, chain Test + Lint + Build into one **Preflight** row."
 4. **Architecture** — "Key modules and relationships in 1–2 sentences."
 5. **Conventions** — "Any naming, file organization, or patterns all agents must follow?"
 6. **Never-do list** — "What are the hard stops? Things an agent must never touch?"
 7. **Defensive code categories** — "Which apply? (Rate limit / Retry / Circuit breaker / Timeout / Graceful degradation)"
 8. **Local tool wiring (optional)** — "Wire bigpowers for project-local tools? (Cursor, OpenCode, Cline, Aider, Codex CLI)" If yes, generate AGENTS.md spine artifacts per [REFERENCE.md](REFERENCE.md) §Local tool wiring and §AGENTS.md spine. If no, skip — standard seed output unchanged (no AGENTS.md spine unless opted in).
 
+## Agentic STE for generated prose (e79s03)
+
+When writing instructional lines in `CLAUDE.md`, `AGENTS.md`, or `CONVENTIONS.md`, follow [AGENTIC-STE.md](../../docs/AGENTIC-STE.md):
+
+- Use directive vocabulary: MUST, MUST NOT, NEVER, ALWAYS, DO, DO NOT
+- Do NOT use hedge modals listed in AGENTIC-STE.md Rule 3
+- Cap each instruction sentence at 20 words
+- Write imperative, active-voice lines — one instruction per line
+- Do NOT apply Agentic STE to `terse-mode` (output compression is out of scope)
+
+After generation, run `bash scripts/validate-agentic-ste.sh --strict CLAUDE.md CONVENTIONS.md` when those files exist in the target project.
+
 ## Generate files
 
 After the interview, generate each file using the templates in [REFERENCE.md](REFERENCE.md):
@@ -66,9 +79,11 @@ echo "# Specs\n\nAll planning documents for this project." > specs/README.md
 
 **Note:** `specs/state.yaml.lock` is NOT pre-created — acquired/released dynamically.
 
-`specs/state.yaml` carries a top-level `workflow_mode` key (`team-pr` | `solo-git`, default `solo-git`). This is the **canonical integrate-mode signal** for all skills — set it once here and skills such as `release-branch` read it from this file instead of sniffing profile files.
+`specs/state.yaml` carries top-level `workflow_mode` (`team-pr` | `solo-git`, default `solo-git`).
+This is the **canonical integrate-mode signal** for all skills.
+Set it once here. Skills such as `release-branch` read this file instead of sniffing profiles.
 
-When generating `CLAUDE.md`, if the user did not name a Preflight command, chain the Test + Lint + Build interview answers into one **Preflight** row (e.g. `npm test && npm run lint && npm run build`).
+When generating `CLAUDE.md`, chain Test + Lint + Build into one **Preflight** row if the user named no Preflight command.
 
 ### Self-installing fenced markers (e45s21)
 
@@ -80,7 +95,9 @@ Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment
 <!-- END bigpowers:section-id -->
 ```
 
-**Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file.
+**Merge rule:** On update, replace only content between matching `BEGIN`/`END` pairs.
+If a marker pair is missing, append a new fenced block at file end.
+Never rewrite the whole file.
 
 **Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers):
 

package/skills/stocktake-skills/SKILL.md

@@ -9,6 +9,7 @@ effort: standard
 
 # story: e09s01
 <!-- story: e45s12 -->
+<!-- story: e79s04 -->
 
 
 # Stocktake Skills
@@ -28,6 +29,7 @@ Audit SKILL.md catalog for drift, stale triggers, missing HARD GATEs, and INDEX
 ## Process
 
 0. **Catalog validator (code-enforced)** — run `bash scripts/validate-skill-catalog.sh`. Any FAIL is a critical finding before manual review. Add `--archive` to list zero-usage skills from `metrics.skill_timings` for auto-archiving candidates (move to `specs/epics/archive/` or delete after user confirms).
+0b. **Agentic STE audit (e79s04)** — run `bash scripts/validate-agentic-ste.sh --audit skills/`. Flag hedge words and sentences over 20 words per [AGENTIC-STE.md](../../docs/AGENTIC-STE.md). Record WARN lines in the stocktake report as **STE debt** — do NOT rewrite the full catalog in one pass. Route critical repeat offenders to `evolve-skill`.
 1. Run `bash scripts/audit-catalog.sh` to verify pi/skills ↔ source SKILL.md sync. Mismatch is a critical finding.
 2. Run mode; for each skill check: exists, verb-noun, &lt;300 lines total, HARD GATE present, INDEX row matches.
 3. Write `specs/STOCKTAKE-<date>.md` with findings table (skill, issue, severity).

package/skills-lock.json

@@ -48,7 +48,7 @@
     },
     "craft-skill": {
       "description": "Create new bigpowers skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill for the bigpowers lifecycle.",
-      "sha256": "2caa9d8ae9298b4b",
+      "sha256": "07d1cc8eddca50c5",
       "path": "skills/craft-skillSKILL.md"
     },
     "deepen-architecture": {
@@ -308,7 +308,7 @@
     },
     "seed-conventions": {
       "description": "Generate CLAUDE.md and CONVENTIONS.md for a brand-new project through a brief interview, and create the specs/ directory with evolved bigpowers structure (product/, tech-architecture/, verifications/, epics/archive/). Entry point for greenfield projects. Use when starting a new project from scratch, when user asks to set up AI agent conventions, or when there is no CLAUDE.md yet.",
-      "sha256": "35c335385c4ad48b",
+      "sha256": "6cb91bf0b5cdd9b3",
       "path": "skills/seed-conventionsSKILL.md"
     },
     "session-state": {
@@ -343,7 +343,7 @@
     },
     "stocktake-skills": {
       "description": "Sequential subagent batch audit of the bigpowers skill catalog — Quick Scan (changed only) or Full (all skills). Use during sustain phase, before a major release, or when catalog drift is suspected.",
-      "sha256": "6833c900df48a98a",
+      "sha256": "9595b954341217d7",
       "path": "skills/stocktake-skillsSKILL.md"
     },
     "survey-context": {

package/tests/test-land-branch-protected.sh

@@ -0,0 +1,222 @@
+#!/usr/bin/env bash
+# story: BUG-2026-07-25-land-branch-protected
+# Regression: land-branch protected-branch push rejection + PR fallback.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+# shellcheck source=../scripts/lib/land-branch-push.sh
+source "$REPO_ROOT/scripts/lib/land-branch-push.sh"
+
+pass_count=0
+fail_count=0
+
+assert_true() {
+  local label="$1"
+  shift
+  if "$@"; then
+    echo "  PASS $label"
+    pass_count=$((pass_count + 1))
+  else
+    echo "  FAIL $label"
+    fail_count=$((fail_count + 1))
+  fi
+}
+
+assert_false() {
+  local label="$1"
+  shift
+  if ! "$@"; then
+    echo "  PASS $label"
+    pass_count=$((pass_count + 1))
+  else
+    echo "  FAIL $label"
+    fail_count=$((fail_count + 1))
+  fi
+}
+
+assert_contains() {
+  local label="$1"
+  local haystack="$2"
+  local needle="$3"
+  if [[ "$haystack" == *"$needle"* ]]; then
+    echo "  PASS $label"
+    pass_count=$((pass_count + 1))
+  else
+    echo "  FAIL $label (missing: $needle)"
+    fail_count=$((fail_count + 1))
+  fi
+}
+
+echo "=== is_protected_branch_rejection fixtures ==="
+
+GH006_FIXTURE=$'remote: error: GH006: Protected branch update failed for refs/heads/main.\nremote: - Changes must be made through a pull request.\nerror: failed to push some refs'
+PR_ONLY_FIXTURE=$'remote: - Changes must be made through a pull request.\nerror: failed to push some refs'
+UNRELATED_FIXTURE=$'error: failed to push some refs\nremote: Permission denied'
+
+assert_true "detects GH006 rejection" is_protected_branch_rejection "$GH006_FIXTURE"
+assert_true "detects PR-required message without GH006 code" is_protected_branch_rejection "$PR_ONLY_FIXTURE"
+assert_false "ignores unrelated push failure" is_protected_branch_rejection "$UNRELATED_FIXTURE"
+
+echo "=== temp bare remote with rejecting pre-receive hook ==="
+
+TMPDIR_ROOT="$(mktemp -d)"
+trap 'rm -rf "$TMPDIR_ROOT"' EXIT
+
+BARE="$TMPDIR_ROOT/remote.git"
+WORK="$TMPDIR_ROOT/work"
+MOCK_BIN="$TMPDIR_ROOT/bin"
+mkdir -p "$MOCK_BIN"
+
+git init --bare "$BARE" >/dev/null
+mkdir -p "$BARE/hooks"
+cat >"$BARE/hooks/pre-receive" <<'HOOK'
+#!/bin/sh
+while read -r oldrev newrev refname; do
+  case "$refname" in
+    refs/heads/main)
+      if [ "$oldrev" = "0000000000000000000000000000000000000000" ]; then
+        continue
+      fi
+      echo "remote: error: GH006: Protected branch update failed for refs/heads/main."
+      echo "remote: - Changes must be made through a pull request."
+      exit 1
+      ;;
+  esac
+done
+exit 0
+HOOK
+chmod +x "$BARE/hooks/pre-receive"
+
+git clone "$BARE" "$WORK" >/dev/null
+git -C "$WORK" config user.email "test@example.com"
+git -C "$WORK" config user.name "test"
+echo "base" >"$WORK/README.md"
+git -C "$WORK" add README.md
+git -C "$WORK" commit -qm "chore: init"
+git -C "$WORK" push origin main >/dev/null
+
+git -C "$WORK" checkout -b feat/test >/dev/null
+echo "feature" >>"$WORK/README.md"
+git -C "$WORK" add README.md
+git -C "$WORK" commit -qm "feat: add feature"
+git -C "$WORK" checkout main >/dev/null
+git -C "$WORK" merge --squash feat/test >/dev/null
+git -C "$WORK" commit -qm "feat(test): squash land"
+LAND_SHA="$(git -C "$WORK" rev-parse --short HEAD)"
+LAND_FULL_SHA="$(git -C "$WORK" rev-parse HEAD)"
+RECOVERY_BRANCH="land-recovery/feat/test"
+
+cat >"$MOCK_BIN/gh" <<'MOCK'
+#!/usr/bin/env bash
+echo "https://github.com/example/repo/pull/1"
+exit 0
+MOCK
+chmod +x "$MOCK_BIN/gh"
+
+cd "$WORK"
+export PATH="$MOCK_BIN:$PATH"
+LAND_PR_FALLBACK=0
+if ! land_push_default_branch main "$LAND_SHA" "feat/test" "feat(test): squash land"; then
+  echo "  FAIL land_push_default_branch should succeed via PR fallback"
+  fail_count=$((fail_count + 1))
+else
+  echo "  PASS land_push_default_branch succeeds on protected rejection"
+  pass_count=$((pass_count + 1))
+fi
+
+if [ "$LAND_PR_FALLBACK" = "1" ]; then
+  echo "  PASS LAND_PR_FALLBACK flag set"
+  pass_count=$((pass_count + 1))
+else
+  echo "  FAIL LAND_PR_FALLBACK flag not set"
+  fail_count=$((fail_count + 1))
+fi
+
+if git show-ref --verify --quiet "refs/heads/$RECOVERY_BRANCH"; then
+  echo "  PASS recovery branch exists locally"
+  pass_count=$((pass_count + 1))
+else
+  echo "  FAIL recovery branch missing locally"
+  fail_count=$((fail_count + 1))
+fi
+
+if git rev-parse main >/dev/null 2>&1 && [ "$(git rev-parse main)" != "$LAND_FULL_SHA" ]; then
+  echo "  PASS local main reset away from stranded squash commit"
+  pass_count=$((pass_count + 1))
+else
+  echo "  FAIL local main still points at squash commit"
+  fail_count=$((fail_count + 1))
+fi
+
+if git ls-remote --heads origin "$RECOVERY_BRANCH" | grep -q "$RECOVERY_BRANCH"; then
+  echo "  PASS recovery branch pushed to origin"
+  pass_count=$((pass_count + 1))
+else
+  echo "  FAIL recovery branch not on origin"
+  fail_count=$((fail_count + 1))
+fi
+cd "$REPO_ROOT"
+
+echo "=== gh failure prints recovery commands ==="
+
+BARE2="$TMPDIR_ROOT/remote2.git"
+WORK2="$TMPDIR_ROOT/work2"
+git init --bare "$BARE2" >/dev/null
+mkdir -p "$BARE2/hooks"
+cp "$BARE/hooks/pre-receive" "$BARE2/hooks/pre-receive"
+chmod +x "$BARE2/hooks/pre-receive"
+
+cat >"$MOCK_BIN/gh" <<'MOCK'
+#!/usr/bin/env bash
+echo "gh: authentication required" >&2
+exit 1
+MOCK
+chmod +x "$MOCK_BIN/gh"
+
+git clone "$BARE2" "$WORK2" >/dev/null
+git -C "$WORK2" config user.email "test@example.com"
+git -C "$WORK2" config user.name "test"
+echo "base" >"$WORK2/README.md"
+git -C "$WORK2" add README.md
+git -C "$WORK2" commit -qm "chore: init"
+git -C "$WORK2" push origin main >/dev/null
+git -C "$WORK2" checkout -b feat/broken >/dev/null
+echo "feature" >>"$WORK2/README.md"
+git -C "$WORK2" add README.md
+git -C "$WORK2" commit -qm "feat: broken land"
+git -C "$WORK2" checkout main >/dev/null
+git -C "$WORK2" merge --squash feat/broken >/dev/null
+git -C "$WORK2" commit -qm "feat(broken): squash land"
+BROKEN_SHA="$(git -C "$WORK2" rev-parse --short HEAD)"
+BROKEN_FULL_SHA="$(git -C "$WORK2" rev-parse HEAD)"
+BROKEN_RECOVERY="land-recovery/feat/broken"
+
+cd "$WORK2"
+export PATH="$MOCK_BIN:$PATH"
+set +e
+stderr_file="$(mktemp)"
+land_push_default_branch main "$BROKEN_SHA" "feat/broken" "feat(broken): squash land" 2>"$stderr_file"
+status=$?
+set -e
+stderr="$(cat "$stderr_file")"
+rm -f "$stderr_file"
+
+if [ "$status" -ne 0 ]; then
+  echo "  PASS land_push_default_branch exits non-zero when gh fails"
+  pass_count=$((pass_count + 1))
+else
+  echo "  FAIL expected non-zero exit when gh fails"
+  fail_count=$((fail_count + 1))
+fi
+
+assert_contains "recovery commands mention git branch" "$stderr" "git branch $BROKEN_RECOVERY $BROKEN_FULL_SHA"
+assert_contains "recovery commands mention gh pr create" "$stderr" "gh pr create --base main --head $BROKEN_RECOVERY"
+cd "$REPO_ROOT"
+
+echo ""
+echo "Results: $pass_count passed, $fail_count failed"
+if [ "$fail_count" -gt 0 ]; then
+  exit 1
+fi
+echo "All land-branch protected-branch tests passed."