@intentsolutionsio/contributing-clanker 0.1.1

package/skills/contribute/scripts/catalog-coverage.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# catalog-coverage.sh — report which catalog modes have gate implementations.
+#
+# Closes contributing-clanker-p5q.3.
+#
+# The 62-failure-mode catalog lives at:
+#   <repo>/000-docs/007-DR-CATG-failure-mode-catalog.md
+# Each row maps a mode ID (e.g. A1, B12, C5) to a "Gate" column with either:
+#   - a real gate filename (e.g. "a01-already-assigned")
+#   - "(planned)" for unimplemented modes
+#   - "(see ...)" for modes covered by a different gate via reference
+#
+# Coverage = real-gate count / total catalog count.
+# Output: per-phase table + overall %.
+
+set -uo pipefail
+
+CATALOG="${1:-${HOME}/000-projects/contributing-clanker/000-docs/007-DR-CATG-failure-mode-catalog.md}"
+GATES_DIR="${HOME}/.claude/skills/contribute/scripts/gates"
+
+if [[ ! -f "$CATALOG" ]]; then
+  /usr/bin/printf 'catalog not found: %s\n' "$CATALOG" >&2
+  /usr/bin/printf 'usage: %s [path-to-catalog.md]\n' "$0" >&2
+  exit 2
+fi
+
+if [[ ! -d "$GATES_DIR" ]]; then
+  /usr/bin/printf 'gates dir not found: %s\n' "$GATES_DIR" >&2
+  exit 2
+fi
+
+# Extract catalog rows. Format: | A1 | description | trigger | gate-name |
+# We only care about rows where col 1 is a single-letter+digit ID and col 4
+# (last col) is the gate ref.
+#
+# Each markdown table row: | id | failure | trigger | gate |
+# We want id (col 2 after leading |) and gate (col 5 after leading |).
+parse_catalog() {
+  /usr/bin/awk -F'|' '
+    /^\| *[A-G][0-9]+ *\|/ {
+      gsub(/^[ \t]+|[ \t]+$/, "", $2)   # mode id
+      gsub(/^[ \t]+|[ \t]+$/, "", $5)   # gate ref
+      print $2 "\t" $5
+    }
+  ' "$CATALOG"
+}
+
+# Aggregate per phase (A,B,C,D,E,F,G)
+declare -A phase_total phase_planned phase_implemented
+total=0
+implemented=0
+planned=0
+
+while IFS=$'\t' read -r id gate; do
+  phase="${id:0:1}"
+  phase_total[$phase]=$(( ${phase_total[$phase]:-0} + 1 ))
+  total=$(( total + 1 ))
+  case "$gate" in
+    *planned*)
+      phase_planned[$phase]=$(( ${phase_planned[$phase]:-0} + 1 ))
+      planned=$(( planned + 1 ))
+      ;;
+    *)
+      # Real gate ref. Confirm a script file actually exists for it.
+      # Gate refs in the catalog look like "a01-already-assigned" — match by
+      # prefix lower-case + leading digits.
+      gate_id_normalized=$(/usr/bin/printf '%s' "$gate" | /usr/bin/tr '[:upper:]' '[:lower:]' | /usr/bin/sed 's/[^a-z0-9].*//')
+      if /usr/bin/find "$GATES_DIR" -maxdepth 1 -name "${gate_id_normalized}*.sh" -print -quit 2>/dev/null | /usr/bin/grep -q .; then
+        phase_implemented[$phase]=$(( ${phase_implemented[$phase]:-0} + 1 ))
+        implemented=$(( implemented + 1 ))
+      else
+        phase_planned[$phase]=$(( ${phase_planned[$phase]:-0} + 1 ))
+        planned=$(( planned + 1 ))
+      fi
+      ;;
+  esac
+done < <(parse_catalog)
+
+# Render
+/usr/bin/printf '\nCatalog → Gate coverage\n'
+/usr/bin/printf '═════════════════════════════════════════\n'
+/usr/bin/printf '%-8s %10s %12s %10s\n' "PHASE" "TOTAL" "IMPLEMENTED" "COVERAGE"
+/usr/bin/printf '─────────────────────────────────────────\n'
+for phase in A B C D E F G; do
+  t=${phase_total[$phase]:-0}
+  i=${phase_implemented[$phase]:-0}
+  if [[ $t -gt 0 ]]; then
+    pct=$(( i * 100 / t ))
+    /usr/bin/printf '%-8s %10s %12s %9s%%\n' "$phase" "$t" "$i" "$pct"
+  fi
+done
+/usr/bin/printf '─────────────────────────────────────────\n'
+overall_pct=$(( implemented * 100 / total ))
+/usr/bin/printf '%-8s %10s %12s %9s%%\n' "TOTAL" "$total" "$implemented" "$overall_pct"
+/usr/bin/printf '═════════════════════════════════════════\n\n'
+
+if [[ $planned -gt 0 ]]; then
+  /usr/bin/printf '  %d catalog mode(s) still planned (no gate file).\n\n' "$planned"
+fi

package/skills/contribute/scripts/gate-runner.sh

@@ -0,0 +1,191 @@
+#!/usr/bin/env bash
+# gate-runner.sh — the orchestrator that runs gates for a lifecycle transition.
+#
+# Usage: gate-runner.sh <action> <candidate-path> [<dossier-path>]
+#   action: e.g., "shortlist→claimed", "working→submitted", "open-pr", "post-comment"
+#
+# Discovers gates by glob from ~/.contribute-system/gates/<phase>*.sh,
+# filters by which gates apply to this action (per the gate's filename phase
+# letter and the action's lifecycle stage), runs each in turn with a 10-second
+# timeout, aggregates verdicts.
+#
+# Output: one JSON per gate to stderr (for human-readable progress);
+# final aggregated verdict to stdout.
+#
+# Exit code: 0 if all PASS/WARN/INFORM/SKIP; 1 if any BLOCK (unless every
+# BLOCK was overridden via the candidate's overrides: frontmatter).
+
+set -euo pipefail
+
+ACTION="${1:-}"
+CANDIDATE="${2:-}"
+DOSSIER="${3:-}"
+
+if [[ -z "$ACTION" || -z "$CANDIDATE" ]]; then
+  echo "usage: $0 <action> <candidate-path> [<dossier-path>]" >&2
+  exit 64
+fi
+
+# Discover gates from two dirs, in priority order:
+#   1. Bundled canonical set at skill/scripts/gates/ (discovered via script location)
+#   2. User-override gates at ~/.contribute-system/gates/ (personal additions / overrides)
+# This split means the bundled set is always present (distributable) and users can
+# add custom gates or fork existing ones without modifying the skill package.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+BUNDLED_GATE_DIR="${SCRIPT_DIR}/gates"
+USER_GATE_DIR="$HOME/.contribute-system/gates"
+LOG="$HOME/.contribute-system/log.jsonl"
+NOW=$(/usr/bin/date -u +%Y-%m-%dT%H:%M:%SZ)
+
+# Map action → relevant gate phases. Gates are filtered by phase letter
+# (first char of filename). An action runs all gates in its applicable phases.
+case "$ACTION" in
+  "open→shortlist")        PHASES="A" ;;
+  "shortlist→claimed")     PHASES="A E" ;;
+  "claimed→working")       PHASES="A B" ;;
+  "working→submitted")     PHASES="B C E F G" ;;
+  "open-pr")               PHASES="C E" ;;
+  "flip-to-ready")         PHASES="C" ;;
+  "post-comment")          PHASES="D" ;;
+  "open-issue")            PHASES="D" ;;
+  *)                       PHASES="A B C D E F G" ;; # unknown: run everything
+esac
+
+# Read disabled_gates from dossier (per-repo opt-out)
+DISABLED=""
+if [[ -n "$DOSSIER" && -f "$DOSSIER" ]]; then
+  DISABLED=$(/usr/bin/awk '/^---$/{fm=!fm?1:2;next} fm==1 && /^disabled_gates:/{
+    sub(/^disabled_gates:[[:space:]]*\[/,""); sub(/\][[:space:]]*$/,""); gsub(/[[:space:]]/,""); print; exit
+  }' "$DOSSIER" 2>/dev/null || /usr/bin/echo "")
+fi
+
+# Read repo + branch from candidate frontmatter
+REPO=$(/usr/bin/awk '/^---$/{fm=!fm?1:2;next} fm==1 && /^repo:/{sub(/^repo:[[:space:]]*/,""); print; exit}' "$CANDIDATE" 2>/dev/null || /usr/bin/echo "")
+BRANCH=$(/usr/bin/awk '/^---$/{fm=!fm?1:2;next} fm==1 && /^branch:/{sub(/^branch:[[:space:]]*/,""); print; exit}' "$CANDIDATE" 2>/dev/null || /usr/bin/echo "")
+
+# Build the input JSON once (passed to every gate)
+INPUT_JSON=$(jq -nc \
+  --arg candidate "$CANDIDATE" \
+  --arg dossier "$DOSSIER" \
+  --arg action "$ACTION" \
+  --arg repo "$REPO" \
+  --arg branch "$BRANCH" \
+  '{candidate: $candidate, dossier: $dossier, action: $action, env: {repo: $repo, branch: $branch}}')
+
+# Discover gate scripts for the relevant phases.
+# Bundled gates first, then user-override dir.
+# A user gate with the same basename shadows the bundled one (by position in GATES array).
+# gate-runner runs all discovered gates; SKIP is cheap.
+declare -A SEEN_GATES=()
+GATES=()
+for DIR in "$BUNDLED_GATE_DIR" "$USER_GATE_DIR" ; do
+  [[ -d "$DIR" ]] || continue
+  for PHASE in $PHASES ; do
+    for GATE in "$DIR"/${PHASE,,}*.sh ; do
+      [[ -f "$GATE" && -x "$GATE" ]] || continue
+      BN=$(/usr/bin/basename "$GATE")
+      # User-override dir wins — if a gate with same name was already queued from
+      # bundled dir, replace it. Simple: add all, let user-dir overwrite.
+      [[ -z "${SEEN_GATES[$BN]:-}" ]] && GATES+=("$GATE") || true
+      SEEN_GATES[$BN]="$GATE"
+    done
+  done
+done
+
+if [[ "${#GATES[@]}" -eq 0 ]]; then
+  /usr/bin/echo '{"verdict":"PASS","gates_run":0,"reason":"no gates applicable for this action"}'
+  exit 0
+fi
+
+# Run each gate. Aggregate.
+PASS_COUNT=0
+WARN_COUNT=0
+BLOCK_COUNT=0
+INFORM_COUNT=0
+SKIP_COUNT=0
+BLOCKERS=()
+WARNINGS=()
+
+/usr/bin/printf '\n=== gate-runner: %s — %d gates ===\n' "$ACTION" "${#GATES[@]}" >&2
+
+for GATE in "${GATES[@]}" ; do
+  GATE_NAME=$(/usr/bin/basename "$GATE" .sh)
+  GATE_ID=$(/usr/bin/printf '%s' "$GATE_NAME" | /usr/bin/cut -d- -f1 | /usr/bin/tr 'a-z' 'A-Z')
+
+  # Per-repo opt-out check
+  if /usr/bin/echo ",$DISABLED," | /usr/bin/grep -qi ",$GATE_ID,"; then
+    /usr/bin/printf '  [%s] SKIP — disabled per dossier\n' "$GATE_ID" >&2
+    SKIP_COUNT=$(( SKIP_COUNT + 1 ))
+    continue
+  fi
+
+  # Run the gate with timeout. Capture stdout. Exit non-zero = treat as BLOCK.
+  if VERDICT_JSON=$(/usr/bin/timeout 10 bash -c "/usr/bin/printf '%s' '$INPUT_JSON' | '$GATE'" 2>/dev/null); then
+    : # ok, parse verdict
+  else
+    VERDICT_JSON=$(jq -nc --arg gid "$GATE_ID" '{severity:"BLOCK", gate:$gid, reason:"gate timed out or crashed (>10s or non-zero exit) — fail-closed", fix_hint:"check the gate script for bugs; preamble.sh should have caught it"}')
+  fi
+
+  # Defensive parse: if the gate returned malformed JSON, treat as BLOCK
+  if ! /usr/bin/printf '%s' "$VERDICT_JSON" | jq -e . >/dev/null 2>&1; then
+    VERDICT_JSON=$(jq -nc --arg gid "$GATE_ID" --arg raw "$VERDICT_JSON" '{severity:"BLOCK", gate:$gid, reason:"gate returned malformed JSON — fail-closed", fix_hint:("raw stdout: " + ($raw | tostring))}')
+  fi
+
+  SEV=$(/usr/bin/printf '%s' "$VERDICT_JSON" | jq -r '.severity')
+  REASON=$(/usr/bin/printf '%s' "$VERDICT_JSON" | jq -r '.reason')
+  FIX=$(/usr/bin/printf '%s' "$VERDICT_JSON" | jq -r '.fix_hint // ""')
+
+  case "$SEV" in
+    PASS)   PASS_COUNT=$((PASS_COUNT+1));   /usr/bin/printf '  [%s] \033[32mPASS\033[0m  — %s\n' "$GATE_ID" "$REASON" >&2 ;;
+    WARN)   WARN_COUNT=$((WARN_COUNT+1));   WARNINGS+=("$GATE_ID: $REASON ($FIX)") ; /usr/bin/printf '  [%s] \033[33mWARN\033[0m  — %s\n' "$GATE_ID" "$REASON" >&2 ;;
+    BLOCK)  BLOCK_COUNT=$((BLOCK_COUNT+1)); BLOCKERS+=("$GATE_ID: $REASON ($FIX)") ; /usr/bin/printf '  [%s] \033[31mBLOCK\033[0m — %s\n         fix: %s\n' "$GATE_ID" "$REASON" "$FIX" >&2 ;;
+    INFORM) INFORM_COUNT=$((INFORM_COUNT+1)); /usr/bin/printf '  [%s] INFO  — %s\n' "$GATE_ID" "$REASON" >&2 ;;
+    SKIP)   SKIP_COUNT=$((SKIP_COUNT+1));   /usr/bin/printf '  [%s] SKIP  — %s\n' "$GATE_ID" "$REASON" >&2 ;;
+    *)      BLOCK_COUNT=$((BLOCK_COUNT+1)); BLOCKERS+=("$GATE_ID: unknown severity '$SEV'") ; /usr/bin/printf '  [%s] BLOCK — unknown severity: %s\n' "$GATE_ID" "$SEV" >&2 ;;
+  esac
+
+  # Append run to log
+  /usr/bin/printf '%s\n' "$(jq -nc \
+    --arg ts "$NOW" \
+    --arg gate "$GATE_ID" \
+    --arg action "$ACTION" \
+    --arg repo "$REPO" \
+    --arg sev "$SEV" \
+    --arg reason "$REASON" \
+    '{ts: $ts, event: "gate_run", details: {gate: $gate, action: $action, repo: $repo, severity: $sev, reason: $reason}}')" >> "$LOG" 2>/dev/null || true
+done
+
+# Check overrides on the candidate (any BLOCK gate the user explicitly waived).
+OVERRIDDEN=()
+if [[ -f "$CANDIDATE" ]] && /usr/bin/grep -q '^overrides:' "$CANDIDATE" 2>/dev/null; then
+  while IFS= read -r OG; do
+    OVERRIDDEN+=("$OG")
+  done < <(/usr/bin/awk '/^overrides:/{flag=1;next} /^[a-z_]+:/{flag=0} flag && /gate:/{sub(/.*gate:[[:space:]]*/,"");sub(/[[:space:]]*,.*$/,"");print}' "$CANDIDATE" 2>/dev/null)
+fi
+
+# Filter BLOCKERS against OVERRIDDEN
+EFFECTIVE_BLOCKS=()
+for B in "${BLOCKERS[@]}"; do
+  BID="${B%%:*}"
+  IS_OVERRIDDEN=0
+  for O in "${OVERRIDDEN[@]}"; do
+    [[ "$O" == "$BID" ]] && { IS_OVERRIDDEN=1; break; }
+  done
+  if [[ "$IS_OVERRIDDEN" -eq 0 ]]; then
+    EFFECTIVE_BLOCKS+=("$B")
+  fi
+done
+
+# Final verdict
+TOTAL=${#GATES[@]}
+EFFECTIVE_BLOCK_COUNT=${#EFFECTIVE_BLOCKS[@]}
+/usr/bin/printf '\n=== summary: %d gates · %d PASS · %d WARN · %d BLOCK (%d after overrides) · %d INFORM · %d SKIP ===\n\n' \
+  "$TOTAL" "$PASS_COUNT" "$WARN_COUNT" "$BLOCK_COUNT" "$EFFECTIVE_BLOCK_COUNT" "$INFORM_COUNT" "$SKIP_COUNT" >&2
+
+if [[ "$EFFECTIVE_BLOCK_COUNT" -gt 0 ]]; then
+  /usr/bin/echo "$(jq -nc --argjson b "$(printf '%s\n' "${EFFECTIVE_BLOCKS[@]}" | jq -R . | jq -s .)" --argjson w "$(printf '%s\n' "${WARNINGS[@]}" | jq -R . | jq -s .)" --argjson n "$EFFECTIVE_BLOCK_COUNT" '{verdict: "BLOCK", effective_blocks: $n, blockers: $b, warnings: $w}')"
+  exit 1
+else
+  /usr/bin/echo "$(jq -nc --argjson w "$(printf '%s\n' "${WARNINGS[@]}" | jq -R . | jq -s .)" --argjson p "$PASS_COUNT" '{verdict: "PASS", gates_passed: $p, warnings: $w}')"
+  exit 0
+fi

package/skills/contribute/scripts/gates/a01-already-assigned.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Catalog: A1 — Claim already-assigned issue
+# Mitigates: Tracer-Cloud opensre #1129 trap (2026-05-02) — issue assigned to
+# unKnownNG day before our scout run; he was actively asking maintainer
+# clarifying questions in comments. We almost claim-jumped real human work.
+source "$(dirname "$0")/lib/preamble.sh"
+
+gate_read_input
+
+# Pull issue number from candidate frontmatter
+ISSUE_NUM=$(fm_field "$GATE_CANDIDATE_PATH" "issue_number")
+if [[ -z "$ISSUE_NUM" || -z "$GATE_REPO" ]]; then
+  gate_skip "no issue_number or repo in candidate"
+fi
+
+# Live check (this is one of the few gates that MUST be live — assignment
+# state changes too fast to trust the dossier)
+ASSIGNEES=$(gh_safe issue view "$ISSUE_NUM" --repo "$GATE_REPO" --json assignees --jq '[.assignees[].login] | join(",")' || /usr/bin/echo "")
+
+if [[ -n "$ASSIGNEES" ]]; then
+  gate_block "issue is assigned to [$ASSIGNEES]" "wait for them to drop it, or pick a different candidate. Override only if you've coordinated with the assignee in a comment."
+fi
+
+gate_pass "no assignees on issue"

package/skills/contribute/scripts/gates/a02-already-shipped.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Catalog: A2 — Claim work that's already merged in another PR
+# Mitigates: PostHog #55412 trap (2026-05-02) — issue was open but PR #57145
+# had already merged the principled fix. Without this check we'd have
+# submitted a duplicate and burned an AI policy strike.
+source "$(dirname "$0")/lib/preamble.sh"
+
+gate_read_input
+
+ISSUE_NUM=$(fm_field "$GATE_CANDIDATE_PATH" "issue_number")
+if [[ -z "$ISSUE_NUM" || -z "$GATE_REPO" ]]; then
+  gate_skip "no issue_number or repo in candidate"
+fi
+
+# Check each of GitHub's three auto-close keywords. NB: gh search uses --merged
+# (NOT --state=merged), and "X OR Y OR Z" is treated as a literal phrase, so
+# we must run separate calls. (Lessons logged in scout's MEMORY.md.)
+SHIPPED_PR=""
+for KW in closes fixes resolves ; do
+  HIT=$(gh_safe search prs --repo="$GATE_REPO" "$KW #$ISSUE_NUM" --merged --limit 1 --json url --jq '.[0].url // empty' || /usr/bin/echo "")
+  if [[ -n "$HIT" ]]; then
+    SHIPPED_PR="$HIT"
+    break
+  fi
+done
+
+if [[ -n "$SHIPPED_PR" ]]; then
+  gate_block "issue already shipped in $SHIPPED_PR" "the issue is open but its fix has already merged. Post a 'safe to close?' comment on the issue (good citizen move) and pick a different candidate."
+fi
+
+gate_pass "no merged PR claims to close this issue"

package/skills/contribute/scripts/gates/a03-duplicate-flagged.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Catalog: A3 — Issue flagged as duplicate in body or comments
+source "$(dirname "$0")/lib/preamble.sh"
+
+gate_read_input
+
+ISSUE_NUM=$(fm_field "$GATE_CANDIDATE_PATH" "issue_number")
+if [[ -z "$ISSUE_NUM" || -z "$GATE_REPO" ]]; then
+  gate_skip "no issue_number or repo in candidate"
+fi
+
+TEXT=$(gh_safe issue view "$ISSUE_NUM" --repo "$GATE_REPO" --json body,comments --jq '.body + " " + (.comments | map(.body) | join(" "))' || /usr/bin/echo "")
+
+if [[ -z "$TEXT" ]]; then
+  gate_inform "could not fetch issue body/comments"
+fi
+
+if /usr/bin/printf '%s' "$TEXT" | /usr/bin/grep -qiE "(duplicate of|dupe of|see)[[:space:]]+#[0-9]+"; then
+  gate_warn "issue body or comments mention being a duplicate" "verify with the maintainer before claiming; the underlying issue may be elsewhere"
+fi
+
+gate_pass "no duplicate references found"

package/skills/contribute/scripts/gates/a04-issue-age.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# Catalog: A4 — Issue is too old (stale, abandoned, or contested)
+# Mitigates: stale issues are a real anti-signal — either the maintainer
+# decided not to fix it, the underlying code changed and the issue's premise
+# no longer holds, or someone has been silently working on it for months
+# without progress. None of those are good for our merge probability.
+#
+# Thresholds (configurable via dossier `max_issue_age_days:`):
+#   issue_age <= 90 days             → PASS
+#   issue_age 91-180 days            → WARN ("aging — verify it's still actionable")
+#   issue_age 181-365 days           → BLOCK ("stale; recommend pick a fresher target")
+#   issue_age > 365 days             → BLOCK + harder ("zombie issue; fix likely landed elsewhere")
+#
+# A repo with `max_issue_age_days: N` in dossier overrides the default 180.
+source "$(dirname "$0")/lib/preamble.sh"
+
+gate_read_input
+
+ISSUE_NUM=$(fm_field "$GATE_CANDIDATE_PATH" "issue_number")
+if [[ -z "$ISSUE_NUM" || -z "$GATE_REPO" ]]; then
+  gate_skip "no issue_number or repo in candidate"
+fi
+
+# Read max_issue_age from dossier, default 180
+MAX_AGE_DAYS=180
+if [[ -n "$GATE_DOSSIER_PATH" && -f "$GATE_DOSSIER_PATH" ]]; then
+  V=$(fm_field "$GATE_DOSSIER_PATH" "max_issue_age_days")
+  [[ -n "$V" && "$V" =~ ^[0-9]+$ ]] && MAX_AGE_DAYS="$V"
+fi
+
+# Live fetch — issue createdAt + last activity (updatedAt + last comment)
+META_JSON=$(gh_safe issue view "$ISSUE_NUM" --repo "$GATE_REPO" --json createdAt,updatedAt,comments --jq '{createdAt, updatedAt, last_comment_at: (.comments | sort_by(.createdAt) | .[-1].createdAt // null)}' || /usr/bin/echo "")
+
+if [[ -z "$META_JSON" ]] ; then
+  gate_skip "couldn't fetch issue metadata (gh failure?)"
+fi
+
+CREATED=$(/usr/bin/printf '%s' "$META_JSON" | jq -r '.createdAt // ""')
+UPDATED=$(/usr/bin/printf '%s' "$META_JSON" | jq -r '.updatedAt // ""')
+LAST_COMMENT=$(/usr/bin/printf '%s' "$META_JSON" | jq -r '.last_comment_at // ""')
+
+if [[ -z "$CREATED" ]] ; then
+  gate_skip "issue createdAt missing in API response"
+fi
+
+NOW_EPOCH=$(/usr/bin/date -u +%s)
+CREATED_EPOCH=$(/usr/bin/date -u -d "$CREATED" +%s 2>/dev/null || echo 0)
+AGE_DAYS=$(( (NOW_EPOCH - CREATED_EPOCH) / 86400 ))
+
+# Activity recency — most recent of updatedAt or last comment
+LATEST_ACT_EPOCH=0
+if [[ -n "$UPDATED" ]] ; then
+  V=$(/usr/bin/date -u -d "$UPDATED" +%s 2>/dev/null || echo 0)
+  [[ "$V" -gt "$LATEST_ACT_EPOCH" ]] && LATEST_ACT_EPOCH="$V"
+fi
+if [[ -n "$LAST_COMMENT" && "$LAST_COMMENT" != "null" ]] ; then
+  V=$(/usr/bin/date -u -d "$LAST_COMMENT" +%s 2>/dev/null || echo 0)
+  [[ "$V" -gt "$LATEST_ACT_EPOCH" ]] && LATEST_ACT_EPOCH="$V"
+fi
+SILENCE_DAYS=$(( (NOW_EPOCH - LATEST_ACT_EPOCH) / 86400 ))
+
+# Verdicts
+if [[ "$AGE_DAYS" -gt 365 ]] ; then
+  gate_block "issue is ${AGE_DAYS}d old (>365d zombie threshold)" "1+ year-old issues are usually either fixed elsewhere, abandoned, or have premises that no longer apply. Pick a fresher target. Override only with a written rationale referencing what's changed."
+fi
+
+if [[ "$AGE_DAYS" -gt "$MAX_AGE_DAYS" ]] ; then
+  gate_block "issue is ${AGE_DAYS}d old (max for this repo: ${MAX_AGE_DAYS}d)" "stale issue. Maintainer engagement likely dropped. Pick a fresher target — or override with rationale if you have direct maintainer signal that it's still wanted."
+fi
+
+# Activity-based check — even fresh issues with long silence are suspect
+if [[ "$SILENCE_DAYS" -gt 90 ]] ; then
+  gate_warn "issue is fresh (${AGE_DAYS}d old) but no activity in ${SILENCE_DAYS}d" "comment first to ping for current relevance before investing time"
+fi
+
+if [[ "$AGE_DAYS" -gt 90 ]] ; then
+  gate_warn "issue is ${AGE_DAYS}d old (aging — under the ${MAX_AGE_DAYS}d block threshold but past the 90d sweet spot)" "verify the underlying premise still holds in current code; verify maintainer still wants this fix"
+fi
+
+gate_pass "issue is ${AGE_DAYS}d old, last activity ${SILENCE_DAYS}d ago"

package/skills/contribute/scripts/gates/a05-issue-still-open.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# Catalog: A5 — Issue is still OPEN right now (not closed since dossier built)
+# Mitigates: lingdojo/kana-dojo #15441 trap (2026-05-03) — issue was OPEN at
+# 04:54Z when scout shortlisted it; CLOSED at 05:00Z (NOT_PLANNED) by
+# maintainer killing a bot-generated cron issue. Our dossier and the existing
+# A1/A2 gates wouldn't have caught it because they check assignees and
+# already-shipped, not state. This is the simplest gate to write and the
+# highest-value catch — bot-generated issues at active repos can close
+# minutes after discovery.
+source "$(dirname "$0")/lib/preamble.sh"
+
+gate_read_input
+
+ISSUE_NUM=$(fm_field "$GATE_CANDIDATE_PATH" "issue_number")
+if [[ -z "$ISSUE_NUM" || -z "$GATE_REPO" ]]; then
+  gate_skip "no issue_number or repo in candidate"
+fi
+
+STATE_JSON=$(gh_safe issue view "$ISSUE_NUM" --repo "$GATE_REPO" --json state,stateReason,closedAt --jq '{state, stateReason: (.stateReason // ""), closedAt: (.closedAt // "")}' || /usr/bin/echo "")
+
+if [[ -z "$STATE_JSON" ]] ; then
+  gate_skip "couldn't fetch issue state"
+fi
+
+STATE=$(/usr/bin/printf '%s' "$STATE_JSON" | jq -r '.state')
+REASON=$(/usr/bin/printf '%s' "$STATE_JSON" | jq -r '.stateReason')
+CLOSED_AT=$(/usr/bin/printf '%s' "$STATE_JSON" | jq -r '.closedAt' | /usr/bin/cut -c1-19)
+
+if [[ "$STATE" == "CLOSED" ]] ; then
+  gate_block "issue is CLOSED (reason: ${REASON:-unspecified}, closed at ${CLOSED_AT:-unknown})" "issue closed since shortlist. If reason is COMPLETED, fix already shipped — pick a different target. If NOT_PLANNED, maintainer rejected the work — drop the candidate."
+fi
+
+gate_pass "issue state = OPEN"

package/skills/contribute/scripts/gates/a06-claim-etiquette-required.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Catalog: A6 — Repo requires claim-etiquette comment before working
+source "$(dirname "$0")/lib/preamble.sh"
+
+gate_read_input
+
+if [[ -z "$GATE_DOSSIER_PATH" || ! -f "$GATE_DOSSIER_PATH" ]]; then
+  gate_skip "no dossier"
+fi
+
+REQUIRED=$(fm_field "$GATE_DOSSIER_PATH" "etiquette_comment_required")
+if [[ "$REQUIRED" != "true" ]]; then
+  gate_skip "etiquette_comment_required is not true"
+fi
+
+ISSUE_NUM=$(fm_field "$GATE_CANDIDATE_PATH" "issue_number")
+if [[ -z "$ISSUE_NUM" || -z "$GATE_REPO" ]]; then
+  gate_skip "no issue_number or repo in candidate"
+fi
+
+LOGIN=$(gh_safe api user --jq .login || /usr/bin/echo "")
+if [[ -z "$LOGIN" ]]; then
+  gate_inform "could not resolve gh user login"
+fi
+
+COMMENTS=$(gh_safe issue view "$ISSUE_NUM" --repo "$GATE_REPO" --json comments --jq "[.comments[] | select(.author.login == \"$LOGIN\") | .body] | join(\"\n---\n\")" || /usr/bin/echo "")
+
+if [[ -z "$COMMENTS" ]]; then
+  gate_block "no claim comment from $LOGIN found on issue #$ISSUE_NUM" "this repo wants you to comment on the issue before working on it; post a claim comment and re-run the transition"
+fi
+
+if /usr/bin/printf '%s' "$COMMENTS" | /usr/bin/grep -qiE "(i'?d like to take this|i'?ll take this|happy to take this|working on this|claiming this|would like to work on|let me know if i can take|i'?d be happy to work)"; then
+  gate_pass "found claim-shaped comment from $LOGIN"
+fi
+
+gate_block "no claim-shaped comment from $LOGIN on issue #$ISSUE_NUM" "this repo wants you to comment on the issue before working on it; post a claim comment and re-run the transition"

package/skills/contribute/scripts/gates/a09-mention-routing.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Catalog: A9 — @-mentions in claim/PR text when CODEOWNERS routing exists
+source "$(dirname "$0")/lib/preamble.sh"
+
+gate_read_input
+
+if [[ -z "$GATE_DOSSIER_PATH" || ! -f "$GATE_DOSSIER_PATH" ]]; then
+  gate_skip "no dossier"
+fi
+
+# Check for CODEOWNERS in dossier — frontmatter policy_files OR Policy file inventory section
+HAS_CODEOWNERS=""
+POLICY_FM=$(fm_field "$GATE_DOSSIER_PATH" "policy_files")
+if /usr/bin/printf '%s' "$POLICY_FM" | /usr/bin/grep -qi "CODEOWNERS"; then
+  HAS_CODEOWNERS=1
+fi
+if [[ -z "$HAS_CODEOWNERS" ]]; then
+  if /usr/bin/awk '/^## Policy file inventory/{flag=1;next} /^## /{flag=0} flag' "$GATE_DOSSIER_PATH" 2>/dev/null | /usr/bin/grep -qi "\*\*CODEOWNERS\*\*"; then
+    HAS_CODEOWNERS=1
+  fi
+fi
+
+if [[ -z "$HAS_CODEOWNERS" ]]; then
+  gate_skip "no CODEOWNERS in dossier policy inventory"
+fi
+
+# Pick the right draft section based on action
+SECTION=""
+case "$GATE_ACTION" in
+  *post-comment*|*claim*) SECTION="## Claim comment draft" ;;
+  *open-pr*|*pr*) SECTION="## PR body" ;;
+  *) SECTION="## Claim comment draft" ;;
+esac
+
+DRAFT=$(/usr/bin/awk -v s="$SECTION" 'BEGIN{flag=0} $0==s{flag=1;next} /^## /{flag=0} flag' "$GATE_CANDIDATE_PATH" 2>/dev/null || /usr/bin/echo "")
+
+if [[ -z "$DRAFT" ]]; then
+  gate_skip "no draft section found in candidate"
+fi
+
+# Count @-mentions, excluding @me, @everyone, @channel.
+# Use awk (single pass, no pipeline-failure surface) instead of a chained
+# grep | grep | wc — under set -uo pipefail, an empty `grep -oE` returns
+# exit 1, killing the whole pipeline, even though "no mentions" is the
+# correct/expected answer for most drafts.
+MENTIONS=$(/usr/bin/printf '%s' "$DRAFT" | /usr/bin/awk '
+  {
+    for (i = 1; i <= NF; i++) {
+      tok = $i
+      gsub(/[,.;:!?)\]"\x27]+$/, "", tok)
+      if (tok ~ /^@[a-zA-Z0-9-]{2,}$/ && tok !~ /^@(me|everyone|channel)$/) {
+        c++
+      }
+    }
+  }
+  END { print c + 0 }
+')
+
+if [[ "${MENTIONS:-0}" -ge 1 ]]; then
+  gate_warn "$MENTIONS @-mention(s) in draft despite CODEOWNERS routing" "this repo uses CODEOWNERS; explicit @-mentions are usually noise. Drop them unless you have a specific reason to ping someone."
+fi
+
+gate_pass "no @-mentions in draft"

package/skills/contribute/scripts/gates/b01-base-branch.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Catalog: B1 — Local branch is based on a non-default upstream branch
+source "$(dirname "$0")/lib/preamble.sh"
+
+gate_read_input
+
+if [[ -z "$GATE_DOSSIER_PATH" || ! -f "$GATE_DOSSIER_PATH" ]]; then
+  gate_skip "no dossier — cannot determine default_branch"
+fi
+
+DEFAULT_BRANCH=$(fm_field "$GATE_DOSSIER_PATH" "default_branch")
+if [[ -z "$DEFAULT_BRANCH" ]]; then
+  gate_skip "no default_branch in dossier"
+fi
+
+REPO_NAME="${GATE_REPO##*/}"
+CLONE_DIR="$HOME/000-projects/contributing-clanker/$REPO_NAME"
+
+if [[ ! -d "$CLONE_DIR/.git" ]]; then
+  gate_skip "no local clone at $CLONE_DIR"
+fi
+
+cd "$CLONE_DIR" || gate_skip "cannot cd to clone dir"
+
+if /usr/bin/git merge-base --is-ancestor "origin/$DEFAULT_BRANCH" HEAD 2>/dev/null; then
+  gate_pass "HEAD descends from origin/$DEFAULT_BRANCH"
+fi
+
+gate_block "HEAD is not a descendant of origin/$DEFAULT_BRANCH" "rebase onto the default branch: git fetch origin $DEFAULT_BRANCH && git rebase origin/$DEFAULT_BRANCH"

package/skills/contribute/scripts/gates/b02-branch-naming.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# Catalog: B2 — Local branch name violates project's branch_convention regex
+source "$(dirname "$0")/lib/preamble.sh"
+
+gate_read_input
+
+if [[ -z "$GATE_DOSSIER_PATH" || ! -f "$GATE_DOSSIER_PATH" ]]; then
+  gate_skip "no dossier"
+fi
+
+CONVENTION=$(fm_field "$GATE_DOSSIER_PATH" "branch_convention")
+if [[ -z "$CONVENTION" ]]; then
+  gate_skip "no branch_convention in dossier"
+fi
+
+REPO_NAME="${GATE_REPO##*/}"
+CLONE_DIR="$HOME/000-projects/contributing-clanker/$REPO_NAME"
+
+if [[ ! -d "$CLONE_DIR/.git" ]]; then
+  gate_skip "no local clone at $CLONE_DIR"
+fi
+
+cd "$CLONE_DIR" || gate_skip "cannot cd to clone dir"
+
+BRANCH=$(/usr/bin/git rev-parse --abbrev-ref HEAD 2>/dev/null || /usr/bin/echo "")
+if [[ -z "$BRANCH" || "$BRANCH" == "HEAD" ]]; then
+  gate_skip "detached HEAD or unknown branch"
+fi
+
+if /usr/bin/printf '%s' "$BRANCH" | /usr/bin/grep -qE "$CONVENTION"; then
+  gate_pass "branch '$BRANCH' matches convention"
+fi
+
+gate_block "branch '$BRANCH' does not match convention /$CONVENTION/" "rename the branch: git branch -m <new-name-matching-convention>"