@open-tomato/rafa 0.33.0 → 0.34.1

package/README.md

@@ -66,6 +66,27 @@ your accounts.
   nobody). `rafa loop resume` starts no session itself, but it lets a
   paused run go on spending. rafa calls no model API directly: all of
   it goes through the `claude` command.
+- **Your machine may go to sleep in the middle of a run.** rafa does not
+  keep it awake, so the operating system's power settings can suspend a
+  loop mid-task. The task carries on when the machine wakes, if its
+  session survived, and its recorded time includes the time asleep, which
+  then reads as an outlier in `rafa effort report --trend`. On a machine
+  you leave running loops, turn sleep off in its power settings, or run
+  the loop under the operating system's own sleep lock, which lasts as
+  long as the command it wraps:
+
+  ```bash
+  systemd-inhibit --what=sleep:idle --why="rafa loop" rafa loop start --plan=<plan>
+  ```
+
+  ```bash
+  caffeinate -i rafa loop start --plan=<plan>
+  ```
+
+  The first is Linux's, the second macOS's. **On a managed device, check
+  its power policy before you do either:** some organisations report, or
+  block, software that keeps a device awake. An opt-in `--keep-awake`
+  flag is planned (#641).
 - So run it in a repository, on a branch and on a machine where all of
   that is acceptable: a container or a disposable checkout is a good
   first home. Nothing here is a sandbox.
@@ -497,6 +518,10 @@ project's file outranks the same one in yours. `rafa init` writes both
 with every setting commented out at its default, so uncomment a line,
 with its section line, to change it.
 
+Tab indentation in `.rafa/config.yaml` is refused with rafa's own error
+on every Bun version, before the parser sees the file. The error names
+the line that carries a tab; use spaces only.
+
 ### `effort`
 
 One setting says how long a command waits for another rafa process that
@@ -795,6 +820,20 @@ is the old one removed, so no reader meets a half-replaced runtime. The
 link lands by a rename too, so a shell meets the old link or the new one
 and never none.
 
+## Bringing a project up to the installed rafa
+
+`rafa self-update` moves the rafa every project on the device runs, and
+leaves what each project holds as it was set up. `rafa update current`,
+run inside a project, brings that project to the installed rafa: it
+creates the `.rafa/` folders and the board labels newer versions expect,
+and records the version in `rafa.lock` at the repository root, a small
+JSON file meant to be committed. It works within a patch range: the
+installed version must share the major and minor of the one the lock
+records, and a project with no lock is adopted. It prints every change
+first, and `--dry-run` stops there; otherwise it asks once, or takes
+`--yes`. The rest of `rafa update` (`self`, `project`, `board`, `next`,
+`latest`) is in development and says so (#713).
+
 ## Runtime
 
 The build targets bun, and `engines` names `bun` alone: there is no

package/dist/bundled/operators/agents/rafa-stretch-analyst.md

@@ -0,0 +1,53 @@
+---
+name: rafa-stretch-analyst
+description: Operator agent, never a loop task executor. Read-only. Turns a stretch's raw data (run records, loop logs, effort store, kernel log, board) into checked insights. Takes the person's hunch, tests it against the data, and names the alternative explanation and the check that separates them. Also called da2 or da². Start it with `bun run stretch analyst` in the project's main checkout, or as the third window of `bun run stretch start`.
+tools: Read, Bash
+provenance: first-party
+source: rafa
+stage: alpha
+---
+
+Alpha: tested on rafa's own development, may become a feature.
+
+## Mission
+
+The person works on hunches and curiosity. Your job is to say which hunch the
+data supports, which it does not, and which it cannot answer yet. Never
+change anything: no writes to the board, branches, config, or the stretch
+folder except `analysis.md`.
+
+## Vision
+
+A finding is only as good as its input. Before any number, check the input:
+
+- time that is not work (machine asleep, waiting on the person, a paused loop);
+- units that do not compare (tokens with input against output-only tokens);
+- small samples (a p90 over 7 tasks is one task);
+- a cause counted twice (one failure filed as several bugs);
+- the loudest signal that is not the costliest one.
+
+## Sources
+
+| Source | What it holds | How to read it |
+|---|---|---|
+| `.rafa/runs/<id>.json` | test steps: kind, scope, failures, `[Ns]` duration | `python3`/`jq` over `steps` |
+| `.rafa/stretch/<n>/loop-*.log` | `rafa·` lines: task done minutes and tokens | grep the `done` lines |
+| `.rafa/effort/effort.sqlite` | sessions, task reports, dispatches | `sqlite3 -readonly` |
+| `journalctl -k` (`pmset -g log` on macOS) | suspend and resume times | subtract from wall time |
+| `gh issue list --search created:>=…` | filings per loop | group by cause |
+| `bucket.md`, `pit-stops.md`, `watch.md` | plan, decisions, what was seen | timestamps of each change |
+
+## Method, for each question
+
+1. Restate the hunch as a claim that can be false.
+2. Measure it: the number, its source, and the command that produced it.
+3. Name at least one other mechanism that fits the same numbers, and the
+   check that tells them apart. Run the check if the data allows it.
+4. Verdict: supported, not supported, or open (with what data would close it).
+
+## Report
+
+Write to `.rafa/stretch/<n>/analysis.md` and answer the person in the same
+shape: one line per finding as claim → measurement → source → verdict. Put
+the one finding that changes a decision first. Leave out findings that
+change nothing.

package/dist/bundled/operators/agents/rafa-stretch-engineer.md

@@ -31,6 +31,11 @@ steps: a helper, never a hinderer. Hold every step you take to it:
   written; a flag you always add is a flag rafa may not need. Note both
   in the report.
 - Stop and ask only where there is a risk. Everything else is yours.
+- Move an issue between epics with `rafa epic move <issue> --to=<epic>`,
+  never by adding a second `epic:` label: where the project installs the
+  epic guard, a second label added beside the first is removed, and its
+  comment lands on the issue. Turning the guard on or off is the
+  person's, never yours.
 
 ## Two stops, everything else unattended
 
@@ -123,10 +128,14 @@ One loop at a time; never two at once inside a stretch.
    `setsid` is Linux's; on macOS start it with `nohup` alone and log the
    difference as a gap. Detached loops are a gap of their own.
 3. Watch it: read the log's `rafa·` lines and `rafa loop status`. Wait
-   with a background check on the log, never a tight loop of reads.
-4. Merge its pull request into the integration branch:
-   `rafa pr merge <pr> --skip-checks` when the repository reports no
-   checks; `rafa pr wait <pr>` then `rafa pr merge <pr>` when it does.
+   with a background check on the log, never a tight loop of reads. No
+   foreground command waits longer than 60 seconds; longer waits run in
+   the background.
+4. Merge its pull request:
+   - Into `stretch/<n>`: `rafa pr merge <pr> --skip-checks`. The merge push
+     runs `verify` asynchronously; read the result at the pit stop.
+   - Into `main`: `rafa pr wait <pr>` then `rafa pr merge <pr>` once
+     the checks pass.
 5. Clean up: `rafa cleanup`.
 
 ### 3. Pit stop
@@ -144,7 +153,8 @@ it is never a change of course.
    gh pr create --base main --head stretch/<n> --title "Stretch <n>" --body-file .rafa/stretch/<n>/report.md
    ```
 
-2. Stop for the person's merge.
+2. Merge the stretch's pull request into `main` once `verify` is green on
+   it: `rafa pr wait <pr>` then `rafa pr merge <pr>`.
 3. After it, point `pr.base` back at `main`, then
    `rafa release settle --dry-run`, check the base it names, and
    `rafa release settle`. Tagging and publishing stay with the person.

package/dist/bundled/operators/skills/rafa-stretch-pit-stop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rafa-stretch-pit-stop
-description: "Use after each stretch item: check effort, bugs, delivery and conflicts, then go on, insert one fix, or halt."
+description: "Use after each stretch item: check effort, bugs, delivery, conflicts and CI, then go on, insert one fix, or halt."
 provenance: first-party
 source: rafa
 stage: alpha
@@ -23,7 +23,7 @@ A pit stop is the check between two items. It fixes the one thing that
 would stop the next item, then rejoins the bucket: it is never a change
 of course, and never a reason to chase one issue down a rabbit hole.
 
-## The four checks
+## The five checks
 
 | Check | Line | What is wrong |
 |---|---|---|
@@ -31,6 +31,11 @@ of course, and never a reason to chase one issue down a rabbit hole.
 | Bugs | `rafa issue list --type=bug --limit=200` | the open count rising, or bugs filed during this loop that repeat an open one |
 | Delivery | `rafa loop status`, `rafa pr list` | the run is done with no pull request, or its pull request did not merge |
 | Conflicts | `rafa pr show <pr>` | the pull request conflicts with the integration branch |
+| CI | `gh run list --branch stretch/<n> --workflow verify.yml --limit 1` | the run failed (use `gh run view <id> --log-failed` to see why), or is still running |
+
+A CI failure already red in the local runs is inherited and noted in the pit-stop entry.
+A new failure is filed as one bug after a search for an existing one. A run still in progress
+is read at the next pit stop.
 
 A conflict goes to the resolve plans first:
 
@@ -67,5 +72,6 @@ Append one entry to `.rafa/stretch/<n>/pit-stops.md`:
 - Bugs: 61 open, 64 at the start; none filed during the loop.
 - Delivery: pull request #612 merged into stretch/3.
 - Conflicts: none.
+- CI: verify.yml passed.
 - Decision: next item, #486.
 ```

package/dist/bundled/skills/dev-planner/SKILL.md

@@ -28,7 +28,7 @@ This file is the single source of that format. `rafa plan` inlines it, without i
 | `<plan.dir>/PLAN-<stub>.md` | Full task checklist with structured blocks and technical context |
 | `<plan.dir>/PREREQUISITES-<stub>.md` | Non-automatable setup steps required before the plan can run (only when any exist) |
 
-`plan.dir` is `.rafa/plans` unless the project's `.rafa/config.yaml` names another directory. `rafa plan --spec=<spec>.md` generates both files (optionally `--stub=<name>`; the stub defaults to the spec's basename) and writes them into `plan.dir`, creating the directory when it is missing. It reads the spec from the project root, or from `specs.dir` (`.rafa/specs` by default) when the root holds no such file, and refuses to run when `<plan.dir>/PLAN-<stub>.md` already exists.
+`plan.dir` is `.rafa/plans` unless the project's `config.yaml` under `.rafa/` names another directory. `rafa plan --spec=<spec>.md` generates both files (optionally `--stub=<name>`; the stub defaults to the spec's basename) and writes them into `plan.dir`, creating the directory when it is missing. It reads the spec from the project root, or from `specs.dir` (`.rafa/specs` by default) when the root holds no such file, and refuses to run when `<plan.dir>/PLAN-<stub>.md` already exists.
 
 Execute a plan with `rafa start --plan=.rafa/plans/PLAN-<stub>.md`. With no `--plan`, `rafa start` runs `PLAN.md` in `plan.dir`, and falls back to a hand-written `PLAN.md` at the project root only when `plan.dir` holds no `PLAN.md`.
 
@@ -165,7 +165,7 @@ All rafa work follows a consistent naming scheme across specifications, plans, b
 
 | Artifact | Pattern | Example |
 | --- | --- | --- |
-| Specification file | `.rafa/specs/rafa-<n>-<slug>.md` | `.rafa/specs/rafa-20-pr-commands.md` |
+| Specification file | `.rafa/specs/rafa-<n>-<slug>.md` | `rafa-20-pr-commands.md`, under `.rafa/specs/` |
 | Plan stub and directory | `rafa-<n>-<slug>` | `rafa-20-pr-commands` |
 | `issue:` field in `rafa:plan` | `<n>` (number only) | `issue: 20` |
 | Git branch | `feat/rafa-<n>-<slug>` | `feat/rafa-20-pr-commands` |
@@ -449,7 +449,7 @@ The second example above has no `skills=` and is still a valid task declaration.
 
 ## Three task-context injection modes
 
-The loop supports three modes of injecting task context, configured at plan start via `--inject=` or in `.rafa/config.yaml`:
+The loop supports three modes of injecting task context, configured at plan start via `--inject=` or in the project's `config.yaml` under `.rafa/`:
 
 | Mode | Contents | Use case |
 | --- | --- | --- |

package/dist/bundled/skills/git-workflow/SKILL.md

@@ -38,7 +38,7 @@ For the rafa project specifically, issue numbers are prefixed with `rafa-` and
 reflected throughout the spec and branch workflow:
 
 - **Issue reference** (in prose): `#rafa-<n>` — e.g., `#rafa-20`
-- **Spec file**: `.rafa/specs/rafa-<n>-<slug>.md` — e.g., `.rafa/specs/rafa-20-pr-commands.md`
+- **Spec file**: `.rafa/specs/rafa-<n>-<slug>.md` — e.g., `rafa-20-pr-commands.md`, under `.rafa/specs/`
 - **Plan stub** (in prose): `rafa-<n>-<slug>` — e.g., `rafa-20-pr-commands`
 - **Branch name**: `feat/rafa-<n>-<slug>` — e.g., `feat/rafa-20-pr-commands`
 - **PR title**: `rafa-<n>: <title>` — e.g., `rafa-20: Add PR commands`