ruvnet--RuView/docs/adr/ADR-284-bounded-nightly-sota-agent.md

# ADR-284: Bounded nightly SOTA research agent

| Field | Value |
|---|---|
| Status | Accepted - implementation gated off by default |
| Date | 2026-07-29 |
| Builds on | ADR-283 |

## Context

RuView needs a repeatable way to notice relevant state-of-the-art work and turn
it into reviewable repository activity. A nightly model with simultaneous
network, repository-write, policy-evolution, and execution authority would
create an unacceptable prompt-injection and supply-chain boundary. It could
also confuse generated confidence with scientific evidence or silently turn a
research suggestion into production code.

Cognitum exposes an OpenAI-compatible completion service and a public
application registry. The contributor harness already commits a Darwin genome
and a signed Flywheel replay gate. Those components can support nightly
research without granting unattended learning promotion.

## Decision

Add a scheduled GitHub Actions workflow that runs daily at `03:17 UTC`, remains
disabled until a maintainer enables a repository variable, and supports a
manual evidence-only dry run.

The live flow has seven jobs:

1. Collect bounded public Cognitum-registry and recent arXiv evidence.
2. Ask Cognitum `cognitum-mid` for one proposal that is locally validated
   against a strict schema.
3. Score proposal completeness using the frozen Darwin policy and verify an
   honest-null Flywheel replay.
4. Deduplicate or create one issue.
5. For a locally classified low-risk proposal only, ask Cognitum for a tiny
   declarative transform and bounded test vectors. Trusted repository templates
   turn that data into the prototype module, tests, JSON, and README.
6. In a job with no external secret or GitHub write token, revalidate every
   artifact, verify the Flywheel replay, and perform static and syntax checks
   without executing generated code.
7. In a job with no model credential, re-hash the validated artifacts, create a
   new branch, open one draft PR, link it to the issue, and explicitly dispatch
   the credential-free contributor-harness verifier.

The jobs exchange bounded JSON artifacts. Cognitum receipts retain the
provider, endpoint, exact resolved tier/model, request ID, a recomputable
routing attestation, and digest metadata. Credential-free validation rebuilds
the deterministic request and verifies its digest. The raw-output digest is
audit metadata only because raw model transcripts are not retained.

## Security and evidence policy

Retrieved titles, abstracts, descriptions, and links are untrusted `CLAIMED`
evidence. Source hosts, paths, media types, redirects, time, byte counts,
records, and citations are validated. The fixed trusted prompt states that
evidence has no instruction authority. Model output is parsed as one JSON
object and locally reconstructs risk, citations, implementation disposition,
and fingerprint.

Risk classification is deliberately conservative. Security, authentication,
cryptography, workflow, dependency, release, deployment, production, firmware,
hardware, network-server, native/Wasmtime plugin, HomeKit pairing, STT/TTS, and
satellite-voice proposals are issue-only.

Autonomous implementation is restricted to new files beneath a fingerprinted
`examples/research-sota/nightly/` directory. The model cannot supply paths or
source text. It selects only a schema-bounded scalar transform and matching
test vectors; repository-owned templates deterministically emit exactly five
files. It cannot edit existing files or add dependencies. File count, size,
line count, paths, symlink ancestry, numeric bounds, operation schema,
secret-shaped values, canonical template digests, and accuracy claims are
checked. Emitted source receives syntax checking, but is not executed.

The deterministic score is named `PROPOSAL_COMPLETENESS`. It is explicitly not
a novelty, scientific-quality, safety, or performance score.

## Darwin and Flywheel boundary

Nightly automation reads the committed Darwin genome as frozen prompt policy.
It never calls Darwin evolution or any Cognitum evolve, pod, guidance-mutation,
brain-write, or promotion endpoint.

Flywheel evaluates the unchanged policy with the repository's honest-null
fixture. The signed replay must verify, report zero verified improvements, and
report no promotion. This canary proves only that the committed Flywheel gate
stayed root-only, rejected its candidate, and did not promote under the frozen
fixture. It does not evaluate the proposal. The no-learning/no-promotion
boundary for the nightly run comes from the workflow's static authority split,
closed commands, and artifact validation.

## Credentials and publication

Scheduled enablement requires:

- repository secret `COGNITUM_NIGHTLY_API_KEY`, limited to
  `completions:mid`; and
- repository variable `RUVIEW_NIGHTLY_SOTA_ENABLED=true`.

Model jobs receive no write-capable GitHub token. GitHub mutation jobs receive
no model key. Validation receives neither. The publish job has the additional
`actions:write` permission solely to dispatch the read-only
`ruview-harness-flywheel.yml` verifier with Darwin disabled, because a PR
created by the workflow token may not trigger ordinary pull-request workflows.

The agent creates draft PRs only. It cannot approve, merge, release, promote a
Darwin candidate, or update canonical shared-brain records. Before any branch
write, it re-fetches the issue and repository rules. Publication requires the
issue to remain open, bot-authored, correctly labelled, and fingerprint-bound;
`main` must require at least one approving review and the
`Verify contributor harness` job-name check. The publisher requires that exact
check name and GitHub Actions integration ID from GitHub's
effective-active-rules endpoint. GitHub hides
ruleset bypass actors from read-only tokens, so the workflow is not given an
administrative token to inspect them. Its safety does not depend on that
metadata: the publisher can create only a non-default branch and draft PR and
contains no merge, approval, or `main`-push path. Branch protection and
maintainer review remain the authority boundary.

## Consequences

RuView gains a low-volume research flywheel with durable evidence, stable
deduplication, and inspectable failure artifacts. A compromised paper,
registry record, or model can at worst propose bounded new example files that
still require static gates and human review.

The tradeoff is intentionally limited autonomy: production ideas become issues,
generated prototypes are not executed, and a missing credential, service
outage, schema drift, or validation ambiguity stops the run rather than
guessing. Maintainers must explicitly enable the schedule and permit Actions to
create pull requests.