ADR 0085: Migrations validate before schema stamping and refuse newer configs

Status: accepted

The migration chain is discern's upgrade safety story: a project records [meta].schema_version runs every pending step, then stamps the project as current. ADR 0014 already says the migrated result must be validated before stamping, but the implementation did not enforce that boundary. A comment-preserving TOML edit could leave discern.toml syntactically invalid or schema-invalid, while upgrade still exited successfully and stamped the current schema. Every later command would then fail on the user's now-current but unreadable config.

The same boundary was missing in the other direction. A project written by a newer binary records a schema version greater than this binary supports. The old binary has no migration to run, because pendingMigrations(newer, older) is empty, so it treated the install as up to date and a full upgrade stamped the recorded version down. That silently converted "you need a newer binary" into "your current config is malformed," pushing the user toward deleting valid newer keys.

Guideline compilation has a different failure model. ADR 0065 deliberately made per-artifact guidance failures non-fatal so one blocked generated file does not prevent the rest of setup or refresh from completing. Config validity is not the same kind of work: a bad discern.toml breaks the command surface itself, so it cannot share that soft-failure semantics.

upgrade proves the migrated discern.toml parses and validates against the current schema before it recompiles guidance or stamps [meta].schema_version. If validation fails returns a hard invalid_migrated_config failure and leaves the recorded schema untouched. The migration's partial file edits may still be present, but the project is not marked current; a fixed, idempotent migration can be re-run from the same recorded version.

A recorded schema greater than this binary's SCHEMA_VERSION is a hard forward skew refusal on every migration-status surface: upgrade, upgrade --check, and upgrade all return schema_version_too_new with the user-facing message "this project needs a newer discern — re-run the installer." They do not compute a pending set, do not report "up to date," and do not stamp the schema down.

The explicit no: guideline refresh failures remain non-fatal after config validity is proven. Config validity is a prerequisite for stamping; generated guidance is a refresh artifact whose failures are reported but isolated.

• A migration bug can no longer create a stamped brick. The user may still need a fixed binary to repair a partially edited config, but discern does not hide the failure behind a current schema number.
• Older binaries fail accurately on newer installs. The recovery advice is to update discern, not to delete config that may be valid for the newer schema.
• Migration tests now include an executable validity net: migration outputs are parsed, full upgrade-corpus entries validate with zero schema issues, and a deliberately invalid synthetic migration pins the hard-failure behavior.
• The cost is that upgrade can now fail after migration steps have written files but before guidance refresh or schema stamping. This matches the existing idempotent-chain design: the recorded schema remains behind, so the repaired chain replays rather than skipping the failed step.

• Warn but do not stamp. Rejected because a warning still exits through a successful-looking path and asks callers to infer that the install is not current. A config that cannot be read is the hard failure the migration system exists to prevent.
• Validate only TOML syntax. Rejected because schema-invalid TOML is still unusable to the current engine. The proof must be the same parser and schema every later command will use.
• Let newer configs pass as "up to date." Rejected because an older binary cannot know that no migration is needed. A monotonic schema version is only meaningful if forward skew refuses instead of pretending compatibility.