core/docs/decisions/ADR-0155-ci-contemplation-runner.md

# ADR-0155 — CI contemplation runner (W-021)

Status: scoping
Date: 2026-05-25

## Context

ADR-0150 (W-018) made contemplation autonomous at checkpoint.
ADR-0151 (W-017) auto-proposes from enriched candidates at load.
ADR-0152 (W-019) closes the engine-authored proposal loop.
Operator (Shay) currently runs sessions from a single workstation
with intermittent connectivity.

A GitHub Actions runner is deterministic Linux compute that the
operator can trigger from anywhere. Running contemplation cycles on
that compute amortizes wall-clock contemplation cost without
sacrificing CORE's HITL doctrine — provided the output is gated
through pull-request review before any corpus mutation.

Budget on GitHub Pro (Student): 3,000 Actions minutes/month on
Linux runners (1× multiplier). A 10-min contemplation run every 4
hours costs ~1,800 min/mo (60% of budget); nightly costs ~900 min.

## Decision

Add `.github/workflows/contemplation.yml`:

- Triggers: `schedule:` (nightly at 09:00 UTC = 01:00 PST) and
  `workflow_dispatch:` (manual).
- Soft kill switch: skips when repo variable `CONTEMPLATION_ENABLED`
  is not `"true"`. Operator toggles in repo settings without
  editing the workflow.
- Runs `core demo learning-arc --json`, writes the report to
  `contemplation/runs/YYYY-MM-DD-HHMMSS.json`.
- Opens a PR against `main` with the new run via
  `peter-evans/create-pull-request@v7`. Operator review on the PR
  is the ratification gate.
- Concurrency group prevents overlapping runs.

The CI runner **never** commits directly to `main`, **never**
mutates `corpora/`, **never** registers recognizers, **never**
ratifies proposals. It only writes a report file under
`contemplation/runs/` and proposes the diff via PR.

## Invariants preserved

- ADR-0150 HITL gate: every proposal still passes through operator
  review. CI just stages the candidate.
- Determinism (CLAUDE.md): `ubuntu-latest` is consistent enough
  for trace_hash equality. First-run verification: compare a local
  `core demo learning-arc --json` against the CI output for the
  same commit SHA; they must byte-match on the
  `proposal_id` / `trace_hash` fields. If they diverge, the
  underlying determinism gap is a substrate bug to fix, not a
  reason to relax the invariant.
- No new trust boundary on disk: CI writes only to
  `contemplation/runs/` (a new directory dedicated to CI output);
  existing trust boundaries are unchanged.
- Acceptable Use Policy: output is a project artifact (proposals
  about CORE's corpus), so contemplation runs are defensibly
  "production, testing, deployment, or publication of the software
  project" per GitHub AUP §5. Idle / unbounded compute is not
  scheduled.

## Trust boundary

The CI workflow has `contents: write` and `pull-requests: write`
on a branch named `contemplation/<date>`. It cannot push to `main`
(protected branch). The HITL surface is the PR review UI —
identical to existing operator workflow for human-authored
proposals.

## Out of scope

- **Persisted engine state across CI runs.** Each run starts from
  the committed corpus and produces a one-shot report. A future
  ADR may track engine-state evolution across runs by committing
  `engine_state/` under a CI-only branch, but only after operator
  review on each step.
- **Auto-merge.** Never. Every CI proposal stays open until the
  operator merges or closes.
- **Cross-runner determinism.** Pinning to `ubuntu-latest` is
  acceptable; switching runner classes invalidates the
  trace_hash equality check.
- **Recognizer growth.** ADR-0154 enables the registry to grow
  from live traffic, but CI runs do not produce traffic the
  registry should learn from (they are synthetic exercises). The
  CI runtime sets the producer queue but does not persist
  derived recognizers to the committed engine_state.

## Validation

- First run (manual `workflow_dispatch`) produces a PR with a
  `contemplation/runs/<date>.json` file.
- Local + CI runs at the same SHA produce byte-identical
  `proposal_id` and `trace_hash` fields (manual check on first
  enable).
- Workflow exits 0 with no PR created when no proposal is
  produced (idempotent runs).
- Soft kill: setting `vars.CONTEMPLATION_ENABLED=""` causes the
  job to skip on the next scheduled tick.

## Operator runbook

1. Repo Settings → Secrets and variables → Actions → Variables:
   set `CONTEMPLATION_ENABLED=true`.
2. Actions tab → "contemplation" workflow → "Run workflow" once
   to verify.
3. Watch the resulting PR; review the proposal as you would any
   `core teaching proposals` entry.
4. Merge to accept (proposal becomes part of the audit trail) or
   close to reject.
5. Disable: set `CONTEMPLATION_ENABLED=""` (empty); the workflow
   exits early without consuming meaningful minutes.

## Closure

After this ADR, CORE has a remote compute path for contemplation
that preserves the operator-as-gate invariant. The operator gains
asynchronous contemplation cycles tied to the project's own audit
trail, with no new infrastructure to maintain beyond a single
workflow file.