Ownership Model

Workloom tracks the ownership state of every file it renders. This prevents accidental overwrites, enables safe conflict resolution, and gives you confidence about what Workloom manages vs. what belongs to you.

The Five States

Every file that Workloom is aware of is in one of five states:

State	Meaning	What wl pull does	What wl sync does
user_owned	Not managed by Workloom	Ignores	Never writes
owned_clean	Hash matches last applied	OK	No-op or safe update
owned_missing	Workloom-owned but absent	OK	Recreates from desired state
owned_locally_modified	You edited it	Warns only	Fails unless explicit restore
owned_conflict	Both you AND desired state changed	Warns only	Fails; requires diff/restore

How It Works

When Workloom renders a file, it records the content hash in .loom/state.json:

{
  "files": {
    "CLAUDE.md": {
      "state": "owned_clean",
      "hash": "sha256:a1b2c3...",
      "package": "@acme/frontend-baseline",
      "version": "1.2.0",
      "renderedAt": "2026-05-12T10:00:00Z"
    }
  }
}

On the next wl pull or wl sync --check, Workloom:

1. Computes the current file's SHA-256
2. Compares to the recorded hash
3. Transitions state accordingly

Conflict Resolution

When a conflict is detected (you edited a file AND the desired state changed), you have options:

# See what changed
wl diff CLAUDE.md

# Keep your local version (tracked as override)
wl pull --on-conflict keep-local

# Restore to desired state (discards your edits)
wl restore CLAUDE.md

# Promote your edit to a workspace override
wl pull --on-conflict promote-to-override

Default Policy: Fail Safe

By default, wl pull refuses to overwrite locally modified files. It exits with code 4 and reports the conflict. You must explicitly choose a resolution.

This is intentional — silent overwrites destroy work and erode trust.

Configuring Conflict Policy

In .loom/binding.toml:

[conflict]
policy = "fail"  # Default: stop and report

# Other options:
# policy = "keep-local"           # Never overwrite, track modifications
# policy = "restore"              # Always restore to desired state
# policy = "promote-to-override"  # Turn local edits into workspace overrides

Or per-command:

wl pull --on-conflict keep-local

State Transitions

                    ┌─── wl pull (new file) ───┐
                    ▼                           │
              owned_clean ◄── wl restore ──────┤
                    │                           │
            user edits file                     │
                    │                           │
                    ▼                           │
        owned_locally_modified                  │
                    │                           │
          desired state changes                 │
                    │                           │
                    ▼                           │
            owned_conflict ────────────────────►│
                    │
         explicit resolution
          (restore/keep/promote)

What Workloom Never Touches

• Files not in any render plan (your code, configs, etc.)
• Files marked as user_local projection scope
• Files in .loom/ itself (binding, lock, state are managed separately)
• Anything outside the bound workspace directory

Workloom's wl restore only restores files it owns. It never deletes "unknown" files — those are yours.