Hypotheses and the Review Swarm

Status

The swarm is built but off by default in son-of-anton-review (feat/cloudflare-native). With no injected hypothesisWorker and no Prime opt-in, #runHypothesisReview returns null. An unset primary flag does not start shadow workers.

Primary mode also enables Prime unless GILF_PRIME_SHADOW=0. The usability check accepts a non-failed result with findings or at least one completed/succeeded worker. It does not require all workers to succeed.

Cloudflare forwarding gap: cloudflare-native/src/container-env.js does not forward the hypothesis, planner or Prime flags below, and the entrypoint does not inject a worker. Setting those flags only on the Worker cannot enable this pipeline. Enabling it in that deployment requires integration code changes, not just Worker vars. The examples below are environment settings for a directly launched engine process.

Pipeline

1. Preflight builds the context graph and classifies changed files into lenses.
2. planHypothesisReview turns those lenses (or planner output) into hypotheses and assigns one worker lens per hypothesis.
3. runHypothesisWorkers runs one worker per hypothesis with a concurrency cap from GILF_HYPOTHESIS_CONCURRENCY (runner default 4). A worker that throws is recorded as failed; the run continues.
4. synthesizeHypothesisReview filters findings by evidence labels, dedupes them and reports degraded if any worker failed, otherwise completed. Its evolution helper accepts previous findings, but the runner does not pass prior findings into this swarm call; PR continuity is handled later by the runner/service.

The lens floor

Eleven regex lenses classify changed paths. Each matching dimension gets a generic hypothesis and required evidence labels. Files matching no lens get Core Correctness.

The planner appends the static floor after model hypotheses. This preserves the planned checks; it does not guarantee workers execute correctly or resist injected content.

LLM planner

Set GILF_HYPOTHESIS_PLANNER=1 in the engine process to request a planner pass. It reads the diff, graph summary and repository priors. The prompt asks for a file/symbol/behavior, concrete failure and falsifiedBy evidence. Prompt instructions are not proof that the generated hypothesis is correct. Priors add SUPPRESS lens "..." instructions and filter matching model-generated hypotheses; they do not remove static-floor hypotheses.

OpenRouter is the recommended planner provider. Choose a model available to your account and consistent with the free-model policy; no particular model ID is guaranteed by the engine.

Timeouts, invalid output and provider errors fall back to static lenses. With the planner enabled, no worker yields no_hypothesis_worker; Codex yields codex_provider_unsupported. Docs-only and validation-failure semantic skip decisions, rather than all docs-only or failing-validation PRs, skip the planner. The OpenRouter free-model guard is shared with semantic review and defaults on.

Evidence filter

filterFindingsByEvidence keeps a finding only if:

1. Its dimension matches a planned hypothesis.
2. It states falsifiability (falsifiable: true, falsification, or falsifiableBy).
3. Its evidence entries cover every required evidence type for that dimension.

Rejected findings are kept in rejectedFindings and counted in the synthesis summary. Today the filter checks evidence type labels, not artifacts. See validation and evidence for artifact-backed evidence.

This is not independent execution verification. Worker normalization supplies missing falsifiability from the hypothesis and can expand one non-empty evidence string into all required type labels. Keep the distinction between accepted labels and an observed test/log artifact.

Publication ownership

Worker results return to the parent runner, whose ReviewService owns GitHub publication. Prime's prompt forbids publishing, messaging and production mutation. That prompt is an instruction, not an isolation guarantee. In particular, the label “shadow” does not prevent the parent from using swarm findings for semantic-failure recovery.

Prime agent worker backend

Without an injected worker, the Prime adapter is selected by GILF_PRIME_SHADOW=1, or by primary mode unless explicitly disabled. It invokes prime-agent --print --mode json --no-session, normally with --no-context-files, plus provider/model/cwd arguments. The binary and its authentication must be provisioned separately. Source inspection cannot establish a deployed login state.

export GILF_PRIME_SHADOW=1
export GILF_PRIME_AGENT_BIN=/path/to/prime-agent
export GILF_PRIME_PROVIDER=codex
export GILF_PRIME_MODEL=your-provisioned-model-id
export GILF_PRIME_THINKING=low
export GILF_PRIME_NO_CONTEXT_FILES=1
export GILF_PRIME_TIMEOUT_MS=600000

When the repo policy forbids execution, the worker is limited to read, grep and glob tools.

Turning it off

If there is no injected worker and Prime is disabled, no swarm runs. Disable GILF_HYPOTHESIS_PRIMARY as well as GILF_PRIME_SHADOW, or explicitly set the latter to 0 when primary remains enabled.

GILF_DISABLE_HYPOTHESIS_WORKERS=1 only changes the harness capability description in src/harness-evolution.js; it is not a runtime stop switch in CodexReviewRunner.

Source evidence

• son-of-anton-review/src/codex-review-runner.js:1682-1686,2298-2315,2351-2366,2620-2709,3248-3435.
• son-of-anton-review/src/review-hypotheses.js:1-214; src/hypothesis-orchestrator.js:30-62,89-172.
• son-of-anton-review/src/hypothesis-planner.js:189-250,377-391,454-463; src/prime-harness-adapter.js:11-52,212-223.
• son-of-anton-review/src/harness-evolution.js:56-59.
• son-of-anton-review/cloudflare-native/src/container-env.js:15-85; cloudflare-native/container/entrypoint.mjs:345-374.