Writes and Caching

Use this page when you need to know what ota may change on disk and what it must leave alone.

Mutations must stay explicit, and cache state should never outrank filesystem truth, so read-only review stays trustworthy.

• map each command to whether it reads or writes before you rely on its output
• use review-first commands and move to explicit write modes only after checking the preview
• merge commands only apply eligible additive changes, so review remains safe before write
• rewrite commands are destructive and require explicit confirmation
• policy-aware diagnosis stays read-only
• hidden mutation paths are not allowed

ota should only write when the command explicitly says it can.

If the command is read-only, it should stay read-only even when it has enough information to suggest a change.

• repo detect and workspace detect are review-by-default; writes happen only with --write, --merge, or --rewrite
• ota detect --write persists the first conservative detect-write candidate when no contract exists
• ota detect --write, --merge, and --rewrite preserve versioned pnpm/yarn-backed Node engine requirements as canonical toolchains.node ownership plus deterministic Compose service wiring when those signals are high-confidence
• ota detect --merge applies only eligible additive fields after preview with --merge --dry-run
• ota detect --rewrite --yes replaces only after a --rewrite --dry-run review
• ota workspace detect follows the same pattern with --write, --merge, and --rewrite
• init commands are explicit scaffold paths and may only write when you choose that mode

• ota detect --write
• ota detect --merge
• ota detect --rewrite --yes
• ota workspace detect --write
• ota workspace detect --merge
• ota workspace detect --rewrite --yes
• ota init
• ota workspace init

• default ota detect/ota workspace detect behavior is read-only unless a write mode is selected
• ota detect --contract is text-only and does not write
• doctor and policy review do not mutate contracts
• check does not mutate contracts
• workspace doctor and workspace check stay read-only
• policy-aware diagnosis stays read-only

Caching is only an implementation detail for repeated reads.

It exists to avoid re-parsing and re-scanning when nothing meaningful changed.

• repo cache entries are keyed by normalized file path and content hash
• workspace cache entries use the same path+hash strategy for ota.workspace.yaml
• changed file contents invalidate cache keys on next read
• cache is for performance only and does not alter command semantics
• if the filesystem changes, ota must trust the filesystem over any cached copy

• use review-only commands when you want to inspect first
• use merge when you want ota to apply only eligible additive changes
• use rewrite only when you want to replace the existing file explicitly
• use doctor when you want to inspect readiness without writing
• use detect --dry-run when you want a safe preview of what would change
• use the Agent boundary section in detect/init preview to understand whether ota inferred a usable agent lane, a partial boundary, or intentionally omitted agent because no safe task was inferred
• treat external structured AGENTS.md / CLAUDE.md command sections and exact Task | Command tables inside those sections as low-authority detect hints rather than canonical execution truth; ota-generated agent docs and broader prose stay out of detect evidence
• use detect --merge --dry-run and workspace detect --merge --dry-run before additive writes
• use detect --rewrite --dry-run and workspace detect --rewrite --dry-run before destructive replacement

• preview a contract change before writing it
• keep detect --dry-run review-only
• know that init writes only when asked
• avoid stale contract state
• trust that a cached parse never wins over the current file on disk

• not a background sync engine
• not a persistent hidden state machine
• not a general-purpose cache policy surface
• not a replacement for the contract or filesystem truth
• not a place where stale state can outrank what is on disk