@intentsolutionsio/contributing-clanker 0.1.1

package/skills/contribute/references/candidate-file-format.md

@@ -0,0 +1,259 @@
+# Candidate file format
+
+Canonical specification for the markdown candidate files at
+`~/.contribute-system/candidates/<owner>__<repo>__issue<N>.md`.
+
+Each candidate file is the per-issue tracker. The frontmatter is the queryable
+layer; the body holds drafts and structured sections that gates read at
+transition time. **Manual edits in the body survive refresh** — only the
+frontmatter is auto-managed.
+
+---
+
+## Filename
+
+```
+~/.contribute-system/candidates/<owner>__<repo>__issue<N>.md
+```
+
+- `<owner>` and `<repo>` are joined by **double** underscore (`__`)
+- `<N>` is the upstream issue number (or PR number for backfilled candidates that have no linked issue)
+- One file per upstream issue; never multiple files for the same issue
+
+---
+
+## Frontmatter (YAML, between two `---` lines)
+
+The frontmatter is canonical state. Every gate reads from it. `transition.sh`
+writes to it atomically when state moves.
+
+| Field | Required | Type | Read by | Notes |
+|---|---|---|---|---|
+| `discovered_at` | yes | ISO8601 UTC | scout/researcher | when scout first wrote the candidate |
+| `repo` | yes | `<owner>/<repo>` | every gate | upstream repo |
+| `issue_number` | yes | int | A-phase gates | upstream issue # |
+| `issue_url` | yes | URL | (info) | direct link |
+| `star_tier` | yes | `niche` / `emerging` / `established` / `mainstream` | scout ranking | from `star_count` |
+| `star_count` | yes | int | scout ranking | |
+| `repo_lang` | yes | string | scout filter | primary language |
+| `competing_prs` | yes | int | A02 gate | scout-detected open PRs claiming this issue |
+| `primary_label` | yes | string | scout heuristic | upstream's primary label |
+| `scout_score` | yes | float (0–1) | scout ranking | momentum signal |
+| `status` | yes | enum (see below) | every gate + transition.sh | lifecycle state |
+| `last_refreshed` | yes | ISO8601 UTC | researcher | when scout/researcher last touched |
+| `merge_probability_pct` | optional | int (0–100) | scout ranking | empirical merge rate at this repo |
+| `research_path` | optional | absolute path | every gate that reads dossier | path to per-repo dossier; auto-resolved if empty |
+| `pr_number` | optional | int | reconciliation | set after PR opens |
+| `pr_url` | optional | URL | reconciliation | set after PR opens |
+| `branch` | optional | string | B/C-phase gates | local feature branch name |
+| `disabled_gates` | optional | array of gate IDs | gate-runner | per-candidate gate disables (escape hatch) |
+
+### `status` enum
+
+```
+open       → discovered, not yet vetted
+shortlist  → vetted, queued for next claim
+claimed    → posted claim comment, waiting for "go ahead" / no objection
+working    → actively coding (local clone exists, diff in progress)
+submitted  → PR or Design Issue opened upstream
+merged    → upstream merged the PR
+dropped    → closed without merge (failure log entry created in dossier)
+```
+
+`transition.sh` enforces the legal transitions and atomically updates the
+field on success.
+
+---
+
+## Body sections
+
+The body holds drafts + evidence. Sections are populated at different lifecycle
+stages by different agents. Manual edits survive refresh.
+
+### Section inventory
+
+Order, owner, and which gates read each section:
+
+| Section | Populated at | Owner | Read by gates |
+|---|---|---|---|
+| `# <repo>#<N> — <title>` | discovery | scout | (display only) |
+| `## Why scout flagged this` | discovery | scout | (info; helps reviewer) |
+| `## Scope` | qualification | user / @repo-analyzer | B07 (must enumerate planned scope) |
+| `## Files to touch` | qualification | user / @repo-analyzer | B07 (must list specific files) |
+| `## Claim comment draft` | claim | @draft-writer | A06 (etiquette comment must reference dossier excerpts) |
+| `## Issue body draft` | submit (Design Issue path) | @draft-writer | C03, C09 (issue body sections + issue link) |
+| `## PR title` | submit | @draft-writer | C02 (regex match against `pr_title_regex` in dossier) |
+| `## PR body` | submit | @draft-writer | C03, C05, C09, C19 (body sections + test evidence + issue link + claim-vs-diff) |
+| `## Test results` | working | @test-runner | C05 (concrete evidence required pre-submit) |
+| `## Review draft` | review (post-merge sometimes) | @draft-writer | D02, D03 (no-AI-reviews-without-disclosure) |
+| `## Safety override disclosure` | submit | user (only if --override-gate used) | F04 (mandatory if any gate was overridden) |
+
+### Required sections by lifecycle stage
+
+| Status | Sections that MUST exist | Sections that MAY exist |
+|---|---|---|
+| `open` | none beyond H1 | `## Why scout flagged this` |
+| `shortlist` | `## Scope`, `## Files to touch` | `## Claim comment draft` |
+| `claimed` | `## Claim comment draft` | `## Scope`, `## Files to touch` |
+| `working` | scope + files + claim draft | `## Test results` (early evidence) |
+| `submitted` | `## PR title`, `## PR body`, `## Test results` | `## Issue body draft` (if Design Issue path), `## Safety override disclosure` (if any overrides) |
+| `merged` | everything from `submitted` | none added |
+| `dropped` | everything that existed | (failure-log entry in dossier referenced here) |
+
+Backfilled candidates (created retroactively for already-open PRs) may
+legitimately skip the early-stage sections — their gates will SKIP rather
+than BLOCK, which is correct behavior.
+
+---
+
+## Worked example (a `submitted`-state candidate)
+
+```markdown
+---
+discovered_at: 2026-04-15T09:00:00Z
+repo: example-org/example-repo
+issue_number: 42
+issue_url: https://github.com/example-org/example-repo/issues/42
+star_tier: mainstream
+star_count: 15000
+repo_lang: TypeScript
+competing_prs: 0
+primary_label: bug
+scout_score: 0.82
+status: submitted
+pr_number: 137
+pr_url: https://github.com/example-org/example-repo/pull/137
+branch: fix/42-null-deref
+research_path: /home/jeremy/.contribute-system/research/example-org__example-repo.md
+last_refreshed: 2026-04-20T14:30:00Z
+---
+
+# example-org/example-repo #42 — null deref in formatter
+
+## Why scout flagged this
+
+Open >7d, primary_label=bug, momentum_score: 0.82 (3 maintainer comments
+in last week, no competing PRs).
+
+## Scope
+
+Replace the unchecked `.format()` call in `src/format.ts` with a guarded
+variant that returns `null` instead of throwing.
+
+## Files to touch
+
+- `src/format.ts` (1-2 lines)
+- `src/__tests__/format.test.ts` (add 2 cases for null + undefined)
+
+## Claim comment draft
+
+Hi! I'd like to take this. Plan: replace `.format()` with a guarded
+variant that returns `null` for nullish input, mirroring the pattern in
+`src/parse.ts`. ETA: end of week. Will open a Design Issue first per your
+CONTRIBUTING.md.
+
+## PR title
+
+fix: guard against null input in formatter (#42)
+
+## PR body
+
+## Problem
+
+`format()` throws on `null` / `undefined` input where callers expect a
+nullish-passthrough.
+
+## Proposed solution
+
+Add a guard at the top: if input is nullish, return `null`. Matches the
+pattern already used in `src/parse.ts`.
+
+## Test results
+
+Added 2 unit tests covering null + undefined input. Full suite green.
+
+Closes #42.
+
+## Test results
+
+```
+PASS  src/__tests__/format.test.ts (2 added)
+Tests: 78 passed, 78 total
+Duration: 1.2s
+```
+```
+
+---
+
+## How agents populate sections
+
+| Agent | Populates | When |
+|---|---|---|
+| `@scout` | `discovered_at`, frontmatter, `# <title>`, `## Why scout flagged this` | first discovery |
+| `@researcher` | `research_path` link only — body untouched | when building/refreshing the dossier |
+| `@repo-analyzer` | `## Scope`, `## Files to touch` | qualification |
+| `@draft-writer` | `## Claim comment draft`, `## PR title`, `## PR body`, `## Issue body draft`, `## Review draft` | claim / submit / review |
+| `@test-runner` | `## Test results` | working |
+| user | any section | any time — manual edits survive refresh |
+
+`transition.sh` updates frontmatter only (status, pr_number, last_refreshed).
+It never writes to the body.
+
+---
+
+## What backfilling looks like
+
+When a PR exists upstream but no candidate file ever tracked it, you can
+backfill one with frontmatter + minimal body. Most B/C-phase gates will
+SKIP rather than BLOCK because the body sections aren't present — that's
+correct behavior. Once the PR merges, the candidate becomes a `merged`
+record for the failure log / institutional memory.
+
+A backfill template:
+
+```markdown
+---
+discovered_at: <PR createdAt>
+repo: <owner>/<repo>
+issue_number: <linked issue # or PR #>
+issue_url: <PR url>
+star_tier: <derived from star_count>
+star_count: <gh repo view ... .stargazerCount>
+repo_lang: <gh repo view ... .primaryLanguage.name>
+competing_prs: 0
+primary_label: backfill
+scout_score: 0.7
+status: submitted
+pr_number: <PR #>
+pr_url: <PR url>
+branch: <gh pr view ... .headRefName>
+research_path: <absolute dossier path>
+backfilled_at: <now ISO8601>
+last_refreshed: <now ISO8601>
+---
+
+# <repo> #<PR#> — <title>
+
+## Why this candidate exists
+
+Backfilled into the lifecycle workflow on <date>. Pre-dates the candidate
+system being wired up; created so reconciliation can pick up state changes
+when the PR merges or closes.
+
+## Source
+
+- PR: <url>
+- Branch: `<branch>`
+- Linked issue: <issue # or "(none)">
+```
+
+---
+
+## Cross-references
+
+- Lifecycle workflow: `000-docs/006-AT-SPEC-lifecycle-workflow.md`
+- Gate inventory: `000-docs/005-AT-SPEC-gate-inventory.md`
+- `agents/draft-writer.md` — agent that populates `## PR body` etc.
+- `agents/test-runner.md` — agent that populates `## Test results`
+- `scripts/transition.sh` — updates frontmatter atomically
+- `scripts/gates/lib/preamble.sh` — gates' shared helpers for reading sections

package/skills/contribute/references/workflow-guide.md

@@ -0,0 +1,153 @@
+# Workflow Guide — long-form
+
+## Table of Contents
+
+1. [Daily rhythm](#daily-rhythm)
+2. [The 5-step workflow in depth](#the-5-step-workflow-in-depth)
+3. [Project-specific gotchas](#project-specific-gotchas)
+4. [Tracker hygiene](#tracker-hygiene)
+5. [Money & payment programs](#money--payment-programs)
+
+---
+
+## Daily rhythm
+
+The first thing the skill does on invoke is Step 0 (refresh state). After that, the natural conversation follows whatever the user is actually trying to do — review status, scout new work, qualify a candidate, draft a submission. The 5-step DISCOVER → QUALIFY → CLAIM → WORK → SUBMIT framing is the long form; most days touch only one or two steps.
+
+| Time of day | Typical action |
+|-------------|----------------|
+| Morning | Step 0 (state summary) → reconcile any drift |
+| Mid-morning | Step 1 (discover) if queue is thin |
+| Workblocks | Step 4 (work) on whatever's claimed |
+| End of day | Step 5 (draft submission) for tomorrow's review |
+
+## The 5-step workflow in depth
+
+### 1. DISCOVER — finding paid issues
+
+Three sources, in priority order:
+
+**Tracker (already-curated)** — `bounties` table rows where status is `open`, `qualified`, or `drafting`. These have already passed a competition / staleness check and represent the user's vetted queue.
+
+**Live GitHub label search** — anything labeled `bounty`, `💰 Bounty`, or repo-specific bounty labels in the tracked orgs. New every day; needs qualifying before it's actionable.
+
+**Algora boards** — browse-only via web. Their public API needs auth and the rate limits make it not worth scripting. The boards to know:
+
+| Org | Stack | Reward range |
+|-----|-------|--------------|
+| mediar-ai (screenpipe) | Rust + TS/Bun | $25–500 |
+| tscircuit | React/PCB | $25–150 |
+| golemcloud | Rust/WASM | up to $3.5K |
+| calcom | TS/Next.js | $20–500 |
+| twentyhq | TS | varies |
+| formbricks | TS | varies |
+| trigger-dev | TS | varies |
+
+**Gumroad** — single tracking issue at `antiwork/gumroad#1055`. Lists all active SCSS-to-Tailwind file conversions. $1.5K per file.
+
+### 2. QUALIFY — eligibility + competition + responsiveness
+
+Three things to check, fast:
+
+**Competition** — `gh pr list --repo <owner>/<repo> --search "<issue#>" --state=all`. If 2+ open PRs already, skip. If one open PR is stale (>14 days no activity), the issue may free up — note and revisit.
+
+**Maintainer responsiveness** — `gh api repos/<owner>/<repo>/commits` for recent activity dates. No commit in 60 days = likely abandoned. Avg PR merge lag from `gh pr list --state=closed --limit 10 --json mergedAt,createdAt` gives a sense of how long submissions sit.
+
+**Friction** — does the repo require a CLA? Does CONTRIBUTING.md ask for design docs / RFCs before code? Is there a PR template that asks for AI disclosure? All of these are fine, but they affect the time-to-merge math.
+
+### 3. CLAIM — staking the work
+
+Most upstreams accept a plain comment ("hey, I'd like to take this on, plan is X, ETA Y"). Algora-managed issues use Algora's `/bounty` slash command on the issue itself. Some programs (Cortex specifically) require an AI disclosure phrase in the first comment.
+
+After posting, update the tracker so Step 0 reflects the claim. Forgetting this is the #1 source of tracker drift.
+
+### 4. WORK — actually doing the thing
+
+Work happens in the upstream clone under `~/000-projects/contributing-clanker/<repo>/`. Each clone has its own `CLAUDE.md` with stack-specific commands and conventions.
+
+The two non-obvious rules:
+
+- **Don't push to forks until tests pass locally.** Pushing then force-pushing is noisy and wastes CI cycles.
+- **Match the upstream's tone.** screenpipe is lowercase; calcom is sentence case; PostHog is sentence case ("Product analytics" not "Product Analytics"). The maintainer notices.
+
+### 5. SUBMIT — design issue first, PR after approval
+
+The repo's `CLAUDE.md` says it explicitly: auto-opening PRs creates whack-a-mole slopfests. Open a Design Issue with diff preview + test results, wait for the maintainer to approve the approach, *then* open a PR.
+
+The exception: if the upstream's CONTRIBUTING.md explicitly asks for direct PRs (some repos prefer this for small fixes), follow their convention.
+
+## Project-specific gotchas
+
+### screenpipe
+
+- Two test suites: `cargo test` for the Rust core, `bun test` for the Tauri app. Both must pass.
+- Lowercase logging and UI text — match the existing codebase tone.
+- No toast errors — use empty states / skeletons / inline errors instead.
+- `@ts-ignore` comments are intentional; don't remove them.
+- Escape HTML properly in JSX (`&apos;` etc. inside string attributes).
+
+### cortex
+
+- CLA required before first PR — sign at the link in `cortex/CLA.md`.
+- Demo video required (before/after for bugs, feature demo for new work).
+- AI disclosure phrase required in the PR body.
+- Tests with >80% coverage (their bar, not optional).
+- No force-push — merge commits only.
+
+### posthog
+
+- ALWAYS wrap commands in `flox activate -- bash -c "..."`. Running pytest directly will fail.
+- Type hints required in Python.
+- No mypy (they ditched it for being too slow).
+- Tailwind preferred over inline styles.
+- Avoid direct `dayjs` imports — use `lib/dayjs`.
+- Conventional commits: `feat(scope):`, `fix(scope):`, lowercase, no period.
+
+### calcom / cal-com
+
+- Two clones in the workspace. Prefer `calcom/` (newer).
+- yarn workspaces — run from the monorepo root, not subpackage.
+
+### vertex-ai-samples (Google)
+
+- CLA required at https://cla.developers.google.com/
+- One notebook per PR.
+- Lint via Docker: `docker run -v ${PWD}:/setup/app gcr.io/cloud-devrel-public-resources/notebook_linter:latest <notebook>.ipynb`
+
+### zio-blocks
+
+- Scala 3, pure FP, sbt.
+- `sbt scalafmtCheckAll` is part of the gate.
+- Schema migrations have $2-4K rewards — biggest individual paydays in the workspace.
+
+### feishin
+
+- Electron + React + pnpm.
+- ESLint + Stylelint both run.
+
+### gumroad
+
+- $1,500 per SCSS file converted to Tailwind.
+- Email `bounties@antiwork.com` with PR link + payment email after merge.
+- Stripe payout (bank, PayPal, crypto).
+- Issue `#1055` is the index of available files.
+
+## Tracker hygiene
+
+The tracker only stays useful if its status reflects reality. Two operations keep it honest:
+
+**Reconcile** — for every row with a `pr_number`, check the live PR state via `gh pr view`. Update the row's `status` to `completed` (merged), `cancelled` (closed-not-merged), or `submitted` (open). Do this at least weekly, or after any "mass push" day.
+
+**Re-import from CSV** — the canonical CSV at `~/000-projects/contributing-clanker/000-docs/002-PM-BKLG-contribution-tracker.csv` is the human-edited backlog. If the CSV gets new rows (manual additions), re-run the importer to land them in SQLite. Idempotent — existing IDs are skipped.
+
+## Money & payment programs
+
+| Program | Payment mechanism | Speed |
+|---------|------------------|-------|
+| Algora | Platform handles automatically (120+ countries) | Days |
+| Gumroad | Email `bounties@antiwork.com` post-merge, Stripe payout | ~1 week |
+| Cortex | Bitcoin (preferred), USDC, or PayPal | <48 hours |
+| Tscircuit / Golem / others on Algora | Same as Algora | Days |
+| Ad-hoc GitHub bounty (no platform) | Negotiated case-by-case | Variable |
+
+The local `001-BL-TRCK-payment-tracker.md` doc tracks paid vs pending across all programs. After a payment lands, update both that doc AND the `bounties.payment_status` column.

package/skills/contribute/scripts/audit-overrides.sh

@@ -0,0 +1,180 @@
+#!/usr/bin/env bash
+# audit-overrides.sh — report override frequency and reasons across gates.
+#
+# Closes beads contributing-clanker-15b.3 and contributing-clanker-i4y.1
+# (both ask for the same reporter: every --override-gate logged with reason +
+# override frequency by gate).
+#
+# Reads ~/.contribute-system/log.jsonl. Aggregates two event types:
+#   - gate_override  → an engineer pressed --override-gate=<ID> "reason"
+#   - gate_run       → every gate verdict (BLOCK / PASS / WARN / etc.)
+#
+# Output: per-gate row with [overrides, blocks, override_rate, top_reason].
+# Sorted by override_rate desc — the most-overridden gates surface first.
+# A high override_rate means the gate is either too strict (false-positive
+# heavy) or genuinely catching real risk that engineers consciously accept.
+# Either way, it's the signal worth surfacing.
+#
+# Usage:
+#   audit-overrides.sh                           # all-time, all repos
+#   audit-overrides.sh --since=30                # last 30 days only
+#   audit-overrides.sh --scope=org:posthog       # only posthog/* repos
+#   audit-overrides.sh --scope=repo:foo/bar      # exact repo
+#   audit-overrides.sh --json                    # JSON output (no table)
+#   audit-overrides.sh --gate=A05                # drill into one gate
+
+set -uo pipefail
+
+LOG="${HOME}/.contribute-system/log.jsonl"
+SINCE_DAYS=""
+SCOPE=""
+GATE_FILTER=""
+JSON_OUT=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --since=*)     SINCE_DAYS="${1#*=}" ;;
+    --scope=*)     SCOPE="${1#*=}" ;;
+    --gate=*)      GATE_FILTER="${1#*=}" ;;
+    --json)        JSON_OUT=1 ;;
+    -h|--help)
+      sed -n '2,30p' "$0"
+      exit 0
+      ;;
+    *)
+      /usr/bin/printf 'unknown arg: %s\n' "$1" >&2
+      exit 2
+      ;;
+  esac
+  shift
+done
+
+if [[ ! -f "$LOG" ]]; then
+  /usr/bin/printf 'no log file at %s — run a transition first\n' "$LOG" >&2
+  exit 0
+fi
+
+# Build a jq filter that applies --since + --scope + --gate filters before
+# aggregation. The repo field is on .details.repo for gate_run, and on
+# .details.candidate (a path) for gate_override — gate_override events don't
+# carry a repo string directly, so for gate_override we extract from the path
+# pattern <owner>__<repo>__issue<N>.md when present, falling back to "" when
+# not parseable. That's why scope filtering for overrides is best-effort.
+
+since_filter='true'
+if [[ -n "$SINCE_DAYS" ]]; then
+  cutoff=$(/usr/bin/date -u -d "$SINCE_DAYS days ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null \
+    || /usr/bin/date -u -v-"${SINCE_DAYS}"d +%Y-%m-%dT%H:%M:%SZ)
+  since_filter=".ts >= \"$cutoff\""
+fi
+
+case "$SCOPE" in
+  org:*)
+    owner="${SCOPE#org:}"
+    scope_run='(.details.repo // "") | startswith("'"$owner"'/")'
+    scope_ovr='(.details.candidate // "") | test("/'"$owner"'__")'
+    ;;
+  repo:*)
+    repo="${SCOPE#repo:}"
+    scope_run='(.details.repo // "") == "'"$repo"'"'
+    owner_repo_path=$(/usr/bin/printf '%s' "$repo" | /usr/bin/sed 's|/|__|')
+    scope_ovr='(.details.candidate // "") | test("/'"$owner_repo_path"'__")'
+    ;;
+  "")
+    scope_run='true'
+    scope_ovr='true'
+    ;;
+  *)
+    /usr/bin/printf 'invalid --scope (use org:OWNER or repo:OWNER/NAME)\n' >&2
+    exit 2
+    ;;
+esac
+
+gate_filter_run='true'
+gate_filter_ovr='true'
+if [[ -n "$GATE_FILTER" ]]; then
+  # Gate IDs in gate_run are lowercase ("a05"); in gate_override they're as
+  # passed by the engineer (often uppercase "A05"). Match case-insensitively.
+  gate_filter_run='(.details.gate // "" | ascii_downcase) == "'"$(/usr/bin/printf '%s' "$GATE_FILTER" | /usr/bin/tr '[:upper:]' '[:lower:]')"'"'
+  gate_filter_ovr='(.details.gate // "" | ascii_downcase) == "'"$(/usr/bin/printf '%s' "$GATE_FILTER" | /usr/bin/tr '[:upper:]' '[:lower:]')"'"'
+fi
+
+# Phase 1: aggregate override counts + reasons per gate
+overrides_json=$(jq -cs --slurpfile _ <(/usr/bin/printf '[]') '
+  map(select(.event == "gate_override" and ('"$since_filter"') and ('"$scope_ovr"') and ('"$gate_filter_ovr"')))
+  | group_by(.details.gate // "" | ascii_downcase)
+  | map({
+      gate: (.[0].details.gate // "" | ascii_downcase),
+      overrides: length,
+      reasons: (map(.details.reason // "") | unique)
+    })
+' "$LOG" 2>/dev/null || /usr/bin/printf '[]')
+
+# Phase 2: aggregate BLOCK count per gate (denominator for override rate)
+blocks_json=$(jq -cs '
+  map(select(.event == "gate_run" and (.details.severity // "") == "BLOCK"
+             and ('"$since_filter"') and ('"$scope_run"') and ('"$gate_filter_run"')))
+  | group_by(.details.gate // "" | ascii_downcase)
+  | map({
+      gate: (.[0].details.gate // "" | ascii_downcase),
+      blocks: length
+    })
+' "$LOG" 2>/dev/null || /usr/bin/printf '[]')
+
+# Phase 3: merge and compute rate
+merged=$(jq -cn --argjson o "$overrides_json" --argjson b "$blocks_json" '
+  ($o + $b)
+  | group_by(.gate)
+  | map({
+      gate: .[0].gate,
+      overrides: ((map(.overrides // 0) | add) // 0),
+      blocks: ((map(.blocks // 0) | add) // 0),
+      reasons: ((map(.reasons // [])  | add | unique) // [])
+    })
+  | map(. + {
+      override_rate: (if .blocks > 0 then (.overrides / .blocks * 100 | floor) else null end),
+      top_reason: (.reasons | first // "")
+    })
+  | sort_by(if .override_rate == null then -1 else -.override_rate end)
+')
+
+if [[ "$JSON_OUT" -eq 1 ]]; then
+  /usr/bin/printf '%s\n' "$merged" | jq .
+  exit 0
+fi
+
+# Render text table
+header_parts=()
+[[ -n "$SINCE_DAYS" ]] && header_parts+=("last ${SINCE_DAYS}d")
+[[ -n "$SCOPE" ]] && header_parts+=("scope=${SCOPE}")
+[[ -n "$GATE_FILTER" ]] && header_parts+=("gate=${GATE_FILTER}")
+[[ ${#header_parts[@]} -eq 0 ]] && header_parts+=("all-time")
+header=$(/usr/bin/printf '%s, ' "${header_parts[@]}" | /usr/bin/sed 's/, $//')
+/usr/bin/printf '\nOverride audit — %s\n' "$header"
+/usr/bin/printf '%s\n' '─────────────────────────────────────────────────────────────────────────'
+/usr/bin/printf '%-6s %10s %8s %10s  %s\n' "GATE" "OVERRIDES" "BLOCKS" "RATE" "TOP REASON"
+/usr/bin/printf '%s\n' '─────────────────────────────────────────────────────────────────────────'
+
+count=$(/usr/bin/printf '%s' "$merged" | jq 'length')
+if [[ "$count" -eq 0 ]]; then
+  /usr/bin/printf '  (no override events match the filter)\n\n'
+  exit 0
+fi
+
+/usr/bin/printf '%s\n' "$merged" | jq -r '
+  .[] | [
+    .gate,
+    .overrides,
+    .blocks,
+    (if .override_rate == null then "n/a" else "\(.override_rate)%" end),
+    (if (.top_reason | length) > 50 then (.top_reason[0:47] + "...") else .top_reason end)
+  ] | @tsv
+' | /usr/bin/awk -F'\t' '{ printf "%-6s %10s %8s %10s  %s\n", $1, $2, $3, $4, $5 }'
+
+/usr/bin/printf '%s\n\n' '─────────────────────────────────────────────────────────────────────────'
+
+# Surface insight
+high_rate=$(/usr/bin/printf '%s' "$merged" | jq -r '[.[] | select(.override_rate != null and .override_rate >= 50)] | length')
+if [[ "$high_rate" -gt 0 ]]; then
+  /usr/bin/printf '  ⚠ %d gate(s) overridden ≥50%% of the time — investigate false positives.\n\n' "$high_rate"
+fi