@open-tomato/rafa 0.28.0 → 0.32.0

package/README.md

@@ -153,9 +153,9 @@ the next one, so you rarely have to remember it.
    stored, one commit. A task that reports `blocked` is marked and the
    run stops with the reason; fix what it names and start again, and the
    blocked task goes first. After the last task a wrap-up session syncs
-   with the base, bumps the version and the changelog when the project
-   has them, pushes, opens the pull request and waits for CI, spending
-   repair sessions on a red one.
+   with the base, commits a release fragment when the project has them
+   (the plan's level and notes), pushes, opens the pull request and waits
+   for CI, spending repair sessions on a red one.
 
    From another terminal: `rafa loop status`, `rafa loop pause` (after the
    running task), `rafa loop stop` (now).
@@ -163,14 +163,64 @@ the next one, so you rarely have to remember it.
 5. **Land it and look at what it cost.**
 
    ```bash
-   rafa pr current        # number, title, checks, URL
-   rafa pr triage         # why is it red, and is the fix simple (🪙 only with --resolve)
-   rafa pr merge [--skip-checks] # asks y/N, merges, switches to the base, pulls, deletes both branches
-   rafa release tag       # tag the merged version
+   rafa pr current             # number, title, checks, URL
+   rafa pr triage              # why is it red, and is the fix simple (🪙 only with --resolve)
+   rafa pr merge [--skip-checks] # asks y/N, merges, switches to the base, pulls, deletes branches
+   rafa release settle         # folds fragments to a version and pushes
+   rafa release tag            # tag the released version (optional, depends on config)
    rafa effort collect && rafa effort report
    ```
 
-   Then step 2 again, or `rafa plan create --next`.
+   Then step 2 again, or `rafa plan create --next`. When `rafa next` is used,
+   it runs settle and optionally tag as part of the workflow.
+
+### Release fragments and settling
+
+A branch no longer owns a version number. Instead, the wrap-up commits a
+release fragment (a small markdown file naming the plan, level and notes),
+and `rafa release settle` assigns the version on the base branch after
+merges. This lets several branches merge in any order without a version
+collision: whichever machine settles first releases all waiting fragments
+under one version.
+
+The pull request shows a forecast of what version the branch would get if
+merged now. The fragment is stored under `release.fragments` (default
+`.changes/`), one file per plan. `rafa doctor` warns when fragments are
+waiting and suggests running settle. `rafa pr list` marks forecasts as
+`(base moved)` if the base branch changed since the forecast was written.
+
+Every project starts with fragments settling to the base branch and tagging
+by hand. You can configure settle to open a pending release pull request
+instead (for protected base branches), and have settle tag the commit
+automatically (for CI ownership of releases). Four keys, all optional:
+
+```yaml
+# Empty config: fragments in .changes/, semver-by-level, settle pushes, tags by hand
+# (This is the default for every new project.)
+
+release:
+  tag: settle          # settle tags the commit it pushed
+
+release:
+  settle: pr           # protected base branch: one pending release PR
+pr:
+  versionCollision: refuse
+
+release:
+  settle: pr
+  tag: settle
+pr:
+  versionCollision: refuse
+```
+
+The keys are: `release.fragments` (path, default `.changes/`), `release.strategy`
+(fold strategy, default `semver-by-level`), `release.settle` (`push` or `pr`,
+default `push`), `release.tag` (`manual` or `settle`, default `manual`),
+`release.publishCommand` (the publish line `rafa release tag` prints and never
+runs, default `npm publish`). `pr.versionCollision` controls what happens when a merge would collide
+(default `report`). Read `context/release.md` for the full design,
+`docs/ci-release-settle.md` for automating settle in CI, and
+`rafa release settle --help` for the settle command.
 
 ### Tracking effort and learning from skills
 
@@ -180,7 +230,7 @@ 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 import <file>  # merge another device's store into this one
 ```
 
 `rafa effort report` shows the per-plan tables (sessions by status and
@@ -211,10 +261,75 @@ 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.
 
+To see whether task sessions are getting more expensive over time, and
+whether that follows the plan or the calendar:
+
+```bash
+rafa effort report --trend                      # last 3 days against the 14 before, then the loops
+rafa effort report --trend --loops=10 --by=effort
+```
+
+The trend report has two parts. **Trend** compares the recent task
+sessions with a baseline: median and p90 of minutes, output tokens,
+cache-read tokens and turns per task, one row per day, and the sessions
+over the outlier line (baseline median plus three robust standard
+deviations). **Loops** lists one row per plan's loop, newest first: its
+wall-clock and summed task time, number of tasks, minutes per task (min,
+max, average, median), and average tokens and turns per task. Under the
+rows, a drift reading tests each per-task figure across the loops in the
+order they ran (the Mann-Kendall trend test). `no steady trend` means the
+cost moves with the plan; `rising` means it grows whatever the plan.
+
+To see everything at once, the loops running now included:
+
+```bash
+rafa effort collect && rafa effort dashboard
+rafa effort dashboard --output=json             # one key per widget, for a dashboard
+```
+
+The dashboard prints the running loops with their tasks done over total
+and three estimates of the time left: **by task** (the plan's average task
+session), **by progress** (the time since the plan first started, per task
+done), and **this session** (what `rafa loop status` prints). By progress
+counts the time between tasks too, so it is the one to compare against
+the clock. Then come the trend, the loops, each plan's skills M1 and M2,
+and the totals of every stored session.
+
+### Choosing how the effort store travels
+
+An effort store can travel between a project's devices in different ways, each
+suited to different setups. Set `effort.sync` in `.rafa/config.yaml`:
+
+| Setup | Strategy | Why |
+|---|---|---|
+| One laptop | `local` | Nothing to sync |
+| Two personal devices, occasional | `file` | No server, no account; copy a file |
+| Personal projects, frequent | `git` | History and access from git, works offline |
+| A company or several teams | `service` | One hub, live status, shared rules |
+| Advanced, exploratory | `p2p` | Devices talk directly (spike) |
+
+Configuration examples:
+
+```yaml
+# Default: no sync, each device keeps its own store
+# (nothing set, or effort: {sync: local})
+
+# File exchange with no server
+effort:
+  sync: file
+
+# Hub-based sync (requires module and service URL)
+effort:
+  sync: service
+  syncUrl: https://hub.example.com
+```
+
+Only `local` and `file` ship with rafa; `git`, `service` and `p2p` need a module.
+
 ### Starting a second device
 
-To run rafa on a second device for the same project, bring the effort
-store over consistently:
+To run rafa on a second device for the same project, bring the effort store over
+consistently using `rafa effort copy` and `rafa effort import`:
 
 1. On the new device, check for an existing `.rafa/effort/` store and set
    it aside (rename or back up).
@@ -225,10 +340,11 @@ store over consistently:
    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.
+   `.rafa/` directory. **The exported file holds private text — task
+   descriptions, findings, and notes — meant only for your own devices.**
 4. After both devices have recorded effort, bring them back together with:
    ```bash
-   rafa effort merge <copied-store-file>
+   rafa effort import <copied-store-file>
    ```
 
 ### Which agents and skills are involved
@@ -303,11 +419,13 @@ 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`.
+is writing the effort store before it gives up with `SQLITE_BUSY`, and
+another names how the store travels between a project's devices.
 
 | Key | Default | What it sets |
 |---|---|---|
 | `effort.busyTimeoutMs` | `5000` | the wait in milliseconds, a whole number from 1 to 60000 |
+| `effort.sync` | `local` | how the store travels: `local`, `file`, `git`, `service` or `p2p` |
 
 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.
@@ -352,6 +470,87 @@ status:
   notice: false
 ```
 
+### `claims`
+
+Two settings control how claims work when two devices work on one project.
+Devices claim issues to prevent collisions: no two can plan or start the same
+issue, and stale or lost claims are recovered without losing work.
+
+| Key | Default | What it sets |
+|---|---|---|
+| `claims.staleAfter` | `3d` | how long a `rafa:claimed` claim stands before takeover is allowed: a duration such as `3d`, `1w`, or `disabled` |
+| `claims.ahead` | `off` | whether to reserve one issue ahead on the roadmap: `off` or `allow` |
+
+`claims.staleAfter` takes a duration or the word `disabled`; `0`, a fraction,
+and a quoted value are refused. When `disabled`, nothing is ever stale and
+claims must be released by hand. `claims.ahead` enables claim-ahead as an
+opt-in per run with `--claim-ahead` on `rafa next --roadmap` and `plan create
+--next`.
+
+```yaml
+# Default: claims are made, staleAfter is 3d, no claim ahead
+# (nothing set, or claims: {})
+
+# Set staleness only
+claims:
+  staleAfter: 3d
+
+# Disable staleness and enable claim ahead
+claims:
+  staleAfter: disabled
+  ahead: allow
+```
+
+### `loop` and the guard
+
+A loop guards itself: every turn, it watches the checkout's branch and HEAD
+and halts if either changes externally (a branch switch in another terminal,
+a pull that moved the base). The work stays committed and nothing is lost;
+without the guard the edits would move with the checkout. The guard runs on
+every loop and never interferes with the loop's own commits.
+
+**Worktree use cases.** `loop start --as-worktree` runs the loop in a new
+git worktree alongside your main checkout, so you stay on `main` in your
+terminal and can keep working — reviewing, pulling or merging other PRs —
+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,
+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
+branch, both under the same `.rafa/`, allowing parallel work on two epics at
+once. Merging a PR while a loop runs no longer offers `rafa self-update` right
+away; `pr merge` names the running loop and asks you to update after it stops,
+since the binary is what the loop spawns its sessions from, and swapping it
+mid-run changes the engine while driving.
+
+**Edge case: the 2026-09-29 incident.** A loop switched the main checkout to
+its branch; 48 seconds later, `git checkout main` and `git pull` in another
+terminal moved it back, and the edits followed. Both branches were at the
+same commit, so `git switch <loop-branch>` recovered it. With the guard the
+loop halts instead, keeping the work and the branch where it is while you
+sort out what happened.
+
+| Key | Default | What it sets |
+|---|---|---|
+| `loop.worktreeDir` | `.rafa/worktrees` | the directory where `--as-worktree` creates worktrees, absolute or relative to the project root |
+| `dangerous.selfUpdateDuringLoop` | `false` | whether `rafa self-update` runs while a loop of this project is live |
+
+Both take a string and a boolean as written; quoted values are refused.
+
+```yaml
+# empty: loops run in the current checkout, guarded
+# --as-worktree puts them in .rafa/worktrees (the default)
+
+loop:
+  worktreeDir: ../rafa-loops   # worktrees beside the repository
+
+dangerous:
+  selfUpdateDuringLoop: true   # update the binary even while a loop runs
+```
+
 ## Specs, issues and the roadmap
 
 You can plan from a local file and never touch a board. When you want
@@ -410,6 +609,18 @@ from GitHub Issues:
   `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.
+- **Board relationships: a choice of modes.** A board tracks relationships
+  — which issues block which — in one of two ways. `labels` (the default)
+  uses `spec:blocked` labels and `Blocked by:` lines, carrying no cost
+  when a board is read. `native` uses GitHub's built-in parent and
+  blocked-by links, showing them in GitHub's UI and costing about 8 API
+  points per read of 5,000 per hour. Solo projects and those new to rafa
+  start with `labels`. Chose `native` when the relationships should show
+  in GitHub, or when nothing should clear a blocker by hand. Config it as
+  `board: relationships: native`, then run `rafa init --board` to move
+  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.
 - **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
@@ -459,10 +670,13 @@ of `~/.bun/bin`; both warn when it is not, and `rafa doctor` checks it.
 Both exit 1 before building anything while a plan tracker in `plan.dir`
 (`.rafa/plans` unless `.rafa/config.yaml` names another) still holds an
 open or blocked task, and name every such tracker. `rafa self-update`
-runs only inside a project, so `rafa init` the checkout first. They exit
+runs only inside a project, so `rafa init` the checkout first, and it
+also exits 1 while a loop of the project is live, naming each loop's
+branch and pid, unless `dangerous.selfUpdateDuringLoop` is true in the
+config; `--force` does not override that wait. They exit
 2 when they could not run: a `package.json` that is not rafa's or cannot
-be read, a config or tracker they could not read, or a build, copy or
-link that failed.
+be read, a config or tracker they could not read, a loop record
+`rafa self-update` could not read, or a build, copy or link that failed.
 
 A version is installed once. Both also exit 1, before building, when
 `~/.rafa/runtime/<version>/` is already there, naming that directory and
@@ -519,7 +733,9 @@ and a line here is ticked by the change that finishes the feature.
 - ✅ Plan straight from the issue board, or from whatever is next on the roadmap
 - ✅ Review, merge and clean up pull requests from the command line
 - ✅ A failing pull request is diagnosed, and fixed when the fix is simple
-- ✅ A version bump and a changelog entry with every pull request
+- ✅ Release fragments on branches, settled to a version on the base
+  branch after merges, with forecasts in the PR and protection for
+  multiple concurrent branches
 - ✅ Start a plan from the main branch and rafa makes the branch for you
 - ✅ One command takes you to the next step: merge, clean up, plan,
   branch, start

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

@@ -155,7 +155,7 @@ Recognized fields:
 - `stub` — The plan identifier (string, following the `rafa-<n>-<slug>` format). Used to organize findings and dedupe rows across runs.
 - `issue` — Optional GitHub issue number (integer, e.g., `123`). Links the work back to the `open-tomato/rafa` board.
 - `spec` — Optional path to the specification document that guided the plan.
-- `release` — Optional release level for the version bump this plan's pull request ships: `patch`, `minor`, `major` or `none`. Anything else is reported as `unusable-field` and read as if unset. Left out, the level is the highest among the change notes the plan's tasks stored, and `none` when they stored none.
+- `release` — Optional release level for the version bump this plan's pull request ships: `patch`, `minor`, `major` or `none`. Anything else is reported as `unusable-field` and read as if unset. When absent, the level is the highest severity among the plan's collected change notes. The wrap-up writes this level to a release fragment file (under `release.fragments`, default `.changes/`) that `rafa release settle` will process to compute the version bump after the branch merges.
 
 Unknown keys are retained and ignored by the loop; they do not cause parsing to fail.
 
@@ -270,7 +270,7 @@ Report fields:
 | `skills_used` | list of strings | Names of skills referenced or applied |
 | `blockers` | list of objects | What blocked the task. Any entry marks the task `[BLOCKED]` whatever `status` says, so write `[]` when nothing did |
 | `out_of_scope_bugs` | list of objects | Bugs found that are outside this task's scope |
-| `changes` | list of objects | The changelog for this task's own diff, one entry per user-visible change (see below). An absent list is empty with no issue; a task whose diff a user would notice nothing of writes one entry at level `none` |
+| `changes` | list of objects | Release notes for this task's own diff (contributing to the release fragment), one entry per user-visible change (see below). An absent list is empty with no issue; a task whose diff a user would notice nothing of writes one entry at level `none`. The wrap-up collects these from all tasks and writes them to the fragment that `rafa release settle` processes after the branch merges. |
 
 Finding entry fields:
 
@@ -414,13 +414,13 @@ The second example above has no `skills=` and is still a valid task declaration.
   invariant sweeps), live-seam runs, migrations, and close-out — these
   preserve resumability where a halt is most likely.
 * The RUNNER owns the push, the pull request, the merge with the base,
-  the wait for CI, and the version bump and changelog entry. After the last
+  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
   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 version bump or changelog entry. Two openers race: measured,
+  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