@open-tomato/rafa 0.34.1 → 0.36.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

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-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,7 +26,8 @@ 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.
@@ -51,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 |
 |---|---|
@@ -60,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.
 
@@ -85,7 +89,6 @@ rafa doctor
 rafa loop list
 rafa status
 rafa release status
-rafa usage
 ```
 
 Then:
@@ -104,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
 
@@ -127,10 +130,10 @@ 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. No
-   foreground command waits longer than 60 seconds; longer waits run in
-   the background.
+3. Watch it: `rafa loop wait --until=pr,no-pr,halt,error,exit` reads the
+   `.rafa/runs/<session-id>.events.ndjson` file your loop wrote, not the
+   log. 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.
@@ -140,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
 
@@ -159,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
 
@@ -166,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/agents/rafa-stretch-watchtower.md

@@ -55,17 +55,17 @@ Four sources, all on this machine:
 
 ## How you wait
 
-- **A Monitor on the loop log**, so each `rafa·` line, a `blocked` line, an
-  `error` line or a `halt` line reaches you as it is written. Match every
-  ending, not only the good ones:
+Watch the running loop's events from `.rafa/runs/<session-id>.events.ndjson`:
 
-  ```bash
-  tail -F .rafa/stretch/<n>/loop-<issue>.log | grep --line-buffered -E 'rafa· (task|wrap-up|pr|no pr|halt|error)'
-  ```
+```bash
+rafa loop wait --until=blocked,quiet:<minutes>,exit
+```
 
-  A Monitor stops after 30 minutes at most; restart it at every wake.
-- **`/loop`**, self-paced, every 10 to 30 minutes, for the slower checks:
-  the agent's status and the quiet-loop timing.
+The `<minutes>` is 2× the p90 task time from `rafa effort dashboard`. With
+no baseline yet, use 30 minutes and say so in the alert. The wait exits
+when a task blocks, when the loop is quiet for that long, or when the loop
+ends. Between waits, read the agent's session status and check the hook
+rule at every wake: `/loop`, self-paced, every 10 to 30 minutes.
 
 ## How you alert
 

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.