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) #

# 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.