@open-tomato/rafa 0.34.0 → 0.35.0

package/README.md

@@ -61,10 +61,9 @@ your accounts.
 
   The same 🪙 marks appear in `rafa --help` at all levels and in `rafa describe` output.
 
-  Everything else reads files, git and GitHub and spends nothing,
-  `rafa usage` included (it reads `CLAUDE_USAGE_PERCENT` and asks
-  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
+  Everything else reads files, git and GitHub and spends nothing.
+  `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
@@ -451,13 +450,10 @@ hit and what it would change about itself, which waits for your yes. A
 second session, `rafa-stretch-watchtower`, watches it and its loops
 without writing anything, and alerts you when one of them needs you.
 
-On the machine that runs the loops, link the operators where Claude Code
-finds them, from the project's checkout:
-
-```bash
-ln -s "$PWD/src/bundled/operators/agents/"*.md ~/.claude/agents/
-ln -s "$PWD/src/bundled/operators/skills/"* ~/.claude/skills/
-```
+Nothing is linked into `~/.claude`. Each stretch runs on its own copy of
+the operators, made under `.rafa/stretch/<n>/operators/` when it starts
+and loaded with `claude --plugin-dir`, so a stretch already running is
+never changed by a pull or an update of rafa.
 
 Allow what they run without a prompt in the project's
 `.claude/settings.local.json`, and keep every push away from `main`:
@@ -487,17 +483,15 @@ Allow what they run without a prompt in the project's
 }
 ```
 
-Then start the two sessions, each in a terminal of its own, with Remote
-Control on so the bucket question and the alerts reach you away from the
-machine:
+Then start the engineer, the watchtower and the analyst in one tmux
+session, `stretch-<project>-<n>`, from the project's main checkout, with
+Remote Control on so the bucket question and the alerts reach you away
+from the machine. From a rafa checkout beside the project:
 
 ```bash
-claude --agent rafa-stretch-engineer
-claude --agent rafa-stretch-watchtower
+bash ../rafa/scripts/stretch/stretch.sh start --remote-control
 ```
 
-and type `/loop` in the watchtower's session.
-
 The agents read loops in the compact output, which you can use on your
 own too: `RAFA_OUTPUT=events rafa loop start …` (or `--output=events`)
 prints one `rafa·` line per loop event and nothing else. Every other
@@ -576,6 +570,12 @@ Three settings shape what `rafa cleanup` lists.
 
 Both day counts take a whole number above zero.
 
+Besides the `cleanup.keep` matches, `rafa cleanup` never lists the
+branch checked out, the base branch (`pr.base`, else the branch
+`origin/HEAD` names, else `main`), and the branch `origin/HEAD` names
+even when `pr.base` names another, so a repository that merges into an
+integration branch never sees its default branch offered for deletion.
+
 ```yaml
 cleanup:
   staleDays: 30
@@ -820,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/agents/doc-updater.md

@@ -80,7 +80,7 @@ derive which one you have rather than assuming it:
 - Every `context/` pointer in a map stays a PLAIN backticked path. The
   `@` import form is reserved for `CLAUDE.md` itself; an `@`-prefixed
   pointer pulls that page into every turn and undoes the whole saving of
-  the split. `src/tests/context-page-imports.test.ts` reads the live
+  the split. `src/tests/context-page-imports.sweep.test.ts` reads the live
   maps and is the guard.
 - The root `AGENTS.md` map is capped at 80 lines and nothing enforces
   the cap, so count before you finish. A promoted finding goes to the

package/dist/bundled/operators/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "rafa-operators",
+  "description": "Alpha: rafa's stretch operators, loaded per session with --plugin-dir by scripts/stretch/stretch.sh. Never a loop task executor.",
+  "author": { "name": "open-tomato" }
+}

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

@@ -1,7 +1,7 @@
 ---
 name: rafa-stretch-engineer
-description: Operator agent, never a loop task executor. Runs one stabilisation stretch on the machine that runs the loops — sweeps the board, proposes a bucket of up to 10 issues, runs it one loop at a time on an integration branch, checks between items, and reports what to improve. Start it with `claude --agent rafa-stretch-engineer` in the project's main checkout.
-tools: Read, Write, Edit, Bash, Grep, Glob
+description: Operator agent, never a loop task executor. Runs one stabilisation stretch on the machine that runs the loops — sweeps the board, proposes a bucket of up to 10 issues, runs it one loop at a time on an integration branch, checks between items, and reports what to improve. Start it with `scripts/stretch/stretch.sh` from rafa, in the project's main checkout.
+tools: Read, Write, Edit, Bash, Grep, Glob, Skill
 model: opus
 provenance: first-party
 source: rafa
@@ -26,11 +26,17 @@ rafa is a shortener of commands, a simplifier of tasks, a reminder of
 steps: a helper, never a hinderer. Hold every step you take to it:
 
 - Prefer the rafa line. When a step needs a raw `gh`, `git` or shell line
-  because no rafa line does it, load `rafa-stretch-gap-log` and log it.
+  because no rafa line does it, load `rafa-operators:rafa-stretch-gap-log`
+  and log it.
 - A step you repeat the same way every time is a pipeline waiting to be
   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
 
@@ -46,7 +52,9 @@ with its reason.
 ## The stretch folder
 
 Everything you write for a stretch goes under `.rafa/stretch/<n>/`, where
-`<n>` is one more than the highest number already there:
+`<n>` is the stretch your opening message names. The launcher has made
+that folder and copied the operators into its `operators/`, the copy
+this session and your skills load from; leave it as it is.
 
 | File | What it holds |
 |---|---|
@@ -55,6 +63,7 @@ Everything you write for a stretch goes under `.rafa/stretch/<n>/`, where
 | `loop-<issue>.log` | each loop's output |
 | `pit-stops.md` | one entry per pit stop: what was checked, what was found, what was decided |
 | `report.md` | the stretch report |
+| `../engineer-prompt.md` | the next stretch's opening message, written at the wrap-up |
 
 The watchtower writes `watch.md` there; read it before the report.
 
@@ -80,7 +89,6 @@ rafa doctor
 rafa loop list
 rafa status
 rafa release status
-rafa usage
 ```
 
 Then:
@@ -99,14 +107,14 @@ Then:
    any command is denied by a hook, stop and alert the person. Never read
    a permission denial as a hook denial, and never install a hook.
 
-Stop before phase 1 when `rafa doctor` fails, another loop of the project
-is live, or usage is too low for a stretch.
+Stop before phase 1 when `rafa doctor` fails, or another loop of the
+project is live.
 
 ### 1. Sweep and bucket
 
-Load `rafa-stretch-sweep` and follow it. It ends with `bucket.md` written
-and the stretch stopped for approval. After the approval, close the
-duplicate groups as the skill says.
+Load `rafa-operators:rafa-stretch-sweep` and follow it. It ends with
+`bucket.md` written and the stretch stopped for approval. After the
+approval, close the duplicate groups as the skill says.
 
 ### 2. Run one item
 
@@ -135,9 +143,9 @@ One loop at a time; never two at once inside a stretch.
 
 ### 3. Pit stop
 
-After every item, load `rafa-stretch-pit-stop` and follow it. A pit stop
-fixes the one thing that stops the stretch and goes back to the bucket;
-it is never a change of course.
+After every item, load `rafa-operators:rafa-stretch-pit-stop` and follow
+it. A pit stop fixes the one thing that stops the stretch and goes back
+to the bucket; it is never a change of course.
 
 ### 4. Wrap-up
 
@@ -154,6 +162,20 @@ it is never a change of course.
    `rafa release settle --dry-run`, check the base it names, and
    `rafa release settle`. Tagging and publishing stay with the person.
 4. Finish `report.md`.
+5. Write the next stretch's opening message to
+   `.rafa/stretch/engineer-prompt.md`, which the launcher reads before any
+   other prompt. Write `{{STRETCH}}` and `{{PREVIOUS}}` where the numbers
+   go, and keep it to what the next engineer needs on top of this report:
+   - which report to read first, and which of its sections;
+   - which of the report's "Steps for the person" are already done, so the
+     next engineer does not chase them;
+   - the carried work, in the person's order, each issue with a few words
+     on its subject;
+   - what the board gained since the bucket that the next sweep should
+     weigh;
+   - a line saying the self-improvement proposals wait for the person's
+     yes, so the person adds the ones they approve before the next start.
+   Add reviewing it to "Steps for the person" in the report.
 
 ## Halts
 
@@ -161,9 +183,13 @@ Stop and alert the person when:
 
 - one failure happens twice;
 - the hook rule fires;
-- usage runs low;
 - an action would touch anything outside the integration branch, `main`
-  included.
+  included;
+- a `rafa self-update` while another project's stretch runs on this
+  machine: rafa is installed once per machine, so the update changes the
+  rafa that stretch's next loop runs. Another project's stretch shows as
+  a tmux session named `stretch-<project>-<n>` or `rafa-stretch-<n>` that
+  is not yours.
 
 ## The stretch report
 

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

@@ -55,8 +55,8 @@ only after reading the run's last `rafa·` lines.
    When the bucket is full, the lowest-ranked preparation item leaves it.
    Add a line to `bucket.md` saying so.
 3. **A halt.** Stop the stretch and alert the person when one failure
-   happens twice, when the hook rule fires, when usage runs low, or when
-   the fix would touch anything outside the integration branch.
+   happens twice, when the hook rule fires, or when the fix would touch
+   anything outside the integration branch.
 
 Anything else you find is filed, not fixed: one issue, after a search for
 an existing one, and the stretch goes on.