ADR-0004: Ownership model and idempotent sync

• Status: Accepted
• Date: 2026-06-27
• Deciders: Founding engineer

Context

repospec sync regenerates files. Without an explicit ownership model it will eventually overwrite a human's edits — the fastest way to lose trust in a file generator. The principles "human decisions always win" and "single owner" demand a precise rule. (Weakness W4.)

Decision

Every file Repospec touches has exactly one owner:

• Human-owned: everything under .repospec/. Repospec seeds these once from templates during init. After that, Repospec never modifies them silently. They are the source of truth.
• Repospec-owned: adapter outputs (e.g. CLAUDE.md, .cursor/rules/repospec.mdc). Generated from .repospec/, regenerated by sync.

Repospec-owned files carry a managed header that includes:

• a clear "generated by Repospec — edit .repospec/ instead" notice,
• the source protocol version,
• a content checksum of the generated body.

repospec sync algorithm:

1. Render desired output.
2. If the on-disk file is absent → write it.
3. If present and its body matches the stored checksum → safe to replace.
4. If present and modified out-of-band (checksum mismatch) → do not overwrite; warn and require --force (or show a diff).

Sync is idempotent: running it twice with no .repospec/ changes produces no writes. init is re-run safe: an existing .repospec/ triggers update/upgrade rather than overwrite. Destruction always requires an explicit flag.

Consequences

Positive

• Humans can never lose authored content silently.
• CI can run repospec sync --check to detect drift without mutating files.

Negative / trade-offs

• Managed headers add minor noise to generated files (acceptable; common practice, e.g. generated lockfiles/codegen).

Neutral / follow-ups

• Consider a repospec sync --check mode for CI as part of the sync issue.

Alternatives considered

• Always overwrite — simple, destroys edits. Rejected.
• Three-way merge — powerful but complex and surprising for prose files. Deferred; checksum-guard + --force is enough to start.