Operations · Lesson 02 of 02
Troubleshooting, drift, and upgrades
How to diagnose ota doctor findings, resolve contract drift against new failures, and manage Ota version upgrades safely.
Learning objectives
- Use
ota doctorto identify the top blocker - Resolve a declared-vs-actual contract drift
- Run
ota self-updateand verify the update
Prerequisites
Troubleshooting starts by classifying the failed layer: contract validation, readiness, admission, execution, proof, provider behavior, or source drift. Treating every failure as a task failure hides the ownership boundary needed for a durable fix.
Use the narrowest truthful diagnostic
Validate checks contract shape. Doctor prioritizes readiness. Dry-run shows admission and planned selection. JSON provides typed reasons. Explain turns findings into ordered remediation. Re-run real execution only after the blocking layer is understood.
ota validate --jsonota doctor --jsonota explain --jsonota run --dry-run --json testReconcile drift through review artifacts
When repository truth changes, publish a fresh detection or upgrade candidate and review the semantic operations. Do not hand-wave stale evidence, silently rewrite ota.yaml, or use an old candidate after its source inventory no longer matches.
ota detect --candidate-out .ota/candidates/current.json .ota contract apply-candidate .ota/candidates/current.json --json .Canonical terminology
Commands and expected output
ota doctor --jsonota receipt --baseline promoted --jsonota self-updateEvidence boundary for this lesson
Establishes
- The worked examples establish the lesson's canonical Ota distinctions for its stated scope.
Does not establish
- Reading the lesson does not validate a repository, execute its tasks, or establish organizational acceptance.
Knowledge check
Why should source drift produce a new candidate instead of a silent contract rewrite?
The previous review was bound to earlier evidence. A new candidate makes changed inputs, operations, conflicts, and resulting identity reviewable again.