@reddb-io/red-skills 4.4.0 → 4.5.0

package/runtime/plugins/dev/skills/engineering/diagnose/scripts/hitl-loop.template.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Human-in-the-loop reproduction loop.
+# Copy this file, edit the steps below, and run it.
+# The agent runs the script; the user follows prompts in their terminal.
+#
+# Usage:
+#   bash hitl-loop.template.sh
+#
+# Two helpers:
+#   step "<instruction>"          → show instruction, wait for Enter
+#   capture VAR "<question>"      → show question, read response into VAR
+#
+# At the end, captured values are printed as KEY=VALUE for the agent to parse.
+
+set -euo pipefail
+
+step() {
+  printf '\n>>> %s\n' "$1"
+  read -r -p "    [Enter when done] " _
+}
+
+capture() {
+  local var="$1" question="$2" answer
+  printf '\n>>> %s\n' "$question"
+  read -r -p "    > " answer
+  printf -v "$var" '%s' "$answer"
+}
+
+# --- edit below ---------------------------------------------------------
+
+step "Open the app at http://localhost:3000 and sign in."
+
+capture ERRORED "Click the 'Export' button. Did it throw an error? (y/n)"
+
+capture ERROR_MSG "Paste the error message (or 'none'):"
+
+# --- edit above ---------------------------------------------------------
+
+printf '\n--- Captured ---\n'
+printf 'ERRORED=%s\n' "$ERRORED"
+printf 'ERROR_MSG=%s\n' "$ERROR_MSG"

package/runtime/plugins/dev/skills/engineering/red-setup/scripts/install-runtime-shim.sh

@@ -0,0 +1,181 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+bin_dir="${XDG_BIN_HOME:-$HOME/.local/bin}"
+name="${1:-red-skills-dev}"
+dev_target="$bin_dir/$name"
+rsp_target="$bin_dir/rsp"
+
+mkdir -p "$bin_dir"
+
+cat >"$dev_target" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+
+env_launcher() {
+  local root
+  for root in \
+    "${RED_SKILLS_DEV_PLUGIN_ROOT:-}" \
+    "${CLAUDE_PLUGIN_ROOT:-}" \
+    "${CODEX_PLUGIN_ROOT:-}" \
+    "${OPENCODE_PLUGIN_ROOT:-}"
+  do
+    [ -n "$root" ] || continue
+    if [ -f "$root/skills/engineering/afk/bin/afk.mjs" ]; then
+      printf '%s\n' "$root/skills/engineering/afk/bin/afk.mjs"
+      return 0
+    fi
+  done
+  return 1
+}
+
+latest_cache_launcher() {
+  local dir
+  for dir in "$HOME"/.codex/plugins/cache/red-skills/dev/* "$HOME"/.claude/plugins/cache/red-skills/dev/*; do
+    [ -f "$dir/skills/engineering/afk/bin/afk.mjs" ] &&
+      printf '%s\t%s\n' "$(basename "$dir")" "$dir/skills/engineering/afk/bin/afk.mjs"
+  done | sort -V | tail -1 | cut -f2-
+}
+
+# There is deliberately NO cached-bundle fallback here. ADR 0147 deleted the dev
+# runtime bundle, so `dev-3.21.0.bundle.min.mjs` is the last one that will ever
+# exist and resolving it runs a 3.21.0-era binary against v4 state. A machine
+# that still holds one gets the message below, not silently old code.
+
+launcher="$(env_launcher || true)"
+if [ -n "$launcher" ]; then
+  exec node "$launcher" "$@"
+fi
+
+launcher="$(latest_cache_launcher || true)"
+if [ -n "$launcher" ]; then
+  exec node "$launcher" "$@"
+fi
+
+cat >&2 <<'EOF'
+red-skills-dev: no RedSkills dev runtime found.
+
+Expected one of:
+- an installed dev plugin under ~/.codex/plugins/cache/red-skills/dev/*
+- an installed dev plugin under ~/.claude/plugins/cache/red-skills/dev/*
+
+The dev runtime bundle was deleted by ADR 0147; any leftover
+~/.cache/red-skills/bundles/dev-*.bundle.min.mjs is inert and safe to remove.
+
+Fallback:
+  npx -y -p @reddb-io/red-skills@<version> red-skills-dev "$@"
+
+Run /red-setup in a repo with plugins.dev.enabled: true, then restart the
+agent session so the plugin SessionStart hook can warm the runtime cache, or use
+the npm direct-run fallback above for a fresh machine.
+EOF
+exit 127
+SH
+
+cat >"$rsp_target" <<'SH'
+#!/usr/bin/env bash
+set -euo pipefail
+
+env_bundle() {
+  local root bundle
+  for root in \
+    "${RED_SKILLS_DEV_PLUGIN_ROOT:-}" \
+    "${CLAUDE_PLUGIN_ROOT:-}" \
+    "${CODEX_PLUGIN_ROOT:-}" \
+    "${OPENCODE_PLUGIN_ROOT:-}"
+  do
+    [ -n "$root" ] || continue
+    for bundle in \
+      "$root/../../dist/rsp.bundle.min.mjs" \
+      "$root/dist/rsp.bundle.min.mjs"
+    do
+      if [ -f "$bundle" ]; then
+        printf '%s\n' "$bundle"
+        return 0
+      fi
+    done
+  done
+  return 1
+}
+
+latest_cache_bundle() {
+  local dir bundle
+  for dir in "$HOME"/.codex/plugins/cache/red-skills/dev/* "$HOME"/.claude/plugins/cache/red-skills/dev/*; do
+    [ -d "$dir" ] || continue
+    for bundle in "$dir/../../dist/rsp.bundle.min.mjs" "$dir/dist/rsp.bundle.min.mjs"; do
+      [ -f "$bundle" ] &&
+        printf '%s\t%s\n' "$(basename "$dir")" "$bundle"
+    done
+  done | sort -V | tail -1 | cut -f2-
+}
+
+latest_bundle() {
+  local cache_root bundle version
+  cache_root="${RED_SKILLS_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/red-skills/bundles}"
+
+  if [ -f "$cache_root/rsp.bundle.min.mjs" ]; then
+    printf '%s\n' "$cache_root/rsp.bundle.min.mjs"
+    return 0
+  fi
+
+  for bundle in "$cache_root"/rsp-*.bundle.min.mjs; do
+    [ -f "$bundle" ] || continue
+    version="${bundle##*/rsp-}"
+    version="${version%.bundle.min.mjs}"
+    printf '%s\t%s\n' "$version" "$bundle"
+  done | sort -V | tail -1 | cut -f2-
+}
+
+find_red_binary() {
+  local cache_root red version
+  cache_root="${RED_SKILLS_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/red-skills/bundles}"
+
+  for red in "$cache_root"/reddb/*/red "$cache_root"/reddb/*/red.exe; do
+    [ -x "$red" ] || continue
+    version="${red%/*}"
+    version="${version##*/}"
+    printf '%s\t%s\n' "$version" "$red"
+  done | sort -V | tail -1 | cut -f2-
+}
+
+with_red_binary() {
+  local red
+  red="$(find_red_binary || true)"
+  if [ -n "$red" ]; then
+    REDDB_BIN="$red" exec node "$@"
+  fi
+  exec node "$@"
+}
+
+bundle="$(env_bundle || true)"
+if [ -n "$bundle" ]; then
+  with_red_binary "$bundle" "$@"
+fi
+
+bundle="$(latest_cache_bundle || true)"
+if [ -n "$bundle" ]; then
+  with_red_binary "$bundle" "$@"
+fi
+
+bundle="$(latest_bundle || true)"
+if [ -n "$bundle" ]; then
+  with_red_binary "$bundle" "$@"
+fi
+
+cat >&2 <<'EOF'
+rsp: no RedSkills rsp runtime found.
+
+Expected one of:
+- an installed dev plugin with dist/rsp.bundle.min.mjs under ~/.codex/plugins/cache/red-skills/dev/*
+- an installed dev plugin with dist/rsp.bundle.min.mjs under ~/.claude/plugins/cache/red-skills/dev/*
+- a warmed rsp bundle under ${RED_SKILLS_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/red-skills/bundles}
+
+Run /red-setup in a repo with plugins.dev.enabled: true, then restart the
+agent session so the plugin SessionStart hook can warm the runtime cache.
+EOF
+exit 127
+SH
+
+chmod 0755 "$dev_target" "$rsp_target"
+printf 'installed %s\n' "$dev_target"
+printf 'installed %s\n' "$rsp_target"

package/runtime/plugins/dev/skills/engineering/red-setup/workflows/red-issues-needs-triage.yml

@@ -0,0 +1,36 @@
+# Auto-applies the `needs-triage` label to any newly opened or reopened issue
+# that has no labels yet. Keeps fresh issues from slipping past `/triage` and
+# `/afk` (which only consumes `ready-for-agent`).
+#
+# Installed by `/red-setup`. Filename prefix `red-` marks it as belonging
+# to the RedSkills ecosystem.
+
+name: red-issues-needs-triage
+
+on:
+  issues:
+    types: [opened, reopened]
+
+permissions:
+  issues: write
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const issue = context.payload.issue;
+            const labels = (issue.labels || []).map(l => l.name);
+            if (labels.length > 0) {
+              core.info(`Issue #${issue.number} already labelled (${labels.join(', ')}). Skipping.`);
+              return;
+            }
+            await github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo:  context.repo.repo,
+              issue_number: issue.number,
+              labels: ['needs-triage']
+            });
+            core.info(`Applied 'needs-triage' to #${issue.number}.`);

package/runtime/plugins/dev/skills/engineering/wizard/template.sh

@@ -0,0 +1,211 @@
+#!/usr/bin/env bash
+#
+# A wizard — walks a human through a manual procedure step by step.
+# Generated by the /wizard skill.
+#
+# Everything above the "STAGES" marker is the wizard library: do not hand-edit
+# it. Author the per-step stages below the marker.
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────────────────────────────────
+# Wizard library — delightful, consistent UX. Identical across every wizard.
+# ──────────────────────────────────────────────────────────────────────────
+
+if [[ -t 1 ]] && command -v tput >/dev/null 2>&1 && [[ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]]; then
+  BOLD=$(tput bold); DIM=$(tput dim); RESET=$(tput sgr0)
+  BLUE=$(tput setaf 4); GREEN=$(tput setaf 2); YELLOW=$(tput setaf 3); RED=$(tput setaf 1)
+else
+  BOLD=""; DIM=""; RESET=""; BLUE=""; GREEN=""; YELLOW=""; RED=""
+fi
+
+# Author sets these two at the top of the stages section.
+TOTAL_STAGES=0
+TOTAL_MINUTES=0
+
+_STAGE_INDEX=0
+_MINUTES_ELAPSED=0
+ENV_FILE="${ENV_FILE:-.env}"
+WRITTEN_ENV=()    # KEYs written to ENV_FILE this run
+WRITTEN_SECRET=() # secret NAMEs set this run
+SKIPPED=()        # things we couldn't do (e.g. gh missing)
+
+# _clear — wipe the terminal so only the current step is on screen. No-op when
+# output isn't a terminal, so piped logs stay readable.
+_clear() {
+  [[ -t 1 ]] || return 0
+  if command -v tput >/dev/null 2>&1; then tput clear; else printf '\033[2J\033[3J\033[H'; fi
+}
+
+# banner "Title" — opening frame: what this wizard does and how long it takes.
+banner() {
+  _clear
+  printf '\n%s%s  %s%s\n' "$BOLD" "$BLUE" "$1" "$RESET"
+  printf '%s  %s stages · about %s minutes%s\n\n' \
+    "$DIM" "$TOTAL_STAGES" "$TOTAL_MINUTES" "$RESET"
+  printf '%s  You drive the browser; this wizard tells you exactly what to do and\n' "$DIM"
+  printf '  captures the values you copy back. Stop any time with Ctrl-C and re-run\n'
+  printf '  later — it remembers values already saved.%s\n' "$RESET"
+  pause "Ready to start?"
+}
+
+# stage "Name" <minutes> — clear the screen, then announce a stage and show
+# progress + time remaining. Clearing keeps only the current step on screen.
+stage() {
+  _clear
+  _STAGE_INDEX=$((_STAGE_INDEX + 1))
+  local remaining=$((TOTAL_MINUTES - _MINUTES_ELAPSED))
+  (( remaining < 0 )) && remaining=0
+  _MINUTES_ELAPSED=$((_MINUTES_ELAPSED + ${2:-0}))
+  printf '\n%s%s▸ Stage %s/%s · %s%s  %s(~%s min left)%s\n' \
+    "$BOLD" "$BLUE" "$_STAGE_INDEX" "$TOTAL_STAGES" "$1" "$RESET" "$DIM" "$remaining" "$RESET"
+}
+
+# say "..." — a plain instruction line.
+say()  { printf '  %s\n' "$1"; }
+# step "..." — a numbered-feeling action the human takes in the browser.
+step() { printf '  %s•%s %s\n' "$BLUE" "$RESET" "$1"; }
+note() { printf '  %s%s%s\n' "$DIM" "$1" "$RESET"; }
+warn() { printf '  %s⚠ %s%s\n' "$YELLOW" "$1" "$RESET"; }
+
+# open_url URL — open in the human's browser, cross-platform incl. WSL.
+open_url() {
+  local url="$1"
+  printf '  %s↗ opening%s %s\n' "$GREEN" "$RESET" "$url"
+  { if   command -v wslview     >/dev/null 2>&1; then wslview "$url"
+    elif command -v explorer.exe >/dev/null 2>&1; then explorer.exe "$url"
+    elif command -v xdg-open    >/dev/null 2>&1; then xdg-open "$url"
+    elif command -v open        >/dev/null 2>&1; then open "$url"
+    else warn "couldn't open a browser — visit it manually: $url"; fi
+  } >/dev/null 2>&1 || warn "couldn't open a browser — visit it manually: $url"
+}
+
+# pause "msg" — wait for the human to confirm they've done the manual part.
+pause() {
+  printf '  %s%s%s ' "$DIM" "${1:-Press Enter to continue}" "$RESET"
+  read -r _ || true
+}
+
+# confirm "question" — y/N gate; returns success on yes.
+confirm() {
+  local reply=""
+  printf '  %s? %s [y/N] ' "$YELLOW" "$1"
+  read -r reply || true
+  [[ "$reply" =~ ^[Yy] ]]
+}
+
+# _existing KEY — current value of KEY in ENV_FILE, if any.
+_existing() {
+  [[ -f "$ENV_FILE" ]] || return 1
+  local line; line=$(grep -E "^${1}=" "$ENV_FILE" | tail -n1) || return 1
+  printf '%s' "${line#*=}"
+}
+
+# ask KEY "Prompt" — read a value into $KEY. Offers the existing .env value as
+# a default on re-runs (Enter keeps it). Visible input (non-secret).
+ask() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -r input || true
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# ask_secret KEY "Prompt" — like ask, but input is hidden.
+ask_secret() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -rs input || true
+  printf '\n'
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# write_env KEY VALUE — upsert KEY=VALUE into ENV_FILE (creates it; replaces
+# any existing line). Idempotent.
+write_env() {
+  local key="$1" value="$2" tmp
+  touch "$ENV_FILE"
+  tmp=$(mktemp)
+  grep -vE "^${key}=" "$ENV_FILE" > "$tmp" || true
+  printf '%s=%s\n' "$key" "$value" >> "$tmp"
+  mv "$tmp" "$ENV_FILE"
+  WRITTEN_ENV+=("$key")
+  printf '  %s✓ wrote%s %s → %s\n' "$GREEN" "$RESET" "$key" "$ENV_FILE"
+}
+
+# set_secret NAME VALUE — set a GitHub Actions repo secret via gh. Falls back
+# to a warning (and records it) if gh is unavailable or unauthenticated.
+set_secret() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if printf '%s' "$value" | gh secret set "$name" >/dev/null 2>&1; then
+      WRITTEN_SECRET+=("$name")
+      printf '  %s✓ set%s GitHub secret %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub secret $name (set it manually: gh secret set $name)")
+  warn "skipped GitHub secret $name — gh not ready; set it later"
+}
+
+# set_var NAME VALUE — set a GitHub Actions repo variable (non-secret).
+set_var() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if gh variable set "$name" --body "$value" >/dev/null 2>&1; then
+      printf '  %s✓ set%s GitHub variable %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub variable $name")
+  warn "skipped GitHub variable $name — gh not ready; set it later"
+}
+
+# finish — clear, then a closing summary of everything configured.
+finish() {
+  _clear
+  printf '\n%s%s  ✓ Setup complete%s\n' "$BOLD" "$GREEN" "$RESET"
+  (( ${#WRITTEN_ENV[@]} ))    && note "wrote ${#WRITTEN_ENV[@]} value(s) to $ENV_FILE: ${WRITTEN_ENV[*]}"
+  (( ${#WRITTEN_SECRET[@]} )) && note "set ${#WRITTEN_SECRET[@]} GitHub secret(s): ${WRITTEN_SECRET[*]}"
+  if (( ${#SKIPPED[@]} )); then
+    printf '\n'; warn "still to do by hand:"
+    for s in "${SKIPPED[@]}"; do note "  - $s"; done
+  fi
+  printf '\n'
+}
+
+# ──────────────────────────────────────────────────────────────────────────
+# STAGES — author this section. One stage() per step the human takes.
+# Replace the example below. Set the two totals to match the stages you write.
+# ──────────────────────────────────────────────────────────────────────────
+
+TOTAL_STAGES=1
+TOTAL_MINUTES=5
+
+banner "Stripe setup"
+
+# ── Example stage: replace with your real steps ───────────────────────────
+stage "Stripe — API keys" 5
+say "We'll grab your Stripe test keys and store them for local dev + CI."
+open_url "https://dashboard.stripe.com/test/apikeys"
+step "On the API keys page, copy the Publishable key (starts pk_test_)."
+ask STRIPE_PUBLISHABLE_KEY "Paste the publishable key:"
+step "Click 'Reveal test key' on the Secret key row, then copy it."
+ask_secret STRIPE_SECRET_KEY "Paste the secret key:"
+write_env STRIPE_PUBLISHABLE_KEY "$STRIPE_PUBLISHABLE_KEY"
+write_env STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"
+set_secret STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"   # CI needs this one
+# ──────────────────────────────────────────────────────────────────────────
+
+finish

package/runtime/plugins/dev/skills/engineering/zoom-out/scripts/graph-mode-plumbing.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Graph-mode memory plumbing for zoom-out.
+# Source only; do not execute directly. Called by zoom-out Gather Context
+# when Memory is available. All reads only — no writes, no ingest, no reindex.
+
+_zoom_out_focus_label="<skill/module/file/concept label from the user's request, or empty>"
+_zoom_out_path_from="<first explicitly named skill/module/file/concept, or empty>"
+_zoom_out_path_to="<second explicitly named skill/module/file/concept, or empty>"
+_zoom_out_target_file="<focused file path when the user's request names one, or empty>"
+_zoom_out_target_symbol="<focused symbol name when the user's request names one, or empty>"
+if { [ -f .red/config.yaml ] && grep -qE '^[[:space:]]+memory:' .red/config.yaml; } || [ -f .red/memory/config.json ]; then
+  _bridge="${CLAUDE_PLUGIN_ROOT:-}/scripts/memory-bridge.sh"
+  [ -f "$_bridge" ] || _bridge="$(git rev-parse --show-toplevel 2>/dev/null)/plugins/dev/scripts/memory-bridge.sh"
+  if [ -f "$_bridge" ] && source "$_bridge"; then
+    MEMORY_REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
+    _memory_mode="$(memory_mode . 2>/dev/null || printf 'unavailable\n')"
+    if [ "$_memory_mode" = "graph" ]; then
+      if memory_graph_ready .; then
+        if [ -n "$_zoom_out_path_from" ] && [ -n "$_zoom_out_path_to" ]; then
+          memory_path . "$_zoom_out_path_from" "$_zoom_out_path_to" bfs
+        fi
+        if [ -n "$_zoom_out_target_file" ] || [ -n "$_zoom_out_target_symbol" ]; then
+          memory_structural_impact . "$_zoom_out_target_file" "$_zoom_out_target_symbol"
+        fi
+        if [ -n "$_zoom_out_focus_label" ]; then
+          memory_neighbors . "$_zoom_out_focus_label" 1 both
+        fi
+        memory_recall . "<2-6 keywords for the code area>"
+      else
+        _zoom_out_memory_ingest_hint=1
+      fi
+    else
+      memory_recall . "<2-6 keywords for the code area>"
+    fi
+  fi
+fi

package/runtime/plugins/dev/skills/engineering/zoom-out/scripts/tests/contract.test.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# Contract test for the zoom-out SKILL.md.
+#
+# Asserts the Answer Contract carries an optional Impact section between
+# Relationships and Critical Paths, defines structural impact in the
+# expected terms, requires graph evidence be interpreted (not pasted raw),
+# stays read-only, and does not introduce a new /impact skill or a
+# memory_impact primitive (issue #97, parent #95).
+
+set -euo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+SKILL_MD="$HERE/../../SKILL.md"
+
+if [ ! -f "$SKILL_MD" ]; then
+  echo "FAIL  SKILL.md not found at $SKILL_MD" >&2
+  exit 1
+fi
+
+pass=0
+fail=0
+
+# absent(needle): assert the literal string does NOT appear anywhere in SKILL.md.
+absent() {
+  local label="$1" needle="$2"
+  if grep -qF "$needle" "$SKILL_MD"; then
+    echo "FAIL  $label (forbidden text present: $needle)" >&2
+    fail=$((fail + 1))
+  else
+    echo "ok    $label"
+    pass=$((pass + 1))
+  fi
+}
+
+# present(needle): assert the literal string DOES appear.
+present() {
+  local label="$1" needle="$2"
+  if grep -qF "$needle" "$SKILL_MD"; then
+    echo "ok    $label"
+    pass=$((pass + 1))
+  else
+    echo "FAIL  $label (missing: $needle)" >&2
+    fail=$((fail + 1))
+  fi
+}
+
+# present_re(regex): assert the extended regex matches.
+present_re() {
+  local label="$1" re="$2"
+  if grep -Eq "$re" "$SKILL_MD"; then
+    echo "ok    $label"
+    pass=$((pass + 1))
+  else
+    echo "FAIL  $label (regex did not match: $re)" >&2
+    fail=$((fail + 1))
+  fi
+}
+
+# --- Section order: Relationships -> Impact -> Critical Paths ----------
+
+rel_line="$(grep -n '^2\. \*\*Relationships\*\*' "$SKILL_MD" | head -1 | cut -d: -f1 || true)"
+imp_line="$(grep -n '^3\. \*\*Impact\*\*' "$SKILL_MD" | head -1 | cut -d: -f1 || true)"
+crit_line="$(grep -n '^4\. \*\*Critical Paths\*\*' "$SKILL_MD" | head -1 | cut -d: -f1 || true)"
+risk_line="$(grep -n '^5\. \*\*Risks/Gaps\*\*' "$SKILL_MD" | head -1 | cut -d: -f1 || true)"
+
+if [ -n "$rel_line" ] && [ -n "$imp_line" ] && [ -n "$crit_line" ] && [ -n "$risk_line" ] \
+   && [ "$rel_line" -lt "$imp_line" ] \
+   && [ "$imp_line" -lt "$crit_line" ] \
+   && [ "$crit_line" -lt "$risk_line" ]; then
+  echo "ok    contract lists Relationships < Impact < Critical Paths < Risks/Gaps"
+  pass=$((pass + 1))
+else
+  echo "FAIL  contract section order broken (rel=$rel_line imp=$imp_line crit=$crit_line risk=$risk_line)" >&2
+  fail=$((fail + 1))
+fi
+
+# Impact must be advertised as optional.
+present_re "Impact is optional" '3\. \*\*Impact\*\*.*optional'
+
+# --- Structural impact vocabulary --------------------------------------
+
+present "Impact mentions imports"      "**imports**"
+present "Impact mentions calls"        "**calls**"
+present "Impact mentions containment"  "**containment**"
+present "Impact mentions type-use"     "**type-use**"
+present "Impact mentions docs links"   "**docs links**"
+present "Impact mentions graph neighbors/paths" "**graph neighbors/paths**"
+
+# --- Verification against the current worktree -------------------------
+
+present_re "Impact requires worktree verification" "verified against the current worktree"
+
+# --- Graph-backed structural impact reader -----------------------------
+
+present "Gather Context names target file variable" "_zoom_out_target_file"
+present "Gather Context names target symbol variable" "_zoom_out_target_symbol"
+present "Gather Context calls structural-impact helper" "memory_structural_impact"
+present "Gather Context names structural-impact-reader" "structural-impact-reader"
+present_re "Structural Impact consults graph before fallback" "before falling back to ordinary codebase exploration"
+present_re "Structural Impact includes graph-derived import evidence when available" "imports, importers, definitions, and containing files"
+present_re "Structural Impact degrades cleanly when graph evidence is empty" "behave identically to today's ad-hoc file-reading path"
+
+# --- Interpret graph evidence, no raw dumps ----------------------------
+
+present_re "Impact requires interpretation over raw graph output" "Interpret graph or recall evidence into project terms"
+present_re "Impact forbids raw nodes/edges/paths/recall dump" "do \*\*not\*\* paste raw nodes, edges, paths, recall output"
+
+# --- Read-only, no ingest / reindex / graph writes ---------------------
+
+present_re "Impact is read-only" "This section is \*\*read-only\*\*"
+present_re "Impact forbids ingest/reindex/graph writes" "must not run .*memory:ingest.*reindex.*graph-write"
+present_re "answer-wide read-only restatement" "The entire .zoom-out. answer is read-only"
+
+# --- No new /impact skill or memory_impact primitive -------------------
+
+present_re "contract forbids new /impact skill"        "must not (create or reference|introduce).*/impact"
+present_re "contract forbids memory_impact primitive"  "memory_impact"
+
+# A memory_impact mention is only allowed in the *forbidding* clauses.
+# Make sure it never shows up as a callable primitive invocation.
+if grep -Eq '^[[:space:]]*memory_impact\b|`memory_impact `|\$\(memory_impact' "$SKILL_MD"; then
+  echo "FAIL  memory_impact appears as an invocation, not just a prohibition" >&2
+  fail=$((fail + 1))
+else
+  echo "ok    memory_impact is not invoked anywhere"
+  pass=$((pass + 1))
+fi
+
+# Same guard for a "/impact" skill invocation (allowed only in prohibitions).
+if grep -Eq '(invoke|run|call|use) /impact\b' "$SKILL_MD"; then
+  echo "FAIL  /impact appears as an invocation, not just a prohibition" >&2
+  fail=$((fail + 1))
+else
+  echo "ok    /impact skill is not invoked anywhere"
+  pass=$((pass + 1))
+fi
+
+# --- Structural vs observed impact split (issue #100) ------------------
+
+present "Impact names Structural impact sub-bullet"  "**Structural impact**"
+present "Impact names Observed impact sub-bullet"    "**Observed impact**"
+present_re "Impact separates structural from observed" "separate structural impact from observed impact"
+
+# --- Observed-impact vocabulary ----------------------------------------
+
+present    "Observed impact cites Reasoning attempts"     "**Reasoning attempts**"
+present    "Observed impact cites touched-together files" "**touched together**"
+present    "Observed impact cites repeated failures"      "**repeated**"
+present    "Observed impact cites retry chains"           "**retry chains**"
+present    "Observed impact cites validation summaries"   "**validation summaries**"
+present_re "Observed impact frames evidence as operational history" "operational history"
+present_re "Observed impact is not authoritative product direction" "not authoritative product (direction|requirements)"
+
+# --- Graceful degradation ----------------------------------------------
+
+present_re "Impact degrades cleanly when attempt evidence is absent" "degrade cleanly"
+present_re "Impact falls back to structural-only when attempts are missing" "drop the Observed impact sub-bullet"
+
+# --- No raw graph dump, attempts included ------------------------------
+
+present_re "Impact forbids raw attempt-record dumps" "do \*\*not\*\* paste raw nodes, edges, paths, recall output, attempt records"
+
+# --- Summary -----------------------------------------------------------
+
+echo
+echo "passed: $pass"
+echo "failed: $fail"
+[ "$fail" -eq 0 ]