feat(reusable): runtime-variable swarm config (cache-immune, no more re-pinning to retune) (#14)

.gitea/workflows/adversarial-review.yml

@@ -1,10 +1,11 @@
-# Gadfly reviewing its OWN PRs — now a thin CALLER of the reusable workflow
-# (.gitea/workflows/review-reusable.yml), dogfooding the Phase-4 "subscribe"
-# path. The reusable holds the image pin + env plumbing; this file holds only
-# the triggers, the actor gate, and gadfly's specific swarm config.
+# Gadfly reviewing its OWN PRs — a thin CALLER of the reusable workflow
+# (.gitea/workflows/review-reusable.yml), dogfooding the "subscribe" path. The
+# reusable holds the image pin, env plumbing, AND the default swarm; this file
+# holds only the triggers, the actor gate, secret forwarding, and allow-list.
 #
-# Advisory only — never blocks a merge. Fleet: 6 cloud + Claude Code
-# (sonnet, opus, opus:max) competitors.
+# Advisory only — never blocks a merge. It inherits the default swarm: 3 cloud
+# models + Claude Code (sonnet, opus, opus:max), 5-lens suite (claude models run
+# one at a time, each with all 5 lenses at once).
 
 name: Adversarial Review (Gadfly)
 
@@ -48,11 +49,7 @@ jobs:
       GADFLY_FINDINGS_URL:     ${{ secrets.GADFLY_FINDINGS_URL }}
       GADFLY_FINDINGS_TOKEN:   ${{ secrets.GADFLY_FINDINGS_TOKEN }}
     with:
-      models: "minimax-m3:cloud,glm-5.2:cloud,glm-5.1:cloud,deepseek-v4-pro:cloud,nemotron-3-super:cloud,qwen3-coder:480b-cloud,claude-code/sonnet,claude-code/opus,claude-code/opus:max"
-      specialists: "security,correctness,error-handling"
-      provider_concurrency: "ollama-cloud=3,claude-code=2"
-      provider_lens_concurrency: "ollama-cloud=3"
-      timeout_secs: "600"
-      max_steps: "14"
+      # Inherit the default swarm (3 cloud + Claude Code sonnet/opus/opus:max,
+      # 5-lens suite) from review-reusable.yml. Only the consumer-specific
+      # allow-list is set here.
       allowed_users: "steve,fizi,dazed"
-      timeout_minutes: 90

.gitea/workflows/review-reusable.yml

@@ -6,15 +6,18 @@
 #   jobs:
 #     review:
 #       if: ...                      # actor gate for the comment trigger
-#       uses: steve/gadfly/.gitea/workflows/review-reusable.yml@<sha>
+#       uses: steve/gadfly/.gitea/workflows/review-reusable.yml@v1
 #       secrets:                     # forward ONLY what the reviewer needs
 #         OLLAMA_CLOUD_API_KEY:    ${{ secrets.OLLAMA_CLOUD_API_KEY }}
 #         CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-#       with: { models: "...", allowed_users: "..." }   # all optional
+#       with: { allowed_users: "..." }   # config inputs are optional (see below)
 #
-# Inputs are all optional and default to "" — an empty env value makes the
-# image/entrypoint use its own built-in default, so the caller only sets what it
-# wants to override. Secrets are DECLARED below (workflow_call.secrets) so a
+# The swarm config (models, specialists, concurrency) is resolved at RUNTIME from,
+# in order: a consumer's `with:` input → the owner's user-scope GADFLY_DEFAULT_*
+# variable → the image's built-in default. Because variables are injected per-run
+# (not part of this cached file), the owner retunes the whole fleet by editing ONE
+# variable — see the inputs block and README "Central config via variables".
+# Secrets are DECLARED below (workflow_call.secrets) so a
 # caller forwards only the credentials the reviewer actually uses — least
 # privilege — rather than `secrets: inherit`, which leaks every caller secret
 # (registry/deploy/db creds) into this workflow. `secrets: inherit` still works
@@ -23,35 +26,50 @@
 #
 # Advisory only — never blocks a merge. The image is pinned to an immutable
 # :sha- tag here (act_runner caches :latest); bump it per Gadfly release.
-# Consumers should likewise pin `uses: ...@<sha>` (not @main) so a push to this
-# repo can't silently change the code that runs with their forwarded secrets.
+# Consumers should pin `uses: ...@v1` — a curated release tag moved on deliberate
+# releases, so central tuning here propagates without per-consumer edits — or a
+# full `@<sha>` for an immutable pin. Avoid `@main` (moves on every push).
 
 name: Gadfly review (reusable)
 
 on:
   workflow_call:
+    # The swarm config (models, specialists, concurrency) is resolved at RUNTIME,
+    # in priority order: a consumer's explicit `with:` input → the owner's
+    # user/org-level variable (GADFLY_DEFAULT_*) → the image's built-in default.
+    # Variables are injected per-run by Gitea (not baked into this file), so the
+    # owner can retune the whole fleet by editing ONE variable — it propagates even
+    # though long-lived act_runners CACHE this workflow file by ref (a moved tag is
+    # NOT re-fetched; only a runtime value or a fresh @<sha> bypasses the cache).
+    #
+    # Owner-set user-scope variables (see README "Central config via variables"):
+    #   GADFLY_DEFAULT_MODELS, GADFLY_DEFAULT_SPECIALISTS,
+    #   GADFLY_DEFAULT_PROVIDER_CONCURRENCY, GADFLY_DEFAULT_PROVIDER_LENS_CONCURRENCY,
+    #   GADFLY_ENDPOINT_RAGNAROS (the 4090 Ti endpoint).
+    # An unset variable + no input → the image default (one model, default suite),
+    # so a public consumer with neither still gets a sane minimal review.
     inputs:
-      models:                    { type: string, default: "" }   # GADFLY_MODELS (csv)
-      specialists:               { type: string, default: "" }   # GADFLY_SPECIALISTS
+      models:                    { type: string, default: "" }   # GADFLY_MODELS — empty falls back to user var GADFLY_DEFAULT_MODELS, then the image default
+      specialists:               { type: string, default: "" }   # GADFLY_SPECIALISTS — empty falls back to user var GADFLY_DEFAULT_SPECIALISTS
       provider:                  { type: string, default: "" }   # GADFLY_PROVIDER
       base_url:                  { type: string, default: "" }   # GADFLY_BASE_URL
-      provider_concurrency:      { type: string, default: "" }   # GADFLY_PROVIDER_CONCURRENCY
-      provider_lens_concurrency: { type: string, default: "" }   # GADFLY_PROVIDER_LENS_CONCURRENCY
-      timeout_secs:              { type: string, default: "" }   # GADFLY_TIMEOUT_SECS (per lens)
-      max_steps:                 { type: string, default: "" }   # GADFLY_MAX_STEPS
+      provider_concurrency:      { type: string, default: "" }   # GADFLY_PROVIDER_CONCURRENCY — empty falls back to user var GADFLY_DEFAULT_PROVIDER_CONCURRENCY
+      provider_lens_concurrency: { type: string, default: "" }   # GADFLY_PROVIDER_LENS_CONCURRENCY — empty falls back to user var GADFLY_DEFAULT_PROVIDER_LENS_CONCURRENCY
+      timeout_secs:              { type: string, default: "600" }   # GADFLY_TIMEOUT_SECS (per lens)
+      max_steps:                 { type: string, default: "14" }   # GADFLY_MAX_STEPS
       worker_model:              { type: string, default: "" }   # GADFLY_WORKER_MODEL
-      allowed_users:             { type: string, default: "" }   # GADFLY_ALLOWED_USERS
+      allowed_users:             { type: string, default: "" }   # GADFLY_ALLOWED_USERS (consumer-specific; set in your stub)
       trigger_phrase:            { type: string, default: "" }   # GADFLY_TRIGGER_PHRASE
-      # Job wall-clock cap. 45 > 30 as a default: a multi-model swarm or a slow
-      # lens (e.g. claude-code with extended thinking) can exceed 30 minutes.
-      timeout_minutes:           { type: number, default: 45 }
+      # Job wall-clock cap. 90 as a default: the 5-lens suite across a slow lane
+      # (claude-code with extended thinking) over two passes can run long.
+      timeout_minutes:           { type: number, default: 90 }
     # Declared so callers can forward ONLY the secrets the reviewer needs
     # (least privilege) instead of `secrets: inherit`, which would hand this
     # workflow every secret in the caller's repo (registry/deploy/db creds the
     # review never touches). All optional — an unset/unpassed secret resolves to
     # empty, harmless for the providers a given consumer doesn't use. GITEA_TOKEN
-    # is the automatic job token and need not be declared/forwarded. Consumers
-    # with bespoke GADFLY_ENDPOINT_<NAME>s beyond M1/M5 need the full stub.
+    # is the automatic job token and need not be declared/forwarded. Named
+    # endpoints (GADFLY_ENDPOINT_*) come from user/org VARS now, not secrets.
     secrets:
       OLLAMA_CLOUD_API_KEY:    { required: false }
       OPENAI_API_KEY:          { required: false }
@@ -59,8 +77,6 @@ on:
       GOOGLE_API_KEY:          { required: false }
       GADFLY_API_KEY:          { required: false }
       CLAUDE_CODE_OAUTH_TOKEN: { required: false }
-      GADFLY_ENDPOINT_M1:      { required: false }
-      GADFLY_ENDPOINT_M5:      { required: false }
       GADFLY_FINDINGS_URL:     { required: false }
       GADFLY_FINDINGS_TOKEN:   { required: false }
 
@@ -99,21 +115,29 @@ jobs:
           GOOGLE_API_KEY: ${{ secrets.GOOGLE_API_KEY }}
           GADFLY_API_KEY: ${{ secrets.GADFLY_API_KEY }}
           CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          # Common named foreman/LAN endpoints (optional). Consumers with other
-          # GADFLY_ENDPOINT_<NAME>s need the full stub (examples/), since a
-          # reusable workflow can't enumerate arbitrary names.
-          GADFLY_ENDPOINT_M1: ${{ secrets.GADFLY_ENDPOINT_M1 }}
-          GADFLY_ENDPOINT_M5: ${{ secrets.GADFLY_ENDPOINT_M5 }}
+          # Named LAN endpoints, defined in user/org vars (format
+          # "<provider>|<base-url>[|<key>]"). Adding a NEW name still needs a line
+          # here — a reusable workflow can't enumerate arbitrary vars.GADFLY_ENDPOINT_*.
+          # NB: vars are NOT masked like secrets — if an endpoint embeds an auth
+          # token, keep that one a secret instead.
+          GADFLY_ENDPOINT_M1: ${{ vars.GADFLY_ENDPOINT_M1 }}
+          GADFLY_ENDPOINT_M5: ${{ vars.GADFLY_ENDPOINT_M5 }}
+          # ragnaros = the 4090 Ti via its llama-swap proxy. Defined in the user
+          # var GADFLY_ENDPOINT_RAGNAROS (format "<provider>|<base-url>[|<key>]")
+          # so the URL can change without editing this file; the matching model is
+          # ragnaros/qwen3.6-27b in GADFLY_DEFAULT_MODELS. NB: use the un-hyphenated
+          # `llamaswap` provider spelling in the var — the pinned image needs it.
+          GADFLY_ENDPOINT_RAGNAROS: ${{ vars.GADFLY_ENDPOINT_RAGNAROS }}
           # --- findings telemetry (optional) --------------------------------
           GADFLY_FINDINGS_URL: ${{ secrets.GADFLY_FINDINGS_URL }}
           GADFLY_FINDINGS_TOKEN: ${{ secrets.GADFLY_FINDINGS_TOKEN }}
           # --- config (from inputs; empty => image default) -----------------
-          GADFLY_MODELS: ${{ inputs.models }}
-          GADFLY_SPECIALISTS: ${{ inputs.specialists }}
+          GADFLY_MODELS: ${{ inputs.models || vars.GADFLY_DEFAULT_MODELS }}
+          GADFLY_SPECIALISTS: ${{ inputs.specialists || vars.GADFLY_DEFAULT_SPECIALISTS }}
           GADFLY_PROVIDER: ${{ inputs.provider }}
           GADFLY_BASE_URL: ${{ inputs.base_url }}
-          GADFLY_PROVIDER_CONCURRENCY: ${{ inputs.provider_concurrency }}
-          GADFLY_PROVIDER_LENS_CONCURRENCY: ${{ inputs.provider_lens_concurrency }}
+          GADFLY_PROVIDER_CONCURRENCY: ${{ inputs.provider_concurrency || vars.GADFLY_DEFAULT_PROVIDER_CONCURRENCY }}
+          GADFLY_PROVIDER_LENS_CONCURRENCY: ${{ inputs.provider_lens_concurrency || vars.GADFLY_DEFAULT_PROVIDER_LENS_CONCURRENCY }}
           GADFLY_TIMEOUT_SECS: ${{ inputs.timeout_secs }}
           GADFLY_MAX_STEPS: ${{ inputs.max_steps }}
           GADFLY_WORKER_MODEL: ${{ inputs.worker_model }}

CLAUDE.md

@@ -46,9 +46,15 @@ entrypoint.sh          container brains: trigger gating, PR clone, model loop (t
                        used to live in workflow YAML)
 Dockerfile             multi-stage; private-module creds via BuildKit secrets never reach the final image
 .gitea/workflows/build-image.yml   push main → :latest; tag v* → :<tag>+:latest; PR → build-only
-.gitea/workflows/review-reusable.yml  reusable (workflow_call) review job; consumers subscribe with
-                       an ~8-line caller forwarding only the secrets the reviewer needs (Phase 4). gadfly's own
-                       adversarial-review.yml is a thin caller of it (dogfoods the path).
+.gitea/workflows/review-reusable.yml  reusable (workflow_call) review job; resolves swarm config at
+                       RUNTIME: consumer `with:` input → owner user-scope var (GADFLY_DEFAULT_MODELS /
+                       _SPECIALISTS / _PROVIDER_CONCURRENCY / _PROVIDER_LENS_CONCURRENCY, +
+                       GADFLY_ENDPOINT_RAGNAROS) → image default. Vars are injected per-run, so editing
+                       one var retunes the whole fleet even though long-lived act_runners CACHE this file
+                       by ref (a moved tag is NOT re-fetched — only a runtime value or a fresh @<sha>
+                       bypasses the cache). Consumers subscribe with an ~8-line caller forwarding only the
+                       secrets the reviewer needs and pinned to an immutable @<sha> (Phase 4);
+                       gadfly's own adversarial-review.yml is a thin caller of it (dogfoods the path).
 examples/              copy-paste consumer stub workflows for different providers
 ```
 
@@ -98,7 +104,10 @@ comment with a section each. Default suite = security/correctness/maintainabilit
 error-handling; opt-in built-ins = tests/docs/conventions/improvements. Select via
 `GADFLY_SPECIALISTS` (csv or `all`); define/override via `GADFLY_SPECIALIST_<NAME>` env or a repo
 `.gadfly.yml` (`specialists:` + `define:`). See `cmd/gadfly/specialists.go`. Cost ≈
-specialists × models × 2 passes — keep the default model count low (entrypoint defaults to one).
+specialists × models × 2 passes — the **image/entrypoint** default stays minimal (one model) for
+that reason; the **reusable workflow** (`review-reusable.yml`) deliberately ships a heavier
+opinionated default swarm (3 cloud + Claude Code, 5 lenses) for steve's own fleet, which consumers
+inherit or override per-input.
 **Dynamic `auto`** (`GADFLY_SPECIALISTS=auto`): a selector (`GADFLY_SELECTOR_MODEL` or the review
 model) picks lenses per-diff and may invent ad-hoc ones (`cmd/gadfly/auto.go`). **Worker-tier**
 (`GADFLY_WORKER_MODEL`): a `delegate_investigation` tool offloads grep/read legwork to a cheap

README.md

@@ -39,7 +39,8 @@ it. Drop one file in your repo and set a couple of secrets/vars:
 1. Copy a stub from [`examples/`](examples/) to `.gitea/workflows/adversarial-review.yml` in
    your repo. Two flavors: the slim [`reusable.yml`](examples/reusable.yml) — a tiny caller of
    Gadfly's **reusable workflow** (`uses: steve/gadfly/.gitea/workflows/review-reusable.yml@…`,
-   forwarding only the secrets the reviewer needs), best when you take the defaults — or the full self-contained
+   forwarding only the secrets the reviewer needs), whose **default swarm is set centrally via owner
+   variables** (see [Central config via variables](#central-config-via-variables)) and inherited by omitting `with:` — or the full self-contained
    [`adversarial-review.yml`](examples/adversarial-review.yml) (Ollama Cloud default, with inline
    notes for every provider / local Ollama / OpenAI-compatible / endpoint aliases). See the
    [examples index](examples/README.md).
@@ -311,8 +312,29 @@ examples/              the ~15-line stub a consuming repo drops in
 
 The image is published to `gitea.stevedudenhoeffer.com/steve/gadfly`. Every push to `main`
 rebuilds and republishes `:latest` (plus `:sha-<short>`); pushing a `v*` tag publishes that
-pinned version (plus `:latest`). Pin consumers to a `:vN` tag for stability, or track
-`:latest` to ride main.
+pinned version (plus `:latest`). Pin full-stub consumers to a `:vN` image tag for stability, or track
+`:latest` to ride main. **Reusable-workflow consumers should pin the workflow ref to an immutable
+`review-reusable.yml@<sha>`** — long-lived act_runners *cache the workflow file by ref*, so a moved tag
+(`@v1`) or `@main` is often **not** re-fetched and silently runs a stale copy. A fresh `@<sha>` is the
+only reliable way to roll out a *structural* change to the reusable.
+
+### Central config via variables
+
+So you don't have to re-pin every consumer just to retune the swarm, the reusable resolves its config
+at **runtime** — `with:` input → owner **user/org-level variable** → image default — and variables are
+injected per-run (not part of the cached file), so changing one variable propagates to every consumer
+on its next review **without** a re-pin or a tag move:
+
+| Variable (user/org scope) | Sets |
+|---|---|
+| `GADFLY_DEFAULT_MODELS` | `GADFLY_MODELS` (csv) |
+| `GADFLY_DEFAULT_SPECIALISTS` | the lens suite |
+| `GADFLY_DEFAULT_PROVIDER_CONCURRENCY` | models-at-once per provider |
+| `GADFLY_DEFAULT_PROVIDER_LENS_CONCURRENCY` | lenses-at-once per provider |
+| `GADFLY_ENDPOINT_RAGNAROS` | a named endpoint, e.g. `llamaswap\|https://host` |
+
+Adding a *new* named endpoint still needs a one-line reusable edit (Gitea can't auto-expose arbitrary
+`vars.GADFLY_ENDPOINT_*`); the values of already-wired ones are pure variables.
 
 ## Configuration (advanced)
 

examples/README.md

@@ -6,7 +6,7 @@ set the secrets/vars it references. Gadfly is advisory only — it never blocks
 
 | File | Backend | Needs |
 |------|---------|-------|
-| [`reusable.yml`](reusable.yml) | **slimmest stub** — calls Gadfly's reusable workflow, forwarding only the secrets the reviewer needs (least privilege, not `secrets: inherit`); take the defaults or override a few inputs | secret `OLLAMA_CLOUD_API_KEY` |
+| [`reusable.yml`](reusable.yml) | **slimmest stub** — calls Gadfly's reusable workflow and inherits its **default swarm** (3 cloud + Claude Code, 5-lens suite), forwarding only the secrets it needs (least privilege, not `secrets: inherit`); the stub keeps a cloud-only `models:` override so it runs with just the Ollama key (drop it + add the Claude token to get the full default) | secret `OLLAMA_CLOUD_API_KEY` |
 | [`adversarial-review.yml`](adversarial-review.yml) | **Ollama Cloud** (default) + inline notes for every provider; full self-contained stub | secret `OLLAMA_CLOUD_API_KEY` |
 | [`local-ollama.yml`](local-ollama.yml) | a **local/LAN Ollama** daemon | nothing (or `GADFLY_BASE_URL` for a remote host) |
 | [`openai-compatible.yml`](openai-compatible.yml) | any **OpenAI-compatible** endpoint (local Ollama `/v1`, gateway, vLLM, OpenRouter…) | `GADFLY_BASE_URL` (+ a key for most gateways) |

examples/reusable.yml

@@ -5,17 +5,22 @@
 # workflow, which holds the image pin + all the env plumbing. You only declare
 # the triggers, the comment-trigger actor gate, and any overrides you want.
 #
-# Needs: secret OLLAMA_CLOUD_API_KEY (the default Ollama Cloud provider).
+# The reusable ships a DEFAULT swarm: 3 cloud models + the Claude Code engine
+# (sonnet/opus/opus:max), 5-lens suite. That default needs BOTH
+# OLLAMA_CLOUD_API_KEY and CLAUDE_CODE_OAUTH_TOKEN. This example overrides
+# `models:` to a cloud-only set so it works with just OLLAMA_CLOUD_API_KEY —
+# delete that override (and forward the Claude token) to inherit the full default.
+#
 # Forward ONLY the secrets the reviewer uses (least privilege) — see the
 # `secrets:` block below. GITEA_TOKEN is automatic. `secrets: inherit` also works
 # but hands the reusable EVERY secret in your repo (registry/deploy/db creds the
-# review never touches), so prefer the explicit form. Pin @<sha> to an immutable
-# Gadfly commit (not @main) so a push there can't change what runs with your
-# secrets.
+# review never touches), so prefer the explicit form. Pin @<ref>: use the @v1
+# release tag (a curated pointer moved on deliberate releases) for auto-updating
+# stability, or a full @<sha> for an immutable pin. Avoid @main — it moves on
+# every push and would change what runs with your forwarded secrets.
 #
-# Prefer this when you're happy with the defaults. For custom named endpoints
-# (GADFLY_ENDPOINT_<NAME>) or a provider the reusable doesn't map, use the full
-# stub in adversarial-review.yml instead.
+# For custom named endpoints (GADFLY_ENDPOINT_<NAME>) or a provider the reusable
+# doesn't map, use the full stub in adversarial-review.yml instead.
 
 name: Adversarial Review (Gadfly)
 
@@ -44,9 +49,9 @@ jobs:
     if: >-
       github.event_name != 'issue_comment'
       || (github.event.issue.pull_request && github.actor == 'your-username')
-    # Pin @<sha> to an immutable Gadfly commit (replace @main below) so a push to
-    # gadfly can't silently change the code that runs with your forwarded secrets.
-    uses: steve/gadfly/.gitea/workflows/review-reusable.yml@main
+    # @v1 = curated release tag (auto-updates on releases); swap for a full @<sha>
+    # if you want an immutable pin. Don't use @main (moves on every push).
+    uses: steve/gadfly/.gitea/workflows/review-reusable.yml@v1
     # Forward ONLY what the reviewer needs. Add provider keys you use
     # (ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, GADFLY_API_KEY) and/or
     # GADFLY_ENDPOINT_M1/M5; drop the findings ones if you don't run telemetry.
@@ -56,7 +61,10 @@ jobs:
       # GADFLY_FINDINGS_URL:     ${{ secrets.GADFLY_FINDINGS_URL }}
       # GADFLY_FINDINGS_TOKEN:   ${{ secrets.GADFLY_FINDINGS_TOKEN }}
     with:
-      # All optional — omit to take Gadfly's defaults. Examples:
-      # models: "qwen3-coder:480b-cloud,gpt-oss:120b-cloud"
-      # specialists: "security,correctness,error-handling"
+      # Cloud-only override so this works with just OLLAMA_CLOUD_API_KEY. Delete
+      # this line (and forward CLAUDE_CODE_OAUTH_TOKEN above) to inherit the full
+      # default swarm (3 cloud + Claude Code sonnet/opus/opus:max, 5 lenses).
+      models: "minimax-m3:cloud,glm-5.2:cloud,deepseek-v4-pro:cloud"
+      # Other inputs inherit the default (5-lens suite, concurrency, 90-min cap);
+      # override any of them here (specialists, provider, base_url, timeout_secs…).
       allowed_users: "your-username"