ruvnet--RuView/.github/scripts/nightly-sota/README.md

Nightly SOTA research agent

nightly-sota-agent.yml turns recent public research into at most one repository issue and, for low-risk topics, one draft offline-prototype pull request. It is intentionally not a general-purpose autonomous coding agent.

Enablement

The committed schedule is 03:17 UTC every day. Scheduled runs stay disabled until both repository settings exist:

1. Actions secret COGNITUM_NIGHTLY_API_KEY, issued with only the Cognitum completions:mid scope.
2. Actions variable RUVIEW_NIGHTLY_SOTA_ENABLED=true.

The key must not receive guidance-write, evolve, pods, brain, Flywheel-write, or administrative scopes. First run the workflow manually in dry-run mode; that mode only collects a bounded evidence artifact and never reads the secret or writes an issue. Manual live mode is restricted to the repository owner.

The repository must also allow GitHub Actions to create pull requests. Normal branch protection must require at least one approving review and the Verify contributor harness status check. The publisher requires that exact job-name check to be bound to the GitHub Actions app, uses GitHub's effective-active-rules endpoint, and stops before prototype generation when either requirement is absent. It does not request an administrative token to inspect hidden ruleset bypass actors; safety does not depend on that metadata because the publisher has no merge or main-push path.

Authority split

Job	External credential	Repository authority	Result
collect	none	contents read	Normalized public Cognitum registry and recent arXiv evidence
propose	Cognitum completions key	contents read	One schema-checked proposal
score	none	contents read	Frozen Darwin digest, completeness score, honest-null Flywheel replay
issue	GitHub token	issue write, PR read	One deduplicated issue
implement	Cognitum completions key	contents read	Declarative transform and test vectors
validate	none	contents read	Schema, template, syntax, claim, path, digest, and replay checks
publish	GitHub token	branch/issue/draft-PR/Actions write	One draft PR and an explicit read-only harness-verifier dispatch

The Cognitum key and a write-capable GitHub token never coexist in one job. Model output is never executable code. Repository-owned templates emit the prototype module and tests, which this workflow syntax-checks but never runs.

Hard boundaries

• Public HTTPS sources are fixed to the Cognitum application registry and the arXiv Atom API. Redirects, oversized responses, unexpected media types, and schema drift fail closed.
• Retrieved text is CLAIMED, untrusted evidence. It is quoted inside a fixed trusted prompt and cannot grant authority.
• The Darwin genome is read-only. Scheduled jobs never invoke Darwin evolution.
• Flywheel runs a separate committed honest-null canary. A valid canary stays root-only, rejects its candidate, and reports zero verified improvements and no promotion. It does not evaluate the nightly proposal. The workflow's static authority split and artifact gates are what prevent nightly learning or promotion.
• High-risk topics stop at an issue. This includes production, security, authentication, release/deployment, workflows, dependencies, firmware, hardware, networking, native plugins, HomeKit pairing, and voice protocols.
• Low-risk model output is a closed transform DSL: bounded scalar test vectors and 1-8 allowlisted operations (center, normalize-peak, absolute, square, difference, moving-average, or clip). Local trusted templates emit exactly five .md, .json, and .mjs files below examples/research-sota/nightly/<fingerprint>/. Existing files, symlinked parents, dependencies, binaries, executable modes, and more than 400 lines are rejected.
• Publication is a draft PR. The agent cannot approve, merge, release, promote, or modify the reviewed shared brain.

Deduplication and failure behavior

The stable fingerprint hashes sorted evidence IDs, finding class, and subsystem. Issues and PRs carry an exact hidden marker. Only markers on github-actions[bot] records with the automation label are trusted for deduplication, so copied issue text cannot suppress future runs.

A failure leaves the last completed bounded artifact for seven days. Model, protection-preflight, or validation failures may leave an issue without a PR; maintainers can inspect the run and decide whether to continue manually. The workflow does not retry a failed model call, force-push a branch, close an issue, or delete a branch.