Canonical params

canonical-params

A results-producing project has a canonical operating point: the named set of default parameter values ({{canonical_values}}) that every reported result implicitly assumes. Changing one of them outside a declared sweep silently forks the project's evidence base — yesterday's figures and today's no longer describe the same system. The contract: protected defaults change only inside a sweep or with explicit user approval, and every approved change leaves a record.

When to use

• Any edit that touches a file or value listed in {{canonical_values}}.
• A "let's quickly try X" impulse during exploration.
• Reviewing a diff that changes a constants/preset/config-default file.
• Deciding whether a new parameter should join the protected set.

When NOT to use

• Sweep code that parameterizes over a value without changing its default — that is the intended mechanism, not a violation.
• Free parameters explicitly documented as unpinned (still record them per run in the meta file — see evidence-convention).
• One-off script arguments (--threshold 0.9) — encouraged; that is exactly where probes belong.

Runbook

1. Identify contact. Does the edit touch {{canonical_values}} (the file, or a frozen token inside it)? No → proceed normally.
2. Classify the intent:
   • Temporary probe → do not edit the default. Revert, and pass the value as a script/CLI/notebook argument instead. Defaults are not a scratchpad.
   • Intentional permanent change → stop and get explicit user approval before the edit.
3. On approval: make the edit, write a decision-log entry (old value → new value, why, what evidence motivated it), and update the document that fixes the operating point (typically a build-log entry recording how the point was chosen).
4. Check the blast radius. A changed canonical value can invalidate cached artifacts, stored baselines, and every figure produced at the old point — state in the decision's Impact section what must be re-run, and let layer-sync hold you to it.

Enforcement (documented, not shipped)

The exemplar pattern is a pre-edit hook: intercept file edits; if the target path is in the protected set AND the edited text matches a frozen-token pattern (specific parameter names, preset identifiers), block the edit and print the probe-vs-permanent instructions from the runbook. Mechanical enforcement catches the honest mistake; this skill is the discipline either way. This pack ships documentation only, no executable hooks.

Rules

1. The protected set is named, small, and closed. List the files (and ideally the exact tokens) in the config block. A protected set nobody can enumerate protects nothing.
2. Probes never edit defaults. Script-level parameters exist precisely so exploration does not touch the canon.
3. Every approved change = decision entry + operating-point document update. The canonical point is part of the scientific record; an undocumented change is drift with a timestamp.
4. Results cite their operating point. Run meta files record the canonical-values hash (see run-provenance), so "which defaults produced this number?" always has one answer.
5. Fixed-by-finding beats fixed-by-fiat. When a canonical value is chosen from a measured sweep, link the sweep evidence; when it is a design guess, label it honestly as "to be calibrated".

Configuration

• {{canonical_values}} — path(s) holding protected defaults, plus optional frozen-token list (e.g. src/config/canonical.py).
• {{decision_log}}, {{evidence_dir}} — where changes and their motivating evidence land.

Provenance & maintenance

Generalized from an operating-point protection rule and its pre-edit guard hook in a working computational-research repository (probe-vs-permanent branching, script-level parameterization for probes, approval-plus-record on permanent change); see the pack's examples/ directory for the worked exemplar mapping. The runbook and rules are verified practice; the hook sketch documents working code without shipping it.

Re-verify in your project:

• git log --oneline -5 -- {{canonical_values}} — every commit touching the canon should pair with a decision entry; spot-check the latest.
• grep -n "<frozen token>" {{canonical_values}} — the protected tokens still live where the config block says they do.
• grep -rn "expectation\|canonical" {{evidence_dir}}/*/meta.json | head -5 — runs record the operating point they assumed (adjust field names to your meta schema).