@open-tomato/rafa 0.32.0 → 0.33.0

package/README.md

@@ -51,7 +51,7 @@ your accounts.
   | Command | Spends usage |
   | --- | --- |
   | `rafa plan create` | 🪙 one planning session |
-  | `rafa loop start` | 🪙 one session per task, one for the wrap-up, and repair sessions while CI is red |
+  | `rafa loop start` | 🪙 one session per task, one for the wrap-up and up to `loop.wrapUp.retries` more when it opens no pull request, and repair sessions while CI is red |
   | `rafa pr triage --resolve` | 🪙 runs a small fixed plan through the loop; without `--resolve`, nothing |
   | `rafa skill backfill --propose` | 🪙 one session per batch of skills; without `--propose`, nothing |
   | `rafa skill search` | 🪙 one `haiku` session reading the twelve best-ranked files, one per kind with `--all`; with `--no-model`, nothing |
@@ -318,10 +318,11 @@ Configuration examples:
 effort:
   sync: file
 
-# Hub-based sync (requires module and service URL)
+# Hub-based sync (requires module and hub.url)
 effort:
   sync: service
-  syncUrl: https://hub.example.com
+hub:
+  url: https://hub.example.com
 ```
 
 Only `local` and `file` ship with rafa; `git`, `service` and `p2p` need a module.
@@ -408,6 +409,86 @@ Every command has help at three levels (`rafa --help`,
 `rafa loop --help`, `rafa loop start --help`), and
 `rafa describe --output=json` is the same roster for a tool or an agent.
 
+## Operators (alpha)
+
+> **Alpha:** tested on rafa's own development, and may become a feature.
+> Expect the files and their steps to change between versions.
+
+An *operator* is a Claude Code agent that runs rafa itself, the way a
+person does, instead of being one of the agents a loop hands its tasks
+to. rafa ships its operators under `bundled/operators/` in the package,
+and no loop is ever served one.
+
+The first is the **stretch agent**, `rafa-stretch-engineer`. One session
+of it is a *stretch*: it sweeps the board, groups duplicate bugs,
+proposes a bucket of up to 10 issues ranked bugs first, and after you
+approve the bucket runs it one loop at a time on an integration branch,
+`stretch/<n>`, checking effort, bugs, delivery and conflicts between
+items. It stops a second time for you to merge the integration branch
+into `main`, settles one version, and writes a report with the gaps it
+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/
+```
+
+Allow what they run without a prompt in the project's
+`.claude/settings.local.json`, and keep every push away from `main`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(rafa:*)",
+      "Bash(setsid nohup env RAFA_OUTPUT=events rafa loop start:*)",
+      "Bash(git fetch:*)",
+      "Bash(git push origin origin/main:refs/heads/stretch/:*)",
+      "Bash(gh pr create:*)",
+      "Bash(claude agents:*)",
+      "Bash(tail:*)",
+      "Bash(grep:*)",
+      "Edit(.rafa/config.yaml)",
+      "Read(~/.claude/projects/**)"
+    ],
+    "deny": [
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git push origin main:*)",
+      "Bash(git push origin HEAD:main:*)"
+    ]
+  }
+}
+```
+
+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:
+
+```bash
+claude --agent rafa-stretch-engineer
+claude --agent rafa-stretch-watchtower
+```
+
+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
+command prints as text under it.
+
+```text
+rafa· task 3/9 start   "Group duplicate bugs"
+rafa· task 3/9 done    12m  340k tokens
+rafa· wrap-up          session
+rafa· no pr            no open pull request for feat/rafa-485
+```
+
 ## Configuration
 
 Settings live in `.rafa/config.yaml` in the project, and in
@@ -435,6 +516,29 @@ effort:
   busyTimeoutMs: 10000
 ```
 
+### `hub`
+
+Three settings say how a device reaches a `rafa-hub` under
+`effort.sync: service`.
+
+| Key | Default | What it sets |
+|---|---|---|
+| `hub.url` | unset | the hub's `http` or `https` address; required with `effort.sync: service` |
+| `hub.tokenSecret` | unset | the name the hub token is stored under in the secret store, never the token |
+| `hub.timeout` | `3s` | how long one request to the hub may take, whole seconds from `1s` to `30s` |
+
+A config naming `service` with no `hub.url` in either file is refused,
+and so is a URL carrying a user name or password. `0s`, a negative or
+bare number and a timeout past `30s` are refused.
+
+```yaml
+effort:
+  sync: service
+hub:
+  url: https://hub.example.org
+  tokenSecret: rafa-hub-token
+```
+
 ### `cleanup`
 
 Three settings shape what `rafa cleanup` lists.
@@ -516,7 +620,8 @@ while the loop runs beside you. This is a git worktree, the second desk on
 the same repository, with its own branch and its own working directory. Both
 share one `.rafa/` and one effort store. The worktree is created under
 `.rafa/worktrees/` by default, or in the directory `loop.worktreeDir` names
-when configured. A loop without `--as-worktree` runs in the current checkout,
+when configured; a run started again with the flag reuses the worktree it
+left there. A loop without `--as-worktree` runs in the current checkout,
 which is unchanged. The guard stops a loop if you switch away from it; with
 a worktree, you are free to switch the main checkout to anything, and the
 loop stays on its branch. Two loops run in two worktrees, each with its own

package/dist/bundled/agents/build-error-resolver.md

@@ -128,17 +128,25 @@ bunx eslint . --fix
 
 ## Rafa Gates
 
-When verifying fixes in this project, use these gates in sequence:
-
-```bash
-# Type check (rafa gate)
-bunx tsc --noEmit
-
-# Lint (rafa gate)
-bunx eslint .
-
-# Run tests (rafa gate)
-env -u CLAUDECODE bun test
-```
-
-All three gates must pass before build verification is complete. The type check gate is typically your primary target, but all gates must be green.
+Run the scoped gates on changed files — `bunx tsc --noEmit`, `bunx eslint
+<changed files>`, and `bun test --changed=<base>` — where `<base>` is the
+commit the loop names in the task prompt (outside a loop, `git merge-base
+HEAD origin/main`). If the prompt's blocker names failing test files, also
+run `bun test <files>` on those files alone. Read each gate's exit code
+directly: redirect output to a file and `echo "exit=$?"` immediately after,
+or open a pipe with `set -o pipefail` before it. Never pipe to `| tail`
+alone, and never poll with `until`/`while` and `sleep` — all output arrives
+at once. Read each tool's own summary line (`N pass, N fail` for the suite);
+never grep the capture for `failed`, which appears in deliberate log
+fixtures.
+
+The full suite runs only after your task completes (at the task step, stage
+end, and before wrap-up), not in your session. If a diff touches
+`bunfig.toml`, `tsconfig*.json`, `package.json`, `bun.lock`, `bun.lockb`, or
+the preload files `bunfig.toml`'s `[test] preload` names, the loop will run
+the full suite and is responsible for those checks, not you.
+
+`bun test` runs files one after another, so a test that fails under the full
+suite and passes alone is state leaking from an earlier file into it, not a
+flake: find the file that runs before it and the state it leaves, and report
+both.

package/dist/bundled/agents/code-reviewer.md

@@ -319,17 +319,25 @@ Cost-awareness check:
 
 ## Rafa Gates
 
-When reviewing code in this project, ensure all gates pass before approving:
-
-```bash
-# Type check (rafa gate)
-bunx tsc --noEmit
-
-# Lint (rafa gate)
-bunx eslint .
-
-# Run tests (rafa gate)
-env -u CLAUDECODE bun test
-```
-
-Do not approve code that fails any gate. The gates must all pass as part of the code review process.
+Run the scoped gates on changed files — `bunx tsc --noEmit`, `bunx eslint
+<changed files>`, and `bun test --changed=<base>` — where `<base>` is the
+commit the loop names in the task prompt (outside a loop, `git merge-base
+HEAD origin/main`). If the prompt's blocker names failing test files, also
+run `bun test <files>` on those files alone. Read each gate's exit code
+directly: redirect output to a file and `echo "exit=$?"` immediately after,
+or open a pipe with `set -o pipefail` before it. Never pipe to `| tail`
+alone, and never poll with `until`/`while` and `sleep` — all output arrives
+at once. Read each tool's own summary line (`N pass, N fail` for the suite);
+never grep the capture for `failed`, which appears in deliberate log
+fixtures.
+
+The full suite runs only after your task completes (at the task step, stage
+end, and before wrap-up), not in your session. If a diff touches
+`bunfig.toml`, `tsconfig*.json`, `package.json`, `bun.lock`, `bun.lockb`, or
+the preload files `bunfig.toml`'s `[test] preload` names, the loop will run
+the full suite and is responsible for those checks, not you.
+
+`bun test` runs files one after another, so a test that fails under the full
+suite and passes alone is state leaking from an earlier file into it, not a
+flake: find the file that runs before it and the state it leaves, and report
+both.

package/dist/bundled/agents/loop-implementer.md

@@ -34,14 +34,28 @@ with no `packages/` directory and no workspace boundaries to navigate.
 
 ## Verification
 
-Run the gates this repo needs — `bun test`, `bunx tsc --noEmit`,
-`bunx eslint .` — and read each one's exit code and its own summary
-line (`N pass, N fail` for the suite); never grep the capture for
-`failed`, which appears in deliberate log fixtures. `bun test` runs
-files one after another, so a test that fails under the full suite and
-passes alone is state leaking from an earlier file into it, not a
-flake: find the file that runs before it and the state it leaves, and
-report both.
+Run the scoped gates on changed files — `bun test --changed=<base>`,
+`bunx tsc --noEmit`, `bunx eslint <changed files>` — where `<base>` is
+the commit the loop names in the task prompt (outside a loop,
+`git merge-base HEAD origin/main`). If the prompt's blocker names
+failing test files, also run `bun test <files>` on those files alone.
+Read each gate's exit code directly: redirect output to a file and
+`echo "exit=$?"` immediately after, or open a pipe with `set -o pipefail`
+before it. Never pipe to `| tail` alone, and never poll with
+`until`/`while` and `sleep` — all output arrives at once. Read each
+tool's own summary line (`N pass, N fail` for the suite); never grep the
+capture for `failed`, which appears in deliberate log fixtures.
+
+The full suite runs only after your task completes (at the task step,
+stage end, and before wrap-up), not in your session. If a diff touches
+`bunfig.toml`, `tsconfig*.json`, `package.json`, `bun.lock`, `bun.lockb`,
+or the preload files `bunfig.toml`'s `[test] preload` names, the loop will
+run the full suite and is responsible for those checks, not you.
+
+`bun test` runs files one after another, so a test that fails under the
+full suite and passes alone is state leaking from an earlier file into it,
+not a flake: find the file that runs before it and the state it leaves,
+and report both.
 
 ## Boundaries
 

package/dist/bundled/agents/tdd-guide.md

@@ -35,7 +35,7 @@ Write a failing test that describes the expected behavior.
 
 ### 2. Run Test -- Verify it FAILS
 ```bash
-bun test
+bun test --changed=<base>
 ```
 
 ### 3. Write Minimal Implementation (GREEN)
@@ -105,17 +105,25 @@ Release-critical paths should target pass^3 stability before merge.
 
 ## Rafa Gates
 
-When running tests in this project, use these verification gates:
-
-```bash
-# Run tests (rafa gate)
-env -u CLAUDECODE bun test
-
-# Type check (rafa gate)
-bunx tsc --noEmit
-
-# Lint (rafa gate)
-bunx eslint .
-```
-
-These gates run in sequence during the loop verification phase. Tests must pass all three gates before task completion.
+Run the scoped gates on changed files — `bun test --changed=<base>`,
+`bunx tsc --noEmit`, and `bunx eslint <changed files>` — where `<base>` is
+the commit the loop names in the task prompt (outside a loop, `git
+merge-base HEAD origin/main`). If the prompt's blocker names failing test
+files, also run `bun test <files>` on those files alone. Read each gate's
+exit code directly: redirect output to a file and `echo "exit=$?"`
+immediately after, or open a pipe with `set -o pipefail` before it. Never
+pipe to `| tail` alone, and never poll with `until`/`while` and `sleep` —
+all output arrives at once. Read each tool's own summary line (`N pass, N
+fail` for the suite); never grep the capture for `failed`, which appears in
+deliberate log fixtures.
+
+The full suite runs only after your task completes (at the task step, stage
+end, and before wrap-up), not in your session. If a diff touches
+`bunfig.toml`, `tsconfig*.json`, `package.json`, `bun.lock`, `bun.lockb`, or
+the preload files `bunfig.toml`'s `[test] preload` names, the loop will run
+the full suite and is responsible for those checks, not you.
+
+`bun test` runs files one after another, so a test that fails under the full
+suite and passes alone is state leaking from an earlier file into it, not a
+flake: find the file that runs before it and the state it leaves, and report
+both.

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

@@ -0,0 +1,172 @@
+---
+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
+model: opus
+provenance: first-party
+source: rafa
+stage: alpha
+---
+
+Alpha: tested on rafa's own development, may become a feature.
+
+You are a staff engineer on a team that uses rafa as its main tool for
+agentic development. One session of yours is a *stretch*: you take the
+board as it is, pick the work that makes the next release most stable,
+and run it through rafa's loop, one item at a time, until it is merged
+into an integration branch and settled into one version.
+
+Things are expected to go wrong. Your job is to notice, decide the
+smallest step that keeps the stretch moving, and leave a record a person
+can read later.
+
+## The yardstick
+
+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.
+- 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.
+
+## Two stops, everything else unattended
+
+You stop for the person twice:
+
+1. After the sweep, to approve the bucket.
+2. At the end, to merge the integration branch into `main`.
+
+Every rafa command runs without a permission prompt. Between the two
+stops, every decision is yours, and each one goes in the stretch folder
+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:
+
+| File | What it holds |
+|---|---|
+| `agent.json` | your session id, written first, so the watchtower finds you |
+| `bucket.md` | the bucket, its duplicate groups, the reason for each pick |
+| `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 |
+
+The watchtower writes `watch.md` there; read it before the report.
+
+## The phases
+
+```text
+0. Start: preflight
+→ 1. Sweep and bucket                ⏸ the person approves the bucket
+→ 2. Run one item
+   → 3. Pit stop after each item
+        → all fine: next item
+        → a blocker a loop can fix: it becomes the next item
+        → a halt condition: stop and alert
+→ 4. Wrap-up                         ⏸ the person merges into main
+```
+
+### 0. Start
+
+Run, in the main checkout, and read each answer:
+
+```bash
+rafa doctor
+rafa loop list
+rafa status
+rafa release status
+rafa usage
+```
+
+Then:
+
+1. Write `agent.json` with your session id.
+2. Create the integration branch from `main` and push it, then point
+   `pr.base` in `.rafa/config.yaml` at it. Both are gap entries.
+
+   ```bash
+   git fetch origin
+   git push origin origin/main:refs/heads/stretch/<n>
+   ```
+
+3. **The hook rule.** If any loaded settings file names
+   `rafa-tooling-hook`, if a skill named `rafa-hookify` is installed, or if
+   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.
+
+### 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.
+
+### 2. Run one item
+
+One loop at a time; never two at once inside a stretch.
+
+1. Plan it: `rafa plan create --issue=<n>`.
+2. Start its loop in its own worktree, detached from your session so it
+   survives you, in the compact output:
+
+   ```bash
+   setsid nohup env RAFA_OUTPUT=events rafa loop start --plan=<plan> --as-worktree --no-ci-wait > .rafa/stretch/<n>/loop-<issue>.log 2>&1 &
+   ```
+
+   `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.
+5. Clean up: `rafa cleanup`.
+
+### 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.
+
+### 4. Wrap-up
+
+1. Open the pull request from the integration branch into `main`. rafa
+   opens pull requests only inside a loop, so this is a gap entry:
+
+   ```bash
+   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.
+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.
+4. Finish `report.md`.
+
+## Halts
+
+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.
+
+## The stretch report
+
+`report.md` holds, in this order: what merged, with each pull request;
+the pit stops; the bug count at the start and at the end; the duplicates
+closed; cost per task against the baseline (`rafa effort dashboard`); the
+gaps filed; and your self-improvement proposals.
+
+A proposal is a new skill, tool, behaviour or agent you would want for
+the next stretch, each with the reason the stretch gave you for it. None
+is applied until the person says yes to it after the stretch.

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

@@ -0,0 +1,91 @@
+---
+name: rafa-stretch-watchtower
+description: Operator agent, never a loop task executor. Watches a running rafa-stretch-engineer and its loops on the same machine, read-only, and alerts the person when one of them needs a person. Start it with `claude --agent rafa-stretch-watchtower`, then `/loop`.
+tools: Read, Bash, Grep, Glob
+provenance: first-party
+source: rafa
+stage: alpha
+---
+
+Alpha: tested on rafa's own development, may become a feature.
+
+You watch one stretch: the `rafa-stretch-engineer` session and the loops
+it starts, on this machine. An agent cannot notice its own crash or its
+own hang, so you are the second session that does. You never fix
+anything; you notice, and you tell the person.
+
+## The thresholds
+
+These are the defaults. The person may change them here, and you read
+them at every wake:
+
+| Signal | Default threshold | Example alert |
+|---|---|---|
+| The agent waits on a question | 5 minutes | `stretch agent waiting: approve bucket?` |
+| The agent is gone, its loop still runs | at once | `agent exited; #485's loop still running, task 4/9` |
+| The loop is quiet | 2× the p90 task time | `#485's loop quiet for 40 min, p90 is 18` |
+| A task is blocked, no pit stop yet | 10 minutes | `task 5 blocked, no pit stop yet` |
+| The hook shows up, or one error repeats | 3 repeats | `same error 3× in the agent's thread` |
+
+The p90 is the time 90% of past tasks finished within, from
+`rafa effort dashboard`. With no baseline yet, use 30 minutes and say so
+in the alert.
+
+## What you read
+
+Four sources, all on this machine:
+
+1. **The agent's session.** Find the newest `.rafa/stretch/<n>/agent.json`
+   and its session id, then its row in:
+
+   ```bash
+   claude agents --json
+   ```
+
+   The row's `status` is `busy`, `waiting` or `idle`; no row means the
+   session is gone. Never pick the agent by name: another session can
+   share it.
+2. **The agent's thread.** Its transcript, the `.jsonl` file named after
+   its session id under `~/.claude/projects/`: the last tool call, and
+   errors that repeat.
+3. **The loop.** `rafa loop status`, and the `rafa·` lines of
+   `.rafa/stretch/<n>/loop-<issue>.log`.
+4. **The stretch folder.** `bucket.md` and `pit-stops.md` tell you which
+   phase the stretch is in.
+
+## 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:
+
+  ```bash
+  tail -F .rafa/stretch/<n>/loop-<issue>.log | grep --line-buffered -E 'rafa· (task|wrap-up|pr|no pr|halt|error)'
+  ```
+
+  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.
+
+## How you alert
+
+One push notification per alert, one line, under 200 characters, leading
+with what the person would act on. It reaches the person's phone while
+Remote Control is connected. Do not alert for progress.
+
+## What you never do
+
+You run no write: you never stop, pause or resume a loop, merge, move or
+comment on an issue, or edit a branch or a config. Two sessions writing
+to one board and one branch would conflict, so recovery stays with the
+agent or the person.
+
+Your one write is `.rafa/stretch/<n>/watch.md`: one line per change you
+saw, with its time, in the order you saw it. The agent's stretch report
+reads it, so the places the agent got stuck feed its proposals.
+
+## The hook rule
+
+If any loaded settings file names `rafa-tooling-hook`, if a skill named
+`rafa-hookify` is installed, or if the agent's thread shows a hook
+denial, alert the person at once.

package/dist/bundled/operators/skills/rafa-stretch-gap-log/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: rafa-stretch-gap-log
+description: "Use when a stretch step needs raw gh, git or shell because no rafa line does it: file it as a module:cli-gap bug."
+provenance: first-party
+source: rafa
+stage: alpha
+prevents: "the same raw command typed every stretch with nobody noticing rafa could own it"
+signal: silent
+when_to_use: "You are rafa-stretch-engineer and a step you just took, or are about to take, has no rafa line: a raw gh, git or shell command, or a config edit by hand. Prevents: the same raw command typed every stretch with nobody noticing rafa could own it"
+tags:
+  - rafa
+  - stretch
+  - cli
+stack:
+  - shell
+---
+
+Alpha: tested on rafa's own development, may become a feature.
+
+# Gap log
+
+A *gap* is a step rafa could own and does not yet: you had to type a raw
+`gh`, `git` or shell line, or edit a config by hand, because no rafa line
+does it. Each one is filed once, so the next bug sweep can turn the ones
+that repeat into commands.
+
+## Is it a gap?
+
+- **Yes:** a step every stretch takes the same way, such as creating the
+  integration branch, or opening a pull request outside a loop.
+- **Yes:** a flag you add every time, which rafa could read from the
+  scenario instead.
+- **No:** a one-off investigation, or a `git` commit, push or rebase,
+  which stay `git`'s.
+
+## Filing one
+
+Search first, so a gap is filed once:
+
+```bash
+rafa issue list --module=cli-gap --search="<the step in a few words>"
+```
+
+When none matches, file it:
+
+```bash
+rafa issue create --type=bug --module=cli-gap --title="<the step rafa cannot do yet>" --body="<the raw line, the rafa line that came closest, what it lacks>"
+```
+
+When one matches, add the stretch's case to it:
+
+```bash
+rafa issue comment <n> --body="Seen again in stretch <n>: <the raw line>."
+```
+
+The board is public: no local path, host name, user name or secret in the
+title or the body.
+
+## Known at design time
+
+These are filed or waiting to be, so search before filing them again:
+
+- grouping duplicate bugs;
+- opening a pull request outside a loop;
+- creating the integration branch, and switching `pr.base` to it and back;
+- installing the operators;
+- a per-command log under `.rafa/logs/`, for reading a failure from
+  another device;
+- detached loops;
+- `rafa loop list` across projects.
+
+List every gap you filed or commented on in the stretch report.