# Phase `settings` — CI-server settings.toml + `SKIP_CANONICALS_FOR_UPGRADE` + release-tag-first fallback

**Mission (operator-specified 2026-06-17):** two cohesive `resolve_upgrade_base` changes for the cc-ci
server:
1. A **minimal, extensible server-level `settings.toml`** with its first value
   **`SKIP_CANONICALS_FOR_UPGRADE`** (bool, **default `false`**, `false` on this server). When `true`, the
   upgrade tier resolves its base **without canonicals** — codifying that canonicals are an optional
   optimization (an operator switch). The file is structured to hold other CI-server configs later; ship
   it minimal.
2. An **improved no-canonical fallback (always-on, not flag-gated):** when no canonical is used — none
   exists, its promote failed, or the flag is `true` — the base should be the **most recent release TAG on
   `main` older than the PR head** (a real published predecessor), with the **raw `main`-tip only as a
   further fallback** if the recipe has no prior release, then skip. Today the no-canonical path jumps
   straight to `main`-tip, which may be an untagged WIP commit.

These compose: `SKIP_CANONICALS_FOR_UPGRADE=true` always takes the improved release-tag-first fallback.

State files: `STATUS-settings.md`, `BACKLOG-settings.md`, `REVIEW-settings.md`, `JOURNAL-settings.md`. DECISIONS.md shared.

## 1. Background

Canonicals are an optimization + robustness aid for the upgrade base, **not** a requirement: the upgrade
tier already falls back to main-tip when no canonical exists (and the install/backup/restore/custom tiers
never use canonicals). This flag makes that explicit and operator-controllable: a server can run the
upgrade tier purely off main-tip (real predecessor), ignoring the warm-canonical layer entirely — useful
for a deployment that doesn't run the canonical sweep, for debugging, or for a simpler setup.

This server keeps `false` (canonicals on — the optimized/robust path); the flag is the documented escape
hatch.

## 2. Design

**A. A minimal server settings file + loader.**
- A server-level TOML (today cc-ci server config is scattered env vars like `MAX_TESTS`, `CCCI_RUNS_DIR`).
  Add a small settings layer that reads a TOML once. Suggested home: a host path the harness reads (e.g.
  `/srv/cc-ci/settings.toml`), with a tracked `settings.toml.example` documenting the keys + defaults — OR
  extend any existing cc-ci config module if one fits. **Builder: check for an existing cc-ci config
  mechanism first and extend it rather than spawn a parallel one.**
- **Defaults baked into the loader** → an absent file, or an absent key, yields the default (so this server
  needs no file to behave as today). Stdlib only (`tomllib`). Validate: unknown keys warn-and-ignore;
  wrong type errors clearly. Per-server: the file is a host override, not committed config (a tracked
  `.example` is fine; the live file is operator-managed and must carry **no secrets** — secrets stay in
  sops).
- Keep it **minimal + extensible**: one `[ci]`/`[upgrade]` table with the single key now, shaped so future
  CI-server configs slot in without a redesign.

**B. `SKIP_CANONICALS_FOR_UPGRADE` (bool, default `false`).**
- Wire into `resolve_upgrade_base` (`run_recipe_ci.py`): guard the canonical (`version`) branch — when the
  flag is `true`, **skip the canonical lookup entirely** and fall through to the **improved no-canonical
  fallback (§2.C)**. Effectively: behave as if no canonical exists.
- **Scope it narrowly to the upgrade BASE** (its name says so). Do NOT change canonical *promotion* or the
  `--quick` warm-reattach with this flag — those are separate optimizations (a future `SKIP_CANONICAL_SWEEP`
  / `SKIP_QUICK` could gate them; out of scope here — note in DECISIONS).

**C. Improved no-canonical fallback — release tag before main-tip (always-on).** Replace the current
"jump straight to `main`-tip" no-canonical path with:
  1. **most recent release TAG with version strictly older than the PR head** — reuse `samever`'s existing
     helper (newest published version `< head`, from `recipe_tags`, version-ordered); deploy that tag (a
     clean published predecessor) as the base.
  2. **raw `main`-tip** (the target-branch tip) — only if the recipe has **no** prior release tag at all.
  3. **skip** — if neither (no predecessor / head == main-tip with no older tag).
  This applies whenever no canonical is used (none exists, promote failed, or the flag is `true`), so it
  improves this server too (false flag, but un-promoted recipes get a real release base instead of a WIP
  commit). The unified chain becomes: `canonical (unless flag/none/==head) → newest release tag < head →
  main-tip → skip`, with `samever`'s step-back and this fallback sharing the same release-tag helper.
- **Sweep interaction (now better):** with the flag `true`, a cold-on-latest sweep run resolves
  base = newest release tag `< latest` = the **previous release** → the upgrade tier still runs a **real**
  `previous-release → latest` upgrade (not a skip, not a no-op). So `SKIP_CANONICALS_FOR_UPGRADE` swaps the
  base from *last-green canonical* to *latest published predecessor* without losing upgrade coverage. PR
  runs likewise get a real release base. This server runs `false`, so the canonical path is unchanged.

## 3. Gates

**M1 — implemented + unit-tested.** Settings loader (TOML, stdlib, defaults, validation, graceful on
absent/malformed file); `SKIP_CANONICALS_FOR_UPGRADE` wired into `resolve_upgrade_base`; the release-tag-first
no-canonical fallback (§2.C) implemented by reusing `samever`'s newest-release-tag-`<`-head helper. Unit
tests for the **full resolution matrix**: flag `false` + canonical present → canonical (unchanged); flag
`false` + no canonical → **newest release tag `< head`** (NOT main-tip); no canonical AND no older release
tag → main-tip; none → skip; flag `true` → canonical skipped → same release-tag-first fallback; absent
file / absent key → default false; malformed file handled. Adversary cold-verifies: **default is false**
(this server byte-for-byte unchanged); the no-canonical fallback returns a real older **release tag**
(main-tip only as last resort); `true` genuinely bypasses the canonical; the loader can't crash the harness
on a bad/absent file; scope is the upgrade base only (promote/`--quick` untouched); the fallback reuses the
`samever` helper (no divergent version-ordering).

**M2 — verified on the server.** The live server reads the settings (file present with
`SKIP_CANONICALS_FOR_UPGRADE = false`, or absent → default false) and the upgrade path **still uses
canonicals — unchanged**. Demonstrate, with evidence: (a) a recipe **without** a canonical resolves its
base to the **newest release tag `< head`** (a real published predecessor), not the raw main-tip; (b)
flipping `SKIP_CANONICALS_FOR_UPGRADE = true` (test/scratch, not permanent) makes a canonical-bearing
recipe ALSO resolve to that release-tag base (canonical bypassed), then restore `false`. Confirm the
harness picks up the file on the server. Fresh Adversary PASS on both milestones → `## DONE`.

## 4. Guardrails

- **Default `false`; this server stays `false`** — the change must be a no-op for current behavior. A
  regression to the default upgrade-base path fails the gate.
- **Minimal + extensible** — one setting now, structured for more; do not over-build a config framework.
- **Stdlib only** for the loader; **no secrets** in settings.toml (config only; secrets stay in sops).
- **Narrow scope** — the flag affects only the upgrade-base resolver, not promotion or `--quick`.
- Never weaken a test. Commit author `autonomic-bot <autonomic-bot@noreply.git.autonomic.zone>`; push every
  commit. If the settings file lives at a host path requiring a deploy, treat it as a host change (loops
  may deploy if clean + verify health, else file for the orchestrator).

## 5. Definition of Done

A minimal, extensible CI-server `settings.toml` (+ tracked `.example`, defaults in the loader) is read by
the harness; `SKIP_CANONICALS_FOR_UPGRADE` (default `false`, `false` on this server) is wired into the
upgrade-base resolver; AND the no-canonical fallback now prefers the **most recent release tag `< head`**
(reusing `samever`'s helper) with raw `main`-tip only as a last resort. `false`/absent leaves current
behavior byte-for-byte unchanged; `true` bypasses the canonical into the same release-tag-first fallback.
Unit-tested across the full resolution matrix; verified live on the server (false = unchanged; no-canonical
recipe → release-tag base; true = canonical bypassed, then restored). Scope limited to the upgrade base
(promote/`--quick` separate). M1 + M2 fresh Adversary PASSes in REVIEW-settings.md.