animation/.agents/rules/working-files.md

# Working files — keep milestones, not steps

Applies to every staged working lane under `characters/` and `clothing/work/`:
folders where a chain of `NN_*.py` scripts each open a `.blend`, change it, and
save. Left unmanaged those lanes grow ~80 MB per attempt. Lena's lane reached
**3.0 GB, of which 2.2 GB was 30 `.blend` files** — five 80 MB snapshots to land
one crotch fix, five more to land one bra fix.

## The rule

**A version is a milestone, not a step.** You get a saved copy when a change is
finished and approved — not after every cut that got you there. Fixing the bra
produces *one* file at the end, not one per attempt.

Four tiers:

| tier | what | policy |
|---|---|---|
| **KEEP** | the `NN_*.py` recipe, mask/input `.npz`/`.npy`, reference images, registered `_vNN.glb` artifacts | permanent. Governed by `characters/REGISTRY.md` (rule 9: superseded artifacts move to `archive/`, never deleted) |
| **MASTER** | the handful of `.blend` files a registered artifact was actually built from, plus the live chain head | pinned by name in the lane's `.lanekeep`. Aim for ≤6 per lane |
| **SCRATCH** | per-attempt `.blend`, `.blend1` autosaves, `review*/` and `dbg_*/` render dirs, `*_run.log` | overwritten freely, pruned any time, never committed |
| **UNKNOWN** | a `.blend` in a folder with no step scripts — hand-authored, so no recipe rebuilds it | never auto-deleted; decide by hand |

The key asymmetry: **the `.py` scripts are the history.** They are kilobytes and
they regenerate any intermediate state from the pinned master above it. Keeping
20 `.blend` files is keeping 20 copies of the same 950k-vertex mesh to avoid
re-running a script that takes a few minutes.

## How to work in a lane

- **Roll one working file.** Pass the same `work.blend` as the output of each
  experimental step. Only write a new named `.blend` at a phase boundary
  (geometry done, texture done) or when a step's result gets registered.
- **Name the end state, not the attempt.** `10_welded.blend` earns a name;
  `10_healed` → `10_rimheal` → `10_seamheal` on the way there do not.
- **Reuse one `review/` dir.** QA renders are regenerable; minting `review29/`
  because 28 exist is 8 MB for nothing.
- **No `.blend1` autosaves.** Step scripts set
  `bpy.context.preferences.filepaths.save_version = 0` before saving.
- **Pin as you go.** When an artifact is registered in `characters/REGISTRY.md`,
  add its master `.blend` to `.lanekeep` in the same edit that adds the registry
  row. Anything not pinned is scratch by definition.

## `.lanekeep`

One filename per line, `#` for comments, inline comments allowed. A `.blend`
earns a line only when a registered artifact was built from it, or it is the
head of the live chain. Unpin the head's parent once the head is accepted.

## Pruning

```
python tools/prune_lane.py characters/female/lena_nude --recursive   # dry run
python tools/prune_lane.py <lane> --apply                            # delete scratch
```

Dry run by default. It never deletes KEEP, MASTER or UNKNOWN, and it flags
binaries that are byte-identical to a registered original in
`characters/originals/` (the canonical filename always survives a duplicate
pair, never the ` - Copy`).

**Before `--apply`, check nothing is mid-flight.** These runs take minutes and
write their output at the end; a lane can gain a new head while you are looking
at it. Confirm no `blender` process is running and that the newest `.blend` is
pinned.

## Committing

Scratch patterns are in `.gitignore` and must never be committed. `.blend`,
`.zprj`, `.obj`, `.npy`/`.npz` and the rest of the heavy formats are LFS-tracked
in `.gitattributes`, so a pinned master can be committed safely — but note that
`.png`/`.jpg` deliberately are **not** (≈250 are already tracked raw; adding them
would rewrite every one without shrinking history). A lane's QA renders are
scratch for that reason too, not just a disk one.