@open-tomato/rafa 0.24.1 → 0.28.0

package/README.md

@@ -175,11 +175,12 @@ the next one, so you rarely have to remember it.
 ### Tracking effort and learning from skills
 
 Each run records what it cost in time, tokens and work, and which skills
-were offered, invoked and worked. Two commands read that record:
+were offered, invoked and worked. Key commands for the effort record:
 
 ```bash
 rafa effort collect        # gather and store session logs
 rafa effort report         # per-plan summary: sessions, tasks, costs
+rafa effort merge <file>   # join another device's store into this one
 ```
 
 `rafa effort report` shows the per-plan tables (sessions by status and
@@ -210,6 +211,26 @@ The report opens with a fixed line explaining that it shows co-occurrence,
 not causation: a skill can be invoked and its failure recur for reasons the
 skill does not cover.
 
+### Starting a second device
+
+To run rafa on a second device for the same project, bring the effort
+store over consistently:
+
+1. On the new device, check for an existing `.rafa/effort/` store and set
+   it aside (rename or back up).
+2. From the primary device, make a consistent copy:
+   ```bash
+   rafa effort copy --to=<path>
+   ```
+   Or use `sqlite3 .rafa/effort/effort.sqlite ".backup <path>"`, but never
+   a plain file copy during a write.
+3. Transfer the copied store and `.rafa/config.yaml` to the new device's
+   `.rafa/` directory.
+4. After both devices have recorded effort, bring them back together with:
+   ```bash
+   rafa effort merge <copied-store-file>
+   ```
+
 ### Which agents and skills are involved
 
 A task line may end with a declaration, for example
@@ -279,6 +300,23 @@ 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.
 
+### `effort`
+
+One setting says how long a command waits for another rafa process that
+is writing the effort store before it gives up with `SQLITE_BUSY`.
+
+| Key | Default | What it sets |
+|---|---|---|
+| `effort.busyTimeoutMs` | `5000` | the wait in milliseconds, a whole number from 1 to 60000 |
+
+There is no unlimited wait, since a lock wait with no end can hang a
+loop; `0`, a fraction and a quoted `"5000"` are refused.
+
+```yaml
+effort:
+  busyTimeoutMs: 10000
+```
+
 ### `cleanup`
 
 Three settings shape what `rafa cleanup` lists.
@@ -359,6 +397,19 @@ from GitHub Issues:
   file `.rafa/position.json` holds your current place, where you were, and
   where you came from — the same two-slot pattern as `cd -` and
   `git checkout -`, plus a home anchor.
+- **Hopping between epics with `rafa next --roadmap`.** When your epic's
+  work is blocked by an issue in another epic, `rafa next --roadmap`
+  reaches for that blocker, works it, and comes home. You hold two slots:
+  home (your anchor) and current (the work in hand). Reaching for a third
+  would mean letting go of home, so rafa halts if a blocker is itself
+  blocked. The pattern keeps unattended work safe: a hop into another
+  team's epic asks for that team's review before it changes their code.
+  Solo projects see a dry hop — the useful part without the permission
+  check. One team hops between its own epics. Several teams open a pull
+  request when a hop crosses to another board, and `rafa status` says
+  `waiting on #C (owner review)` until the team reviews and approves. The
+  hop record (`.rafa/hop.json`) tracks where home is and what rafa works.
+  When `rafa next` finishes, it deletes the record and returns home.
 - **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/bundled/skills/dev-planner/SKILL.md

@@ -503,6 +503,17 @@ The report rules in this skill restate `src/report/parse.ts`, which is the autho
 
 ---
 
+## Plans that change the effort store
+
+When the spec adds or changes anything in `.rafa/effort/`:
+
+- Give each migration its own task, naming its id and whether it is additive or which side it breaks. Never write a schema version number or an array position.
+- A task that runs the branch's store code over real data first runs `bun src/rafa.ts effort copy --to=.rafa/scratch/<stub>-effort`, and runs each command with `RAFA_EFFORT_DIR=<absolute path of that dir>` on the same line. The close-out task removes the copy.
+- Work that must land in the live store goes under "Operator steps after the plan merges [human]": `rafa self-update`, then the command.
+- PREREQUISITES carries `- [ ] The installed rafa can read and write the live store: \`rafa effort schema --check\`` under an `[auto]` heading.
+
+---
+
 ## Command-development rule: Claude session declaration
 
 When planning work on rafa commands: every command that can start a Claude