# The pit — a filesystem task queue

The pit is just directories. Snakes coordinate entirely through atomic `mv` between them — moving a
file within one filesystem is atomic, so two snakes can never devour the same food.

```
pit/
  food/      the queue: tasks waiting to be eaten        (food-<id>-<slug>.md)
  claimed/   in digestion: a snake is working this one   (<snake-id>.food-<id>-<slug>.md)
  done/      regurgitated WHOLE: a finished result        (food-<id>-<slug>.result.md)
  scraps/    regurgitated in PARTS: notes/leftovers        (anything; informational)
  waste/     excreted waste: chat logs, debug traces       (<snake-id>-<ts>.log)
```

> Sub-tasks ("broken / digested parts") are regurgitated back into **`food/`** as new food items, so
> any snake can devour them. `scraps/` is for non-actionable leftovers a snake wants to keep around.

## Food schema (`pit/food/food-<id>-<slug>.md`)

```markdown
# food-0007-reverse-string
- **task:** Implement a `reverse(s)` function in scraps/reverse.py and a test that proves it.
- **done-when:** `python -m pytest scraps/test_reverse.py -q` is green.
- **tossed-by:** keeper        # or another snake, if this is a regurgitated sub-task
```

Keep food small and self-contained — one unit a snake can digest in a sitting. If a task is too big,
a snake regurgitates it as several smaller food items.

## The eating protocol (snakes)

1. **Devour** — atomically claim one item:
   `mv pit/food/food-0007-reverse-string.md pit/claimed/snake-2.food-0007-reverse-string.md`
   If the `mv` fails, another snake beat you to it — pick a different one.
2. **Digest** — do the work described in the food.
3. **Regurgitate** — *whole*: write the result to `pit/done/food-0007-reverse-string.result.md`
   and `git`-free remove the claimed file. *In parts*: if it decomposes, write new `food-*` items
   into `pit/food/` for other snakes, and note that in your result.
4. **Excrete** — drop your working log/trace as `pit/waste/snake-2-<ts>.log`; don't let it pile up
   in the workspace.
5. **Choke?** On the 3rd identical failure, regurgitate the food back to `pit/food/` (or leave it in
   `claimed/` past the cleanup timeout) with a note in `scraps/`, so another snake or the keeper
   takes it.

## Cleanup duty

The cleanup snake sweeps `waste/` (summarise then prune old logs) and **reclaims** food left in
`claimed/` longer than the abandonment timeout — a sign the snake choked or died — by moving it back
to `food/` so a healthy snake can devour it.