@open-tomato/rafa 0.32.0 → 0.34.0

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.

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

@@ -0,0 +1,77 @@
+---
+name: rafa-stretch-pit-stop
+description: "Use after each stretch item: check effort, bugs, delivery, conflicts and CI, then go on, insert one fix, or halt."
+provenance: first-party
+source: rafa
+stage: alpha
+prevents: "a stretch that misses a run with no pull request, piles up refiled bugs, or wanders off after one issue"
+signal: silent
+when_to_use: "You are rafa-stretch-engineer and one bucket item's loop has just ended, merged or not. Prevents: a stretch that misses a run with no pull request, piles up refiled bugs, or wanders off after one issue"
+tags:
+  - rafa
+  - stretch
+  - effort
+stack:
+  - shell
+---
+
+Alpha: tested on rafa's own development, may become a feature.
+
+# Pit stop
+
+A pit stop is the check between two items. It fixes the one thing that
+would stop the next item, then rejoins the bucket: it is never a change
+of course, and never a reason to chase one issue down a rabbit hole.
+
+## The five checks
+
+| Check | Line | What is wrong |
+|---|---|---|
+| Effort | `rafa effort dashboard` | cost per task drifting up against the baseline, not explained by the item's size |
+| 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 |
+
+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
+is read at the next pit stop.
+
+A conflict goes to the resolve plans first:
+
+```bash
+rafa pr triage <pr> --resolve
+```
+
+A run that ended with no pull request is a known defect of the loop: say
+so in the pit-stop entry, and open the pull request from the run's branch
+only after reading the run's last `rafa·` lines.
+
+## Deciding
+
+1. **All fine.** Write the entry and take the next item.
+2. **A blocker a loop can fix.** It stops the next item, and one small
+   plan can fix it. It becomes the next item and takes a bucket slot.
+   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.
+
+Anything else you find is filed, not fixed: one issue, after a search for
+an existing one, and the stretch goes on.
+
+## The entry
+
+Append one entry to `.rafa/stretch/<n>/pit-stops.md`:
+
+```markdown
+## After #485 (item 2 of 10)
+
+- Effort: 14 min per task against a 12 min baseline; the plan was large.
+- Bugs: 61 open, 64 at the start; none filed during the loop.
+- Delivery: pull request #612 merged into stretch/3.
+- Conflicts: none.
+- CI: verify.yml passed.
+- Decision: next item, #486.
+```

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

@@ -0,0 +1,111 @@
+---
+name: rafa-stretch-sweep
+description: "Use at a stretch's sweep: group duplicate bugs, rank the board, and fill a bucket of up to 10 issues by tier."
+provenance: first-party
+source: rafa
+stage: alpha
+prevents: "a bucket that refiles the same failing test, chases a feature over a blocker, or pulls in a chain of issues"
+signal: silent
+when_to_use: "You are rafa-stretch-engineer in phase 1 of a stretch, choosing which issues the stretch will run. Prevents: a bucket that refiles the same failing test, chases a feature over a blocker, or pulls in a chain of issues"
+tags:
+  - rafa
+  - stretch
+  - triage
+stack:
+  - shell
+---
+
+Alpha: tested on rafa's own development, may become a feature.
+
+# Sweep and bucket
+
+The sweep reads the board, groups what is filed twice, ranks what is
+left, and proposes a *bucket*: the issues this stretch will run, at most
+10. It ends with the bucket written and the stretch stopped for the
+person's approval.
+
+## Read the board
+
+```bash
+rafa roadmap --full
+rafa issue list --type=bug --limit=200
+rafa effort report --trend
+```
+
+Read the roadmap's "now" epics first: their members are where the
+project already said the work is.
+
+## The five steps
+
+1. **Group the duplicates.** Bugs naming the same failing test, or the
+   same symptom in other words, form one group. The oldest issue of a
+   group stays open; the others will close as its duplicates. Most
+   duplicate bugs are one failing test filed by several loops, so read
+   test file names and case names first.
+2. **Rank the bugs.** First by how often the group was filed, then by
+   impact: what it unblocks, and whether it breaks the loop itself (a run
+   with no pull request, a refused pull, a false blocker).
+3. **Fill 10 slots by tier.** 6 bugs, 3 fixes, 1 preparation item, by the
+   tier rules below.
+4. **Apply the chain rule.** An item that would pull in a chain of other
+   items is left out for a later stretch. An item whose absence would
+   spread an error, or make a new one, is let in past the cap.
+5. **Write the bucket report** to `.rafa/stretch/<n>/bucket.md`.
+
+## The tiers
+
+| Tier | What belongs | First |
+|---|---|---|
+| Bugs | anything filed as a bug that still happens | refiled most, then biggest impact |
+| Fixes and stabilisation | work that closes a known defect, labelled as a fix or not | fixes, then stabilisation |
+| Preparation | work that readies the next feature, or separates mechanics from interface | only what a target feature needs |
+
+**Rebalancing.** When a tier has fewer items than its slots, its spare
+slots split 50-50 between the other two, starting from the highest tier.
+A tier that already split passes its half on to the tier below, so no
+split repeats. The bug share never drops under 20% while bugs remain;
+when every bug left is low impact and touches no workflow, it may drop
+to 20%.
+
+## Bugs reach a loop through one sweep spec
+
+`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.
+
+## The bucket report
+
+```markdown
+# Stretch <n>: bucket
+
+| Slot | Issue | Tier | Why it is here |
+|---|---|---|---|
+| 1 | #485 | fix | every loop inherits its red tests |
+
+## Duplicate groups
+
+| Kept | Closes as duplicates | The shared test or symptom |
+|---|---|---|
+| #513 | #527, #555, #571, #583 | registry.test.ts HOME case |
+
+## Left out, and why
+
+- #28: pulls in a chain of four specs.
+
+## Cost
+
+<items> items: <loops> loops, <planner sessions> planner sessions.
+```
+
+Then stop: the person approves the bucket.
+
+## After the approval
+
+Close each duplicate with a comment naming the issue kept, so reopening
+is one command:
+
+```bash
+rafa issue comment 527 --body="Duplicate of #513: the same registry.test.ts HOME case."
+rafa issue move 527 done
+```

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

@@ -28,7 +28,7 @@ This file is the single source of that format. `rafa plan` inlines it, without i
 | `<plan.dir>/PLAN-<stub>.md` | Full task checklist with structured blocks and technical context |
 | `<plan.dir>/PREREQUISITES-<stub>.md` | Non-automatable setup steps required before the plan can run (only when any exist) |
 
-`plan.dir` is `.rafa/plans` unless the project's `.rafa/config.yaml` names another directory. `rafa plan --spec=<spec>.md` generates both files (optionally `--stub=<name>`; the stub defaults to the spec's basename) and writes them into `plan.dir`, creating the directory when it is missing. It reads the spec from the project root, or from `specs.dir` (`.rafa/specs` by default) when the root holds no such file, and refuses to run when `<plan.dir>/PLAN-<stub>.md` already exists.
+`plan.dir` is `.rafa/plans` unless the project's `config.yaml` under `.rafa/` names another directory. `rafa plan --spec=<spec>.md` generates both files (optionally `--stub=<name>`; the stub defaults to the spec's basename) and writes them into `plan.dir`, creating the directory when it is missing. It reads the spec from the project root, or from `specs.dir` (`.rafa/specs` by default) when the root holds no such file, and refuses to run when `<plan.dir>/PLAN-<stub>.md` already exists.
 
 Execute a plan with `rafa start --plan=.rafa/plans/PLAN-<stub>.md`. With no `--plan`, `rafa start` runs `PLAN.md` in `plan.dir`, and falls back to a hand-written `PLAN.md` at the project root only when `plan.dir` holds no `PLAN.md`.
 
@@ -165,7 +165,7 @@ All rafa work follows a consistent naming scheme across specifications, plans, b
 
 | Artifact | Pattern | Example |
 | --- | --- | --- |
-| Specification file | `.rafa/specs/rafa-<n>-<slug>.md` | `.rafa/specs/rafa-20-pr-commands.md` |
+| Specification file | `.rafa/specs/rafa-<n>-<slug>.md` | `rafa-20-pr-commands.md`, under `.rafa/specs/` |
 | Plan stub and directory | `rafa-<n>-<slug>` | `rafa-20-pr-commands` |
 | `issue:` field in `rafa:plan` | `<n>` (number only) | `issue: 20` |
 | Git branch | `feat/rafa-<n>-<slug>` | `feat/rafa-20-pr-commands` |
@@ -352,6 +352,7 @@ The strip happens where the loop reads the next task, `findNextTask` in `src/uti
 | `budget` | US dollars above zero, as a plain decimal of at most six digits each side of the point, such as `0.50` | `--max-budget-usd` | always passed: a definition supplies no budget |
 | `tools` | tool names, comma-separated with no spaces | `--tools` | never passed: the definition names its tool set |
 | `skills` | skill names, comma-separated with no spaces | nothing: no flag carries a skill | kept on the record beside the agent |
+| `tests` | `affected`, `module` or `full`; `affected` when absent | nothing: the loop's runner reads it | kept on the record beside the agent |
 
 * `agent=<name>` outranks `model` and `tools`, and `effort` only when its
   definition declares one, as the last column says. The outranked keys
@@ -376,7 +377,7 @@ The strip happens where the loop reads the next task, `findNextTask` in `src/uti
 
 There is no default agent. A task with no declaration passes no routing flag and runs at the loop's defaults, as does one whose every value failed to parse.
 
-The recognised keys are the `DECLARATION_KEYS` of `src/utils/declaration.ts`, whose `MODEL_ALIASES` and `EFFORT_LEVELS` hold the aliases and levels in the table, whose `parseBudgetUsd` reads a budget and whose `parseSkillList` reads a skill list; that module is the authority for this section, so change the two together.
+The recognised keys are the `DECLARATION_KEYS` of `src/utils/declaration.ts`, whose `MODEL_ALIASES`, `EFFORT_LEVELS` and `TEST_SCOPES` hold the aliases, levels and test scopes in the table, whose `parseBudgetUsd` reads a budget, whose `parseSkillList` reads a skill list and whose `readTestScope` reads a test scope; that module is the authority for this section, so change the two together.
 
 ### `skills=` declaration
 
@@ -393,6 +394,23 @@ A task with no `skills=` declaration is valid — naming none is the answer when
 
 The second example above has no `skills=` and is still a valid task declaration.
 
+### `tests=` declaration
+
+`tests=` names how much of the suite the loop's runner runs after the task commits. The task's own session runs only the tests its changes reach, whatever the key says; the key sizes the runner's step that follows it.
+
+| Value | The runner's step runs |
+| --- | --- |
+| `affected` | the test files the task's diff reaches. The default: a task with no `tests=` runs this |
+| `module` | the tests of every module the task's diff touches |
+| `full` | the whole suite |
+
+`tests` is a recognised key that maps to no flag, like `skills`: it stands on its own (`{tests=full}` is a declaration), is stripped from the task text with the rest of the block, and a value outside the three is recorded as an issue and read as absent, so the task runs at `affected`.
+
+```markdown
+  - [ ] Drive a real `rafa loop start` over a one-task fixture plan  {tests=module}
+  - [ ] Move the test preload into `bunfig.toml`  {tests=full}
+```
+
 ---
 
 ## Task sizing (session economics)
@@ -431,7 +449,7 @@ The second example above has no `skills=` and is still a valid task declaration.
 
 ## Three task-context injection modes
 
-The loop supports three modes of injecting task context, configured at plan start via `--inject=` or in `.rafa/config.yaml`:
+The loop supports three modes of injecting task context, configured at plan start via `--inject=` or in the project's `config.yaml` under `.rafa/`:
 
 | Mode | Contents | Use case |
 | --- | --- | --- |

package/dist/bundled/skills/git-workflow/SKILL.md

@@ -38,7 +38,7 @@ For the rafa project specifically, issue numbers are prefixed with `rafa-` and
 reflected throughout the spec and branch workflow:
 
 - **Issue reference** (in prose): `#rafa-<n>` — e.g., `#rafa-20`
-- **Spec file**: `.rafa/specs/rafa-<n>-<slug>.md` — e.g., `.rafa/specs/rafa-20-pr-commands.md`
+- **Spec file**: `.rafa/specs/rafa-<n>-<slug>.md` — e.g., `rafa-20-pr-commands.md`, under `.rafa/specs/`
 - **Plan stub** (in prose): `rafa-<n>-<slug>` — e.g., `rafa-20-pr-commands`
 - **Branch name**: `feat/rafa-<n>-<slug>` — e.g., `feat/rafa-20-pr-commands`
 - **PR title**: `rafa-<n>: <title>` — e.g., `rafa-20: Add PR commands`