From 57c854edafdfa5490828c93008b6182742211a14 Mon Sep 17 00:00:00 2001 From: Chris Geyer Date: Thu, 16 Apr 2026 19:03:44 +0000 Subject: [PATCH] docs(skill): document clean-git requirement and /tmp filter gotchas MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two gotchas discovered while exercising `roar run` end-to-end: 1. `roar run` refuses to execute with any uncommitted git changes (including untracked files) and has no `--dirty` bypass. Agents hitting this need to commit, stash, or gitignore first — and especially need to make sure `.roar/` is in `.gitignore` before the first run, or it becomes an untracked change that blocks subsequent runs. 2. The default `config.toml` sets `ignore_tmp_files = true`, which silently drops any I/O under `/tmp`. A run in a /tmp workdir produces no Inputs/Outputs and `in:0 out:0` in `roar dag`, with no indication the filter is responsible. Added both to the Claude skill's Gotchas section and a condensed version to the cross-agent AGENTS.md snippet. Co-Authored-By: Claude Opus 4.6 (1M context) --- roar/cli/templates/agents/SKILL.md.tmpl | 3 +++ roar/cli/templates/agents/agents_section.md.tmpl | 2 ++ 2 files changed, 5 insertions(+) diff --git a/roar/cli/templates/agents/SKILL.md.tmpl b/roar/cli/templates/agents/SKILL.md.tmpl index 5301200..483247e 100644 --- a/roar/cli/templates/agents/SKILL.md.tmpl +++ b/roar/cli/templates/agents/SKILL.md.tmpl @@ -80,6 +80,9 @@ Workloads should NOT need to know which backend is active. ## Gotchas +- **Clean git state is required.** `roar run` refuses to execute if the git working tree has uncommitted changes — including untracked files. There's no `--dirty` bypass; commit (or stash, or gitignore) first. Lineage ties to a commit, so this is by design. +- **Add `.roar/` to `.gitignore` before your first run.** Otherwise it becomes an untracked change that trips the clean-tree check above on the next run. `roar init` prompts to add it; say yes. If you run `roar init -n` (skip) you'll need to add it yourself. +- **Default config filters `/tmp`.** `ignore_tmp_files = true` in the generated `config.toml` silently drops any I/O under `/tmp`. If a run shows `in:0 out:0` or a missing `Inputs/Outputs` section and you're working under `/tmp`, that's why — move the workdir or edit `.roar/config.toml` to flip the filter. Other default filters hide system reads (`/sys`, `/etc`) and installed-package reads. - **Ray workers**: `ROAR_WRAP=1` is set on the driver but NOT on Ray workers. `ROAR_SESSION_ID` and `ROAR_JOB_ID` are propagated. Use those if a worker needs to detect provenance context. - **Osmo workers**: no env var propagation today. - **Don't make user code import roar** for tracking purposes — capture is transparent. The only exception is `from roar import require` for the abort-if-not-tracked guard. diff --git a/roar/cli/templates/agents/agents_section.md.tmpl b/roar/cli/templates/agents/agents_section.md.tmpl index c909462..e83c9d8 100644 --- a/roar/cli/templates/agents/agents_section.md.tmpl +++ b/roar/cli/templates/agents/agents_section.md.tmpl @@ -4,6 +4,8 @@ This project uses [roar](https://github.com/treqs/roar) to capture lineage for M - **Run scripts with provenance:** prefer `roar run ` over bare `` (e.g. `roar run python train.py`). - **Don't modify code to use roar.** Capture is transparent. The exception: `from roar import require` at the top of a script aborts if it isn't being run under `roar run`. +- **Clean git state is required.** `roar run` refuses to execute with uncommitted changes (including untracked files). No `--dirty` bypass. Make sure `.roar/` is in `.gitignore`. +- **Avoid `/tmp` for workdirs.** Default config has `ignore_tmp_files = true`, which silently drops I/O under `/tmp` — a run there will show `in:0 out:0`. - **Inspect lineage:** `roar show `, `roar log`, `roar dag`. Add `--all` to `roar show` to disable truncation. - **Don't commit `.roar/`** — it's local lineage state. - **`roar --help` is the source of truth** for current command behavior.