Docs

Aromba — Chores

A chore is one file: a header that describes it and a script that does it. The engine reads the header to decide when and how it may run. Nothing runs without a valid header.

The format is meant to carry any recurring or reactive task on a machine — cleaning is just the first use. A chore can run on a schedule, on an event, on a threshold, on demand, or when another chore asks for it.

1. File format

# chores/sweep/old-downloads.sh
# ---
# name: Old Downloads
# verb: sweep          # sweep | fix | prepare | guard | watch | report | run
# os: linux, mac
# safety: yellow       # green | yellow | red
# touches: files in ~/Downloads older than {days} days
# needs: find
# trigger: night       # night | often | hourly | daily | on-demand | event:<name> | after:<chore>
# params: days=30 path=~/Downloads
# default: off
# author: core         # core | community | assistant
# ---
set -euo pipefail

if [ "${AROMBA_DRY_RUN:-0}" = "1" ]; then
  find "$P_path" -type f -mtime +"$P_days" | wc -l
  exit 0
fi

n=0
while IFS= read -r f; do
  mkdir -p "$AROMBA_QUARANTINE$(dirname "$f")" && mv "$f" "$AROMBA_QUARANTINE$f" && n=$((n + 1))
done < <(find "$P_path" -type f -mtime +"$P_days")
echo "moved=$n" >> "$AROMBA_RESULT"
echo "Old Downloads: moved $n files to quarantine" >> "$AROMBA_RECEIPT"

Header fields

Triggers

Events are emitted by watchers (below) and by the engine itself. A chore can list several triggers: trigger: night, event:disk-95.

Environment the engine provides

2. Safety colors

Promotion is manual: a community chore starts red; a maintainer can move it to yellow or green after review. An assistant-written chore stays red until the user saves it with /keep, and even then stays red.

3. Rules the engine enforces before running

1. Header complete and valid. Missing field → chore skipped and logged.
2. Dry-run supported: the engine runs every chore once with AROMBA_DRY_RUN=1 before its first real run and shows the user the result.
3. Idempotent: running twice in a row changes nothing the second time.
4. One result line minimum in AROMBA_RESULT, one human line in AROMBA_RECEIPT. Silent chores are reported as “ran, said nothing”.
5. Fails loudly: non-zero exit on unexpected state. Engine reports the failure in the receipt, retries once next night, then disables the chore and tells the user.
6. Time cap: timeout, default 10 minutes.
7. Load guard: scheduled chores don’t start if the 5-minute load average is above the core count, and pause if it goes over during the run. Event chores ignore the guard, and so do the watchers: one on often (PLAN D122), and one that only reads — green, verb: watch, no path in touches, the test prod mode uses (PLAN D206) — whatever its trigger. The load watcher is hourly, and a guard that held it stopped the one chore that reports high load (PLAN D208). The calendar’s hold (PLAN D107) lets the same watchers through.
8. needs present, os matches, color rules respected. Red chores never run without a fresh approval (valid for one run, expires after 24 h). Approval message shows the exact params.
9. Chaining depth: after: chains stop at 5 links. A chore can’t trigger itself.
10. systemd and apt are never reached from inside the cage: their sockets live under /run, which the cage hides (05 §3). A chore asks (the asks header) and, after a clean real run, may write do=<command> result lines for the few commands the Warden runs on its behalf outside the cage, each judged on its own and each a receipt line: systemctl restart <unit>, timedatectl set-ntp true, apt-get install …, docker image prune -f and docker builder prune -f (PLAN D230). A red chore may ask for any of them — its approval is the button 05 §5 gives such commands; a green chore only for time sync’s two. Nothing runs after a dry run or a failed run. The plain files /run/reboot-required and /run/reboot-required.pkgs are visible inside the cage.

4. Watchers

A watcher is a chore with verb: watch, usually trigger: hourly — often for the few that must notice within minutes. Its two first dry runs must both succeed, but they need not print the same thing: a watcher measures, and a measurement differs (PLAN D124; the pair’s agreement rule is for chores that change something). A question in asks: may name one of the chore’s own params as <name> — docker logs --tail 200 <container> — and the Warden fills it from the run’s values before it checks the command against its list, so what the policy sees is what will run; a param left empty leaves that question unasked and its answer file empty (PLAN D120). A watcher is given its own last result as PREV_* (PLAN D117): half of what one is asked to notice is a change — two failures in a row, an error rate against the hour before, a feed that stopped moving — and a chore has no memory of its own between runs. It writes alert=<text> when something is wrong and event=<name> to fire an event, nothing otherwise. Beside an alert it may also say what it measured — value=<number>, line=<the number it compared against> and metric=<a health metric's name, e.g. disk_pct> — and when it does, the alert is weighed before it is sent: how far past its own line, and how far from normal for this server, decide whether the phone rings, whether the message waits quietly in the chat, or whether it is one line in the receipt (03 §6, PLAN D115). A watcher that says none of them is weighed on its history alone. The engine sends an alert at most once per 24 h per watcher unless the value gets worse. Watchers never fix anything. In phase 3 an alert can be handed to the assistant, which is what makes the AI cheap: it only wakes up when a watcher says so.

5. run chores — the cron replacement

A run chore wraps any user job: a backup script, a scraper, a build, a report generator. What Aromba adds over cron: dry-run, timeout, load guard, receipt line, failure retry and alert, and the assistant can look at a failure. Always red on first run; the user can lower it to green for their own scripts with /chores → “trust this”. Trust is for the script as it is and the values it runs with — a run chore’s command and folder are its params — so a changed file or a changed value asks again; once trusted, it runs on its schedule like a green chore, outside the first week and prod mode.

# ---
# name: Nightly scraper
# verb: run
# os: linux
# safety: red
# touches: runs /home/james/scraper/run.sh
# needs: bash
# trigger: night
# params: cmd=/home/james/scraper/run.sh
# default: off
# author: mine
# ---

6. Catalog

Phase 2 ships the chores marked ★: the system skill in full (OS level only, 13-skills.md) and the minimum of each phase-2 skill; the skill in parentheses owns the chore, no parentheses means system. Everything else is the target catalog for phases 2–4, in rough priority order inside each verb. Skills for other audiences are not listed here; they arrive through the skill catalog (see 06-architecture.md).

sweep — clean regenerable or stale things

fix — keep the system healthy

prepare — have things ready before you sit down

guard — backups and safety copies

watch — look and alert, never touch

report — write things down

run — your own jobs, supervised

7. Folder layout

/opt/aromba/chores/
  core/         the `system` skill's chores, shipped with the binary, updated with it
  community/    installed with `aromba chore add <url>`
  mine/         written by the user or the assistant, never overwritten by updates

Same file name in mine/ overrides core/. Skills install into /opt/aromba/skills/<name>/chores/ with the same format.