cc-ci/machine-docs/BACKLOG-settings.md

BACKLOG — phase settings

Build backlog

• B1 — harness/settings.py: stdlib tomllib loader, [upgrade].skip_canonicals_for_upgrade (bool, default false), _SCHEMA single-source defaults+validation, graceful on absent/malformed, warn-and-ignore unknown keys/tables, raise on wrong type. Path $CCCI_SETTINGS / /etc/cc-ci/settings.toml.
• B2 — tracked settings.toml.example documenting keys + defaults (no secrets).
• B3 — wire SKIP_CANONICALS_FOR_UPGRADE into resolve_upgrade_base (run_recipe_ci.py): flag true → bypass canonical lookup → no-canonical fallback. Scope = upgrade base only.
• B4 — improved no-canonical fallback _no_canonical_base (§2.C): newest release tag < head (reuse warm_reconcile.newest_older_version) → main-tip → skip. Always-on.
• B5 — unit tests: full resolution matrix (tests/unit/test_upgrade_base.py) + loader (tests/unit/test_settings.py). 315 unit pass, lint clean.
• B6 (M1 claim) — clean tree, push, claim M1 in STATUS-settings.md.

M2 (after M1 PASS)

• B7 — deploy to cc-ci (/etc/cc-ci git pull + nixos-rebuild if needed); confirm harness reads settings (absent → default false; or file present false).
• B8 — live evidence (a): a recipe WITHOUT a canonical resolves base to newest release tag < head (not raw main-tip).
• B9 — live evidence (b): flip SKIP_CANONICALS_FOR_UPGRADE = true (scratch) → a canonical-bearing recipe ALSO resolves to the release-tag base (canonical bypassed); then restore false.
• B10 (M2 claim) — claim M2; on fresh PASS of M1+M2 → ## DONE.