@open-tomato/rafa 0.37.0 → 0.39.0

package/README.md

@@ -58,6 +58,8 @@ your accounts.
   | `rafa agent search` | 🪙 the same as `rafa skill search`, over agent definitions |
   | `rafa next` | 🪙 when the step it runs is one of the above; it asks before each step |
   | `rafa epic close` | 🪙 one verification planning session and one session per check; nothing while a member is open |
+  | `rafa stretch start` | 🪙 one session per operator it starts: the engineer, watchtower and analyst, or the one `--role` names; with `--dry-run`, nothing |
+  | `rafa stretch item` | 🪙 one planning session, unless a plan of the issue is there already, and the loop it starts; with `--dry-run`, nothing |
 
   The same 🪙 marks appear in `rafa --help` at all levels and in `rafa describe` output.
 
@@ -132,12 +134,14 @@ the next one, so you rarely have to remember it.
    rafa doctor --deep
    ```
 
-   `init` writes `.rafa/config.yaml`, keeps `.rafa/` out of git, and on a
-   GitHub repository offers to set up the board (labels, the spec issue
-   template, a pinned Roadmap issue). `doctor` runs every check
-   `loop start` runs before its first session, and starts nothing: the
-   prerequisites your config and the plan name, `gh` and its login when
-   the repository is on GitHub, and the install itself.
+   `init` writes what is missing of `.rafa/` and `~/.rafa/`, their
+   `config.yaml` files, and directories `specs/`, `plans/`, `runs/`,
+   `effort/`, `instincts/` under `.rafa/`. On a GitHub repository it also
+   offers to set up the board (labels, the spec issue template, a pinned
+   Roadmap issue). `doctor` runs every check `loop start` runs before its
+   first session, and starts nothing: the prerequisites your config and the
+   plan name, `gh` and its login when the repository is on GitHub, and the
+   install itself.
 
 2. **Write a spec.** A spec says what you get, where things stand, the
    design, what can go wrong, the tasks the plan must carry, and how you
@@ -751,6 +755,19 @@ from GitHub Issues:
   from one mode to the other and remove the old marks. Read
   [docs/specs-and-roadmap.md](docs/specs-and-roadmap.md) under "Board
   relationships" for the full choice and upgrade path.
+- **GitHub project as a board mirror.** `rafa init --board --project` creates
+  a GitHub project in your repository, kept in step with your issues by rafa.
+  The project mirrors the issues' labels, pull requests, close state, and the
+  roadmap checklists: one column per issue (Backlog, Triage, Needs work, Ready,
+  Blocked, Claimed, In development, Waiting for approval, In review, Done,
+  Cancelled), a row per open issue and closed issue with a plan or in review.
+  Five fields track Status, Horizon, Rank, Blocked by and Progress; every
+  command that changes an issue's state refreshes its project row, and
+  `rafa board sync` repairs any drift made outside rafa. Optional per
+  repository: run `rafa init --board` without `--project` to skip the project,
+  or `rafa board sync` adds missing issues and refreshes every item on an
+  existing project. Read [context/board-project.md](context/board-project.md)
+  for the full design and the warnings.
 - **Other trackers.** GitHub Issues is what works today. Linear support
   is being ported from the project rafa grew out of, as an optional
   add-on in a later version. For anything else, open or upvote a request

package/dist/PROMPT.md

@@ -2,7 +2,9 @@ We shared as much of the plan as this run is configured to share — the whole p
 
 Do not stage or commit anything: the loop owns staging and committing, and once this session exits cleanly it runs `git add -A` and commits your work under a subject derived from the task text. Leave your changes in the working tree, and leave them in a state the pre-commit hooks accept — a refused hook blocks the task and stops the loop.
 
-End your final message with exactly one `rafa:report` block shaped like the example below, and write nothing after it: the loop stores what it reads there, and a message without the block stores none of your findings. Write all seven fields, `status`, `feedback`, `findings`, `skills_used`, `blockers`, `out_of_scope_bugs` and `changes`, and write a list with nothing in it as `[]` rather than leaving its field out. `status` is `done` or `blocked`. `feedback` says what was done and how it went. `findings` is a list with one entry per distinct observation, never several merged into one; a finding's `kind` is one of `gotcha`, `pattern`, `location` or `skill-suggestion`, its `signal` is `loud` when it surfaced as a failure or `silent` when something passed while wrong, and its `artifact`, when there is one, is the exact string a recurrence would match on, such as an error message. A finding may also carry a `domain`, the area of work its lesson belongs to, one of `code-style`, `testing`, `git`, `debugging`, `workflow`, `security` or `general-best-practices`; leave it out when none fits. `skills_used` names each skill you invoked. `blockers` lists what stopped the task, each entry a `what` and, when there is one, an `artifact`, `out_of_scope_bugs` the bugs you saw outside it, each bug with `security` set to `true` or `false`, and `changes` is the changelog for your diff, each entry holding the required fields `level` (one of patch, minor, major, none) and `summary` (a quoted line the user would understand), plus optional `area` (the changelog section). Write those closed-set words and `security` bare, as the example does, and double-quote every other value on one line: an unquoted value that opens with a backtick, `@`, `%` or `[` makes the whole block unreadable, and a `#` after a space silently cuts a value short.
+Run every command in the foreground, the full test suite included: never start a background command and never wait on a notification. This session is a single `claude -p` turn, so ending it to wait for something leaves no report and no commit; end the session only after your `rafa:report` block.
+
+End your final message with exactly one `rafa:report` block shaped like the example below, and write nothing after it: the loop stores what it reads there, and a message without the block stores none of your findings. Write all seven fields, `status`, `feedback`, `findings`, `skills_used`, `blockers`, `out_of_scope_bugs` and `changes`, and write a list with nothing in it as `[]` rather than leaving its field out. `status` is `done` or `blocked`. `feedback` says what was done and how it went. `findings` is a list with one entry per distinct observation, never several merged into one; a finding's `kind` is one of `gotcha`, `pattern`, `location` or `skill-suggestion`, its `signal` is `loud` when it surfaced as a failure or `silent` when something passed while wrong, and its `artifact`, when there is one, is the exact string a recurrence would match on, such as an error message. A finding may also carry a `domain`, the area of work its lesson belongs to, one of `code-style`, `testing`, `git`, `debugging`, `workflow`, `security` or `general-best-practices`; leave it out when none fits. `skills_used` names each skill you invoked. `blockers` lists what stopped the task, each entry a `what` and, when there is one, an `artifact`, `out_of_scope_bugs` the bugs you saw outside it, each bug with `security` set to `true` or `false` — a test type error that the task's base already held is part of the measured backlog and is not reported as a bug, and the type step's line names how many errors the base held — and `changes` is the changelog for your diff, each entry holding the required fields `level` (one of patch, minor, major, none) and `summary` (a quoted line the user would understand), plus optional `area` (the changelog section). Write those closed-set words and `security` bare, as the example does, and double-quote every other value on one line: an unquoted value that opens with a backtick, `@`, `%` or `[` makes the whole block unreadable, and a `#` after a space silently cuts a value short.
 
 ```rafa:report
 status: done

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

@@ -46,6 +46,11 @@ before it. Never pipe to `| tail` alone, and never poll with
 tool's own summary line (`N pass, N fail` for the suite); never grep the
 capture for `failed`, which appears in deliberate log fixtures.
 
+Run every command in the foreground, the full test suite included: no
+background command, and no waiting on a notification. The session is a
+single `claude -p` turn, so ending it to wait leaves no report and no
+commit; end it only after its `rafa:report` block.
+
 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`,

package/dist/bundled/agents/qa-bug-reporter.md

@@ -134,8 +134,8 @@ confirmation — it only adds evidence to a record that already exists.
 **7. File it.**
 
 ```bash
-gh issue create --title "Fix …" --body-file /tmp/bug.md \
-  --label bug --label "<area>" --label "<priority>"
+rafa issue create --type=bug --body-file /tmp/bug.md \
+  --label "<area>" --label "<priority>"
 ```
 
 Drop the priority label entirely if step 4 produced none, and the area label if

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

@@ -1,5 +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.",
+  "description": "Alpha: rafa's stretch operators, loaded per session with --plugin-dir by rafa stretch start. Never a loop task executor.",
   "author": { "name": "open-tomato" }
 }

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

@@ -9,6 +9,13 @@ stage: alpha
 
 Alpha: tested on rafa's own development, may become a feature.
 
+## Run every rafa line as one command
+
+Run every `rafa` line as one command: no `cd … &&`, no `;`, no pipe, no redirect. The allow
+rules match a single command, and a compound one goes to the auto-mode classifier, which
+reads `--skip-checks` as a CI bypass. The tool returns the output; to keep a record, write
+it with the file tools afterwards.
+
 ## Mission
 
 The person works on hunches and curiosity. Your job is to say which hunch the

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

@@ -10,6 +10,13 @@ stage: alpha
 
 Alpha: tested on rafa's own development, may become a feature.
 
+## Run every rafa line as one command
+
+Run every `rafa` line as one command: no `cd … &&`, no `;`, no pipe, no redirect. The allow
+rules match a single command, and a compound one goes to the auto-mode classifier, which
+reads `--skip-checks` as a CI bypass. The tool returns the output; to keep a record, write
+it with the file tools afterwards.
+
 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,
@@ -91,18 +98,10 @@ rafa status
 rafa release status
 ```
 
-Then:
+Then, after `rafa stretch start` has set up the integration branch and set `pr.base`:
 
 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
+2. **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.
@@ -120,26 +119,10 @@ approval, close the duplicate groups as the skill says.
 
 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: `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.
-   - Into `main`: `rafa pr wait <pr>` then `rafa pr merge <pr>` once
-     the checks pass.
-5. Clean up: `rafa cleanup`.
+Run `rafa stretch item <issue> --wait`. It starts the loop as a detached child, logs
+its output to `.rafa/stretch/<n>/loop-<issue>.log`, waits on it, merges its pull
+request into `stretch/<n>` with checks skipped, and polls the run until it ends. Then
+move to the pit stop.
 
 ### 3. Pit stop
 
@@ -149,20 +132,12 @@ 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. 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.
-4. Finish `report.md`.
-5. Write the next stretch's opening message to
+1. Run `rafa stretch end`. It opens the pull request from `stretch/<n>` into `main`,
+   waits for it to merge, and puts back the `pr.base` recorded when the stretch started.
+2. Once the merge is done, run `rafa release settle --dry-run`, check the base it names,
+   and `rafa release settle`. Tagging and publishing stay with the person.
+3. Finish `report.md`.
+4. 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:
@@ -175,7 +150,8 @@ to the bucket; it is never a change of course.
      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.
+
+5. Add reviewing the engineer prompt to "Steps for the person" in the report.
 
 ## Halts
 

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

@@ -9,6 +9,13 @@ stage: alpha
 
 Alpha: tested on rafa's own development, may become a feature.
 
+## Run every rafa line as one command
+
+Run every `rafa` line as one command: no `cd … &&`, no `;`, no pipe, no redirect. The allow
+rules match a single command, and a compound one goes to the auto-mode classifier, which
+reads `--skip-checks` as a CI bypass. The tool returns the output; to keep a record, write
+it with the file tools afterwards.
+
 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

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

@@ -31,7 +31,7 @@ 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 |
+| CI | `rafa ci status --branch=stretch/<n>` | 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

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

@@ -72,7 +72,7 @@ to 20%.
 `rafa plan create --issue` plans from a `type:spec` issue only. So the
 bucket's bugs go into one sweep spec that lists them, as the project's
 bug sweeps already do, and six bug slots can run as one or two loops.
-Filing that spec is a step with no rafa line yet: log it as a gap.
+File that spec with `rafa issue create --type=spec --body-file <path>`.
 
 ## The bucket report
 

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

@@ -434,14 +434,14 @@ The second example above has no `skills=` and is still a valid task declaration.
 * The RUNNER owns the push, the pull request, the merge with the base,
   the wait for CI, and the release fragment creation. After the last
   task it runs a wrap-up session that promotes findings, compacts
-  `progress.txt`, merges `origin/main`, commits, pushes and opens (or
+  `progress.txt`, merges `origin/<base>`, commits, pushes and opens (or
   updates) the PR — and then polls that PR's checks, spending repair sessions
   on a red or conflicting result. So a plan must NOT carry a task that opens
   a PR, resolves a merge conflict, waits on CI, compacts `progress.txt`,
   or writes a release fragment. Two openers race: measured,
   one run cut a second branch and opened a second PR for a single plan. A
   close-out task SHOULD still take the mergeability reading (`git merge-tree
-  --write-tree origin/main HEAD`) and assemble the body material — the gate
+  --write-tree origin/<base> HEAD`) and assemble the body material — the gate
   captures, the test plan, the recorded debt — into the plan's close-out
   notes for that wrap-up session to use.
 

package/dist/bundled/stretch/engineer-prompt-default.md

@@ -0,0 +1,5 @@
+Start stretch {{STRETCH}}.
+
+Read `.rafa/stretch/{{PREVIOUS}}/report.md` before the sweep, carried work first.
+
+The bucket is yours to propose and mine to approve.