@intentsolutionsio/contributing-clanker 0.1.1

package/skills/contribute/scripts/gates/g03-no-changelog-edits.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Catalog: G3 — manual CHANGELOG edits in a repo that auto-generates the changelog
+# Mitigates: clobbers release tooling, gets reverted on next release, looks careless.
+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 auto_changelog policy"
+fi
+
+AUTO=$(fm_field "$GATE_DOSSIER_PATH" "auto_changelog")
+if [[ "$AUTO" != "true" ]]; then
+  gate_skip "dossier auto_changelog is not true"
+fi
+
+REPO_NAME="${GATE_REPO##*/}"
+CLONE="$HOME/000-projects/contributing-clanker/$REPO_NAME"
+
+if [[ ! -d "$CLONE/.git" ]]; then
+  gate_skip "no local clone at $CLONE"
+fi
+
+DEFAULT_BRANCH=$(fm_field "$GATE_DOSSIER_PATH" "default_branch")
+[[ -z "$DEFAULT_BRANCH" ]] && DEFAULT_BRANCH="main"
+
+CHANGED=$(/usr/bin/git -C "$CLONE" diff "$DEFAULT_BRANCH..HEAD" --name-only 2>/dev/null || /usr/bin/echo "")
+
+# Match CHANGELOG.md at root or in any subdir (case-sensitive)
+HITS=$(/usr/bin/printf '%s\n' "$CHANGED" | /usr/bin/grep -E '(^|/)CHANGELOG\.md$' || /usr/bin/echo "")
+
+if [[ -z "$HITS" ]]; then
+  gate_pass "no CHANGELOG.md edits in diff"
+fi
+
+LIST=$(/usr/bin/printf '%s' "$HITS" | /usr/bin/tr '\n' ',' | /usr/bin/sed 's/,$//')
+gate_warn "diff edits CHANGELOG.md ($LIST) but repo auto-generates changelog" "this repo auto-generates CHANGELOG; let the release tooling write it"

package/skills/contribute/scripts/gates/g04-no-version-bump.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# Catalog: G4 — manual version bump in a repo that uses semantic-release / changesets
+# Mitigates: clobbers release tooling, breaks semver, signals unfamiliarity with workflow.
+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 auto_version policy"
+fi
+
+AUTO=$(fm_field "$GATE_DOSSIER_PATH" "auto_version")
+if [[ "$AUTO" != "true" ]]; then
+  gate_skip "dossier auto_version is not true"
+fi
+
+REPO_NAME="${GATE_REPO##*/}"
+CLONE="$HOME/000-projects/contributing-clanker/$REPO_NAME"
+
+if [[ ! -d "$CLONE/.git" ]]; then
+  gate_skip "no local clone at $CLONE"
+fi
+
+DEFAULT_BRANCH=$(fm_field "$GATE_DOSSIER_PATH" "default_branch")
+[[ -z "$DEFAULT_BRANCH" ]] && DEFAULT_BRANCH="main"
+
+DIFF=$(/usr/bin/git -C "$CLONE" diff "$DEFAULT_BRANCH..HEAD" -- package.json Cargo.toml pyproject.toml 2>/dev/null || /usr/bin/echo "")
+
+# Look for added lines that look like version field updates
+HITS=$(/usr/bin/printf '%s\n' "$DIFF" | /usr/bin/grep -E '^\+[[:space:]]*("version"[[:space:]]*:|version[[:space:]]*=)' || /usr/bin/echo "")
+
+if [[ -z "$HITS" ]]; then
+  gate_pass "no manual version field changes detected"
+fi
+
+gate_warn "diff appears to bump a version field (package.json / Cargo.toml / pyproject.toml)" "this repo uses semantic-release / changesets; don't bump versions manually"

package/skills/contribute/scripts/gates/g06-override-rate-limit.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Catalog: G6 — Override rate limit (anti-habituation)
+# Mitigates: Round-1 security GAP-2 — under "just ship it" pressure, an agent
+# learns to invoke overrides reflexively. Without a rate limit, the override
+# mechanism becomes a slop escape valve. ≥3 overrides at one repo in 30d =
+# the system is telling you something; pause and reflect.
+source "$(dirname "$0")/lib/preamble.sh"
+
+gate_read_input
+
+if [[ -z "$GATE_REPO" ]]; then
+  gate_skip "no repo in candidate"
+fi
+
+LOG="$HOME/.contribute-system/log.jsonl"
+[[ ! -f "$LOG" ]] && gate_pass "no log.jsonl yet"
+
+# Count override events in last 30 days at this repo
+THIRTY_AGO=$(/usr/bin/date -u -d '30 days ago' +%s)
+
+OVERRIDE_COUNT=$(jq -r --arg cutoff "$THIRTY_AGO" --arg repo "$GATE_REPO" '
+  select(.event == "gate_override")
+  | select(.details.repo == $repo)
+  | select((.ts | fromdateiso8601) >= ($cutoff | tonumber))
+' "$LOG" 2>/dev/null | jq -s 'length' 2>/dev/null || /usr/bin/echo 0)
+
+if [[ "${OVERRIDE_COUNT:-0}" -ge 3 ]]; then
+  gate_block "$OVERRIDE_COUNT gate overrides at $GATE_REPO in last 30 days (rate limit: 3)" "the system is telling you something. Either your scope at this repo is wrong, your dossier is out of date, or you're forcing through patterns that will eventually trigger an AI-policy closure. To override THIS rate limit: edit ~/.contribute-system/g06-rate-limit-reset && touch it. Don't just shrug it off."
+fi
+
+gate_pass "$OVERRIDE_COUNT/3 overrides at $GATE_REPO in last 30 days"

package/skills/contribute/scripts/gates/lib/preamble.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# Shared preamble for every gate script. Sourced as the first line of every
+# gate. Eliminates the per-script bug surface that Slice 1's scout-discover.sh
+# already showed (empty-array failures under set -u, jq parse errors on
+# malformed gh output, etc.).
+#
+# Per-script gate authors: source this file FIRST, then implement the gate.
+# Use the helpers below for output. NEVER `echo "{...}"` your verdict directly
+# — use gate_pass / gate_warn / gate_block / gate_inform.
+
+set -euo pipefail
+
+# Global error trap — any uncaught error dumps a BLOCK verdict + exits 0.
+# (Per gate contract: exit code is always 0; runner reads stdout JSON.)
+_GATE_ID="${0##*/}"
+_GATE_ID="${_GATE_ID%.sh}"
+
+_gate_err_trap() {
+  local exit_code=$?
+  local line_no=$1
+  /usr/bin/cat <<EOF
+{"severity":"BLOCK","gate":"$_GATE_ID","reason":"gate $_GATE_ID crashed at line $line_no (exit $exit_code) — fail-closed","fix_hint":"check ~/.contribute-system/check-runs/gate-debug.log; this is a bug in the gate itself"}
+EOF
+  exit 0
+}
+trap '_gate_err_trap $LINENO' ERR
+
+# Emit a verdict and exit. Use these — never raw echo.
+#
+# Reason / fix_hint are JSON-escaped via jq -nc. Earlier versions used
+# printf '%s' which dropped raw text into the JSON body and produced
+# invalid output whenever any message contained a literal `"`. Caught by
+# the e02-ai-strike-track unit tests on 2026-05-03.
+gate_pass()   { jq -nc --arg g "$_GATE_ID" --arg r "${1:-ok}" '{severity:"PASS",gate:$g,reason:$r}'; exit 0; }
+gate_warn()   { jq -nc --arg g "$_GATE_ID" --arg r "${1:-warning}" --arg f "${2:-}" '{severity:"WARN",gate:$g,reason:$r,fix_hint:$f}'; exit 0; }
+gate_block()  { jq -nc --arg g "$_GATE_ID" --arg r "${1:-blocked}" --arg f "${2:-}" '{severity:"BLOCK",gate:$g,reason:$r,fix_hint:$f}'; exit 0; }
+gate_inform() { jq -nc --arg g "$_GATE_ID" --arg r "${1:-noted}" '{severity:"INFORM",gate:$g,reason:$r}'; exit 0; }
+gate_skip()   { jq -nc --arg g "$_GATE_ID" --arg r "${1:-not applicable}" '{severity:"SKIP",gate:$g,reason:$r}'; exit 0; }
+
+# Read stdin JSON contract. Sets:
+#   GATE_CANDIDATE_PATH — path to candidate .md file
+#   GATE_DOSSIER_PATH — path to dossier .md (or empty if no dossier)
+#   GATE_ACTION — transition name (e.g., "shortlist→claimed")
+#   GATE_REPO — owner/repo
+#   GATE_INPUT_JSON — raw stdin for any extra fields
+gate_read_input() {
+  GATE_INPUT_JSON=$(/usr/bin/cat)
+  GATE_CANDIDATE_PATH=$(/usr/bin/printf '%s' "$GATE_INPUT_JSON" | jq -r '.candidate // ""')
+  GATE_DOSSIER_PATH=$(/usr/bin/printf '%s' "$GATE_INPUT_JSON" | jq -r '.dossier // ""')
+  GATE_ACTION=$(/usr/bin/printf '%s' "$GATE_INPUT_JSON" | jq -r '.action // ""')
+  GATE_REPO=$(/usr/bin/printf '%s' "$GATE_INPUT_JSON" | jq -r '.env.repo // ""')
+  export GATE_INPUT_JSON GATE_CANDIDATE_PATH GATE_DOSSIER_PATH GATE_ACTION GATE_REPO
+}
+
+# Read a frontmatter field from a markdown file. Returns empty if missing.
+# Usage: val=$(fm_field /path/to/file.md "key")
+fm_field() {
+  local file="$1" key="$2"
+  [[ -f "$file" ]] || { /usr/bin/printf ''; return; }
+  /usr/bin/awk -v k="$key" '
+    /^---$/ { fm = !fm ? 1 : 2; next }
+    fm == 1 && $0 ~ "^"k":" {
+      sub("^"k":[[:space:]]*", "")
+      gsub(/^"|"$/, "")
+      print
+      exit
+    }
+  ' "$file"
+}
+
+# gh wrapper with bounded retry.
+#
+# Constraint: gate-runner enforces a 10s wall-clock timeout per gate. gh_safe
+# must finish well under that to leave room for jq/awk downstream.
+# Tuning: 2 attempts, 0.5s sleep between, 4s per-call timeout.
+# Worst case ≈ 4 + 0.5 + 4 = 8.5s — leaves headroom.
+#
+# Permanent 404s (issue/repo doesn't exist) fail on the first call's HTTP error
+# and don't usefully retry. Transient blips get one retry. That's enough for
+# the read-only gh queries gates make.
+#
+# On final failure returns non-zero with empty stdout — caller decides what
+# missing data means (usually `gate_pass`/`gate_inform`/`gate_skip`).
+gh_safe() {
+  local attempt=1 max=2
+  while (( attempt <= max )); do
+    if /usr/bin/timeout 4 gh "$@" 2>/dev/null; then return 0; fi
+    /usr/bin/sleep 0.5
+    attempt=$(( attempt + 1 ))
+  done
+  return 1
+}
+
+# Helper: log a gate run for observability. Append-only.
+gate_log_run() {
+  local verdict="$1"
+  /usr/bin/printf '%s\n' "$(jq -nc \
+    --arg ts "$(/usr/bin/date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg gate "$_GATE_ID" \
+    --arg action "$GATE_ACTION" \
+    --arg repo "$GATE_REPO" \
+    --arg verdict "$verdict" \
+    '{ts: $ts, event: "gate_run", details: {gate: $gate, action: $action, repo: $repo, verdict: $verdict}}')" \
+    >> ~/.contribute-system/log.jsonl 2>/dev/null || true
+}

package/skills/contribute/scripts/lint-candidate.sh

@@ -0,0 +1,149 @@
+#!/usr/bin/env bash
+# lint-candidate.sh — report missing required body sections in candidate files.
+#
+# Sibling to audit-overrides.sh and catalog-coverage.sh: a read-only reporter
+# that walks ~/.contribute-system/candidates/, reads each candidate's status,
+# and surfaces missing required sections per the matrix in
+# skills/contribute/references/candidate-file-format.md.
+#
+# Required-sections matrix (matches the spec + transition.sh):
+#   shortlist  → ## Scope, ## Files to touch
+#   claimed    → ## Scope, ## Files to touch, ## Claim comment draft
+#   working    → same as claimed
+#   submitted  → ## PR title, ## PR body, ## Test results
+#   merged     → same as submitted
+#   open       → no body requirements
+#   dropped    → no body requirements
+#
+# Usage:
+#   lint-candidate.sh                  # all candidates, table output
+#   lint-candidate.sh --status=submitted   # filter to one status
+#   lint-candidate.sh --missing-only       # only candidates with missing sections
+#   lint-candidate.sh --json               # JSON output (one object per candidate)
+#   lint-candidate.sh --candidates-dir=X   # override the candidate dir
+#
+# Exit codes:
+#   0  — no missing sections across the filtered set (clean)
+#   1  — at least one candidate has missing required sections
+#   64 — bad arguments
+
+set -uo pipefail
+
+CAND_DIR="${HOME}/.contribute-system/candidates"
+STATUS_FILTER=""
+MISSING_ONLY=0
+JSON_OUT=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --status=*)         STATUS_FILTER="${1#*=}" ;;
+    --missing-only)     MISSING_ONLY=1 ;;
+    --json)             JSON_OUT=1 ;;
+    --candidates-dir=*) CAND_DIR="${1#*=}" ;;
+    -h|--help)          /usr/bin/sed -n '2,28p' "$0" | /usr/bin/sed 's/^# \{0,1\}//'; exit 0 ;;
+    *)                  /usr/bin/echo "unknown arg: $1" >&2; exit 64 ;;
+  esac
+  shift
+done
+
+if [[ ! -d "$CAND_DIR" ]]; then
+  /usr/bin/echo "candidate dir not found: $CAND_DIR" >&2
+  exit 64
+fi
+
+# Required-sections per status. Pipe-delimited for compatibility with the
+# same scheme transition.sh uses.
+required_for() {
+  case "$1" in
+    shortlist) /usr/bin/echo '## Scope|## Files to touch' ;;
+    claimed)   /usr/bin/echo '## Scope|## Files to touch|## Claim comment draft' ;;
+    working)   /usr/bin/echo '## Scope|## Files to touch|## Claim comment draft' ;;
+    submitted) /usr/bin/echo '## PR title|## PR body|## Test results' ;;
+    merged)    /usr/bin/echo '## PR title|## PR body|## Test results' ;;
+    *)         /usr/bin/echo '' ;;  # open, dropped, unknown
+  esac
+}
+
+# Per-candidate evaluation. Echoes a JSON object per candidate so the table
+# pass and the JSON pass can both consume it.
+evaluate_one() {
+  local file="$1"
+  local basename
+  basename=$(/usr/bin/basename "$file")
+  local status
+  status=$(/usr/bin/awk '/^---$/{fm=!fm?1:2;next} fm==1 && /^status:/{sub(/^status:[[:space:]]*/,""); print; exit}' "$file" 2>/dev/null)
+  status="${status:-unknown}"
+
+  local req
+  req=$(required_for "$status")
+
+  local missing=()
+  if [[ -n "$req" ]]; then
+    IFS='|' read -ra SECTIONS <<< "$req"
+    for sec in "${SECTIONS[@]}"; do
+      if ! /usr/bin/grep -qE "^${sec}\b" "$file" 2>/dev/null; then
+        missing+=("$sec")
+      fi
+    done
+  fi
+
+  local missing_json
+  if [[ "${#missing[@]}" -eq 0 ]]; then
+    missing_json='[]'
+  else
+    missing_json=$(/usr/bin/printf '%s\n' "${missing[@]}" | jq -Rsc 'split("\n") | map(select(. != ""))')
+  fi
+
+  jq -nc --arg cand "$basename" --arg status "$status" --argjson missing "$missing_json" \
+    '{candidate: $cand, status: $status, missing: $missing, missing_count: ($missing | length)}'
+}
+
+# Walk all candidates, evaluate each, capture rows.
+ROWS=()
+EXIT_CODE=0
+shopt -s nullglob
+for f in "$CAND_DIR"/*.md; do
+  row=$(evaluate_one "$f")
+  STATUS=$(/usr/bin/echo "$row" | jq -r .status)
+  MISSING_COUNT=$(/usr/bin/echo "$row" | jq -r .missing_count)
+
+  # Apply --status filter
+  if [[ -n "$STATUS_FILTER" && "$STATUS" != "$STATUS_FILTER" ]]; then
+    continue
+  fi
+  # Apply --missing-only filter
+  if [[ "$MISSING_ONLY" -eq 1 && "$MISSING_COUNT" -eq 0 ]]; then
+    continue
+  fi
+
+  ROWS+=("$row")
+  if [[ "$MISSING_COUNT" -gt 0 ]]; then
+    EXIT_CODE=1
+  fi
+done
+shopt -u nullglob
+
+# Emit
+if [[ "$JSON_OUT" -eq 1 ]]; then
+  /usr/bin/printf '%s\n' "${ROWS[@]}" | jq -s '.'
+else
+  /usr/bin/printf '%-55s  %-10s  %s\n' 'candidate' 'status' 'missing'
+  /usr/bin/printf '%-55s  %-10s  %s\n' '---------' '------' '-------'
+  if [[ "${#ROWS[@]}" -eq 0 ]]; then
+    /usr/bin/printf '(no candidates matched filter)\n'
+  else
+    for row in "${ROWS[@]}"; do
+      cand=$(/usr/bin/echo "$row" | jq -r .candidate)
+      status=$(/usr/bin/echo "$row" | jq -r .status)
+      missing_str=$(/usr/bin/echo "$row" | jq -r '.missing | if length == 0 then "(none)" else join(", ") end')
+      /usr/bin/printf '%-55s  %-10s  %s\n' "$cand" "$status" "$missing_str"
+    done
+
+    # Summary footer
+    TOTAL=${#ROWS[@]}
+    DIRTY=$(/usr/bin/printf '%s\n' "${ROWS[@]}" | jq -s '[.[] | select(.missing_count > 0)] | length')
+    /usr/bin/printf '\n%d candidate(s) shown · %d with missing sections\n' "$TOTAL" "$DIRTY"
+  fi
+fi
+
+exit "$EXIT_CODE"