@open-tomato/rafa 0.50.0 → 0.52.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/bugs/record.d.ts +8 -3
- package/dist/bundled/agents/doc-updater.md +4 -0
- package/dist/bundled/agents/loop-implementer.md +4 -0
- package/dist/bundled/agents/qa-bug-reporter.md +6 -3
- package/dist/bundled/operators/agents/rafa-stretch-engineer.md +10 -2
- package/dist/bundled/operators/skills/rafa-stretch-pit-stop/SKILL.md +37 -11
- package/dist/bundled/operators/skills/rafa-stretch-sweep/SKILL.md +10 -3
- package/dist/bundled/skills/dev-planner/SKILL.md +20 -5
- package/dist/cli.js +2073 -1197
- package/dist/config/index.js +2 -2
- package/dist/effort/store/index.js +2 -2
- package/dist/{index-7rg3jbsz.js → index-91cag9fr.js} +1 -1
- package/dist/{index-w5qbpdtp.js → index-amevawhe.js} +1 -1
- package/dist/{index-kcbs6fp9.js → index-hyp1sraj.js} +1 -1
- package/dist/{index-g91ys6kw.js → index-jjxnyqvy.js} +1 -0
- package/dist/{index-q1tkqxnh.js → index-mbxgc1zv.js} +203 -120
- package/dist/{index-ajv88fkm.js → index-n2r3wf2z.js} +31 -2
- package/dist/{index-zsak0jy6.js → index-nqaqh4zz.js} +1 -1
- package/dist/index.js +349 -99
- package/dist/plan/index.js +2 -2
- package/dist/plan-prompt.md +1 -0
- package/dist/{ready-stwsr9ws.js → ready-3ccr65a2.js} +4 -4
- package/dist/report/parse.d.ts +3 -1
- package/package.json +5 -4
package/dist/bugs/record.d.ts
CHANGED
|
@@ -13,8 +13,10 @@
|
|
|
13
13
|
* `environment`, `versions`, `errorLine`, `artifact`, and the cause
|
|
14
14
|
* (`cause`, `proposed`, `suspected`).
|
|
15
15
|
*
|
|
16
|
-
* `reproduce` and `rerun` stand beside them
|
|
17
|
-
*
|
|
16
|
+
* `reproduce` and `rerun` stand beside them. `reproduce` is one shell
|
|
17
|
+
* command, run from the checkout root, whose output or exit code shows
|
|
18
|
+
* the bug; prose only when no command can show it, and then it names the
|
|
19
|
+
* condition. `rerun` is the one command that shows it again.
|
|
18
20
|
*
|
|
19
21
|
* ## The body
|
|
20
22
|
*
|
|
@@ -63,7 +65,10 @@ export interface BugRecord {
|
|
|
63
65
|
readonly summary: string | null;
|
|
64
66
|
/** The description. The `What` section. */
|
|
65
67
|
readonly what: string | null;
|
|
66
|
-
/**
|
|
68
|
+
/**
|
|
69
|
+
* One shell command run from the checkout root whose output or exit code
|
|
70
|
+
* shows the bug; the condition only when no command can show it. Never `unknown`.
|
|
71
|
+
*/
|
|
67
72
|
readonly reproduce: string | null;
|
|
68
73
|
/** One command that shows the bug again. */
|
|
69
74
|
readonly rerun: string | null;
|
|
@@ -113,6 +113,10 @@ file's wrapped lines before searching.
|
|
|
113
113
|
`stale_docs`; `docs` is the fallback for one written in the wrong field.
|
|
114
114
|
The loop checks every `own-` claim, so a guess between `bug` and
|
|
115
115
|
`own-fallout` is written as `bug`.
|
|
116
|
+
- **Reproduce of each out-of-scope entry.** Give `reproduce` as one command
|
|
117
|
+
run from the checkout root whose output or exit code shows the bug, such
|
|
118
|
+
as `bun test src/x.test.ts` or `grep -n pattern src/y.ts`. Prose only when
|
|
119
|
+
no command can show it, and then it names the condition.
|
|
116
120
|
- Never commit, never push, never open a pull request, never merge. The
|
|
117
121
|
loop owns all four, and `src/PROMPT.md` states what it does once this
|
|
118
122
|
session exits cleanly. Leave your work in the tree in a state the
|
|
@@ -43,6 +43,10 @@ with no `packages/` directory and no workspace boundaries to navigate.
|
|
|
43
43
|
`stale_docs`; `docs` is the fallback for one written in the wrong field.
|
|
44
44
|
The loop checks every `own-` claim, so a guess between `bug` and
|
|
45
45
|
`own-fallout` is written as `bug`.
|
|
46
|
+
- **Reproduce of each out-of-scope entry.** Give `reproduce` as one command
|
|
47
|
+
run from the checkout root whose output or exit code shows the bug, such
|
|
48
|
+
as `bun test src/x.test.ts` or `grep -n pattern src/y.ts`. Prose only when
|
|
49
|
+
no command can show it, and then it names the condition.
|
|
46
50
|
|
|
47
51
|
## Verification
|
|
48
52
|
|
|
@@ -109,8 +109,10 @@ never guess one.
|
|
|
109
109
|
`## ` sections. rafa reads five of them as the bug's fields:
|
|
110
110
|
|
|
111
111
|
- `What`: the context and the symptom.
|
|
112
|
-
- `Reproduce`:
|
|
113
|
-
|
|
112
|
+
- `Reproduce`: one shell command run from the checkout root whose output or
|
|
113
|
+
exit code shows the bug, such as `bun test src/x.test.ts`. Prose only when no
|
|
114
|
+
command can show it, and then the condition that revealed it. Required, and
|
|
115
|
+
never "unknown": when no command can show it, say what was running when it
|
|
114
116
|
showed.
|
|
115
117
|
- `Rerun`: one command that shows it again, when there is one.
|
|
116
118
|
- `Artifact`: the verbatim output. rafa takes the error line from its first
|
|
@@ -159,7 +161,8 @@ Then file from the fields:
|
|
|
159
161
|
```bash
|
|
160
162
|
rafa issue create --type=bug --body-file=/tmp/bug.md \
|
|
161
163
|
--module=<module> --action=<action> --summary="<one line>" \
|
|
162
|
-
--cause=<code>
|
|
164
|
+
--cause=<code> \
|
|
165
|
+
--reproduce="<one command run from the checkout root, or the condition when no command can show it>" \
|
|
163
166
|
--priority=<priority>
|
|
164
167
|
```
|
|
165
168
|
|
|
@@ -67,6 +67,7 @@ this session and your skills load from; leave it as it is.
|
|
|
67
67
|
|---|---|
|
|
68
68
|
| `agent.json` | your session id, written first, so the watchtower finds you |
|
|
69
69
|
| `bucket.md` | the bucket, its duplicate groups, the reason for each pick |
|
|
70
|
+
| `rules.md` | the working rules the person approved for every item, drafted beside the bucket |
|
|
70
71
|
| `loop-<issue>.log` | each loop's output |
|
|
71
72
|
| `pit-stops.md` | one entry per pit stop: what was checked, what was found, what was decided |
|
|
72
73
|
| `report.md` | the stretch report |
|
|
@@ -112,8 +113,15 @@ project is live.
|
|
|
112
113
|
### 1. Sweep and bucket
|
|
113
114
|
|
|
114
115
|
Load `rafa-operators:rafa-stretch-sweep` and follow it. It ends with
|
|
115
|
-
`bucket.md` written and the stretch stopped for approval.
|
|
116
|
-
|
|
116
|
+
`bucket.md` written and the stretch stopped for approval. The same
|
|
117
|
+
message carries the draft of `rules.md`, the working rules every item of
|
|
118
|
+
this stretch follows, as a text block. The person and you write the rules
|
|
119
|
+
together: change the draft in the conversation as the person asks, and
|
|
120
|
+
once the person calls it final, write it unchanged to
|
|
121
|
+
`.rafa/stretch/<n>/rules.md` and print its path once. If the person edited
|
|
122
|
+
that file in the terminal instead, read it back after their word and use
|
|
123
|
+
what it holds. After the approval, close the duplicate groups as the skill
|
|
124
|
+
says.
|
|
117
125
|
|
|
118
126
|
### 2. Run one item
|
|
119
127
|
|
|
@@ -23,25 +23,49 @@ A pit stop is the check between two items. It fixes the one thing that
|
|
|
23
23
|
would stop the next item, then rejoins the bucket: it is never a change
|
|
24
24
|
of course, and never a reason to chase one issue down a rabbit hole.
|
|
25
25
|
|
|
26
|
+
Between two items the closing output of `rafa stretch item` is the whole
|
|
27
|
+
pit stop. Its readings are printed there, and the decision is the only
|
|
28
|
+
step left for you. Read them there; do not run the checks again.
|
|
29
|
+
|
|
26
30
|
## The five checks
|
|
27
31
|
|
|
28
32
|
| Check | Line | What is wrong |
|
|
29
33
|
|---|---|---|
|
|
30
|
-
| Effort | `
|
|
31
|
-
| Bugs | the `Bugs
|
|
34
|
+
| Effort | the `Effort:` line of the item's closing output | cost per task drifting up against the baseline, not explained by the item's size |
|
|
35
|
+
| Bugs | the `Bugs:`, `Filed since` and `Recheck` lines of the item's closing output | the open count rising, a bug filed during this loop that repeats an open one (a `Recheck` line that says `reproduces`) |
|
|
32
36
|
| Delivery | `rafa loop status`, `rafa pr list` | the run is done with no pull request, or its pull request did not merge |
|
|
33
37
|
| Conflicts | `rafa pr show <pr>` | the pull request conflicts with the integration branch |
|
|
34
|
-
| CI | `rafa ci status --branch=stretch/<n>` | the run failed (use `gh run view <id> --log-failed` to see why), or is still running |
|
|
38
|
+
| CI | the `CI:` line of the item's closing output (`rafa ci status --branch=stretch/<n>` gives the same verdict) | the run failed (use `gh run view <id> --log-failed` to see why), or is still running |
|
|
35
39
|
|
|
36
40
|
A CI failure already red in the local runs is inherited and noted in the pit-stop entry.
|
|
37
41
|
A new failure is filed as one bug after a search for an existing one. A run still in progress
|
|
38
42
|
is read at the next pit stop.
|
|
39
43
|
|
|
40
|
-
The
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
44
|
+
The readings in the closing output decide nothing; you do. The shapes:
|
|
45
|
+
|
|
46
|
+
- `Effort: <stub>: <n> tasks, p50 <m> min against <b> min, max <x> min.`
|
|
47
|
+
is the item's effort against its baseline; with no baseline in the store
|
|
48
|
+
it reads `against no baseline`. `Effort: <stub>: no task sessions stored.`
|
|
49
|
+
is a plan with no task sessions in the store. `Effort: not read (<reason>).`
|
|
50
|
+
is a reading that failed.
|
|
51
|
+
- `Bugs: <n> open.`, then `Filed since <time>: <n>.` with one indented line
|
|
52
|
+
per bug filed after the last item, `#<n> <title>: <first line>`. `none` is
|
|
53
|
+
a reading, not a failure. `Filed since the last item: not read: <reason>`
|
|
54
|
+
is one that failed.
|
|
55
|
+
- One `Recheck #<n>: <verdict>` line per bug in that list, judged as
|
|
56
|
+
`rafa bug recheck` judges it, with no comment posted. The verdict is
|
|
57
|
+
`reproduces`, `gone`, `flaky` (with its failed runs), `stale` or `skipped`
|
|
58
|
+
(each with its reason), or `manual`. A `manual` line is followed by the
|
|
59
|
+
bug's reproduce text, indented four spaces: copy it as written, do not look
|
|
60
|
+
the issue up. `Recheck: no bug filed since.` is a reading too.
|
|
61
|
+
`Recheck: not read (<reason>).` is the reading that failed.
|
|
62
|
+
|
|
63
|
+
A line that says `not read` is the only time you type a command by hand:
|
|
64
|
+
`rafa effort dashboard` for an `Effort: not read` line, and
|
|
65
|
+
`rafa bug recheck <n>` for each bug in the `Filed since` list when the
|
|
66
|
+
`Recheck` lines say `not read`. Read the bugs with
|
|
67
|
+
`rafa issue list --type=bug --limit=200` when a bug reading is not read
|
|
68
|
+
and no recheck can be run.
|
|
45
69
|
|
|
46
70
|
A conflict goes to the resolve plans first:
|
|
47
71
|
|
|
@@ -70,13 +94,15 @@ one issue, after a search for an existing one, and the stretch goes on.
|
|
|
70
94
|
|
|
71
95
|
## The entry
|
|
72
96
|
|
|
73
|
-
Append one entry to `.rafa/stretch/<n>/pit-stops.md
|
|
97
|
+
Append one entry to `.rafa/stretch/<n>/pit-stops.md`, quoting the closing
|
|
98
|
+
output's lines for the effort and the bugs:
|
|
74
99
|
|
|
75
100
|
```markdown
|
|
76
101
|
## After #485 (item 2 of 10)
|
|
77
102
|
|
|
78
|
-
- Effort: 14
|
|
79
|
-
- Bugs: 61 open
|
|
103
|
+
- Effort: `Effort: rafa-485-plan: 14 tasks, p50 14.0 min against 12.0 min, max 22.0 min.`
|
|
104
|
+
- Bugs: `Bugs: 61 open.` `Filed since 2026-11-05T09:12:44.000Z: none.`
|
|
105
|
+
`Recheck: no bug filed since.`
|
|
80
106
|
- Delivery: pull request #612 merged into stretch/3.
|
|
81
107
|
- Conflicts: none.
|
|
82
108
|
- CI: verify.yml passed.
|
|
@@ -103,12 +103,19 @@ File that spec with `rafa issue create --type=spec --body-file <path>`.
|
|
|
103
103
|
<items> items: <loops> loops, <planner sessions> planner sessions.
|
|
104
104
|
```
|
|
105
105
|
|
|
106
|
-
|
|
106
|
+
After the report, in the same message, print the draft of `rules.md` as a
|
|
107
|
+
`text` block: the working rules every item of the stretch follows, each one
|
|
108
|
+
a rule the person can say yes or no to. Then stop: the person approves the
|
|
109
|
+
bucket and calls the rules final, and either may change in the conversation
|
|
110
|
+
first.
|
|
107
111
|
|
|
108
112
|
## After the approval
|
|
109
113
|
|
|
110
|
-
|
|
111
|
-
|
|
114
|
+
Once the person calls the rules final, write the draft unchanged to
|
|
115
|
+
`.rafa/stretch/<n>/rules.md` and print its path once. If the person edited
|
|
116
|
+
that file in the terminal, read it back after their word and use what it
|
|
117
|
+
holds. Then close each duplicate with a comment naming the issue kept, so
|
|
118
|
+
reopening is one command:
|
|
112
119
|
|
|
113
120
|
```bash
|
|
114
121
|
rafa issue comment 527 --body="Duplicate of #513: the same registry.test.ts HOME case."
|
|
@@ -75,9 +75,9 @@ A plan document may contain fenced blocks of the form `` ```rafa:*``` `` that
|
|
|
75
75
|
carry metadata and context. Three kinds are read in phase 0:
|
|
76
76
|
|
|
77
77
|
* `rafa:plan` — Header fields in YAML format: `stub`, `issue` (optional),
|
|
78
|
-
`spec` (optional)
|
|
79
|
-
|
|
80
|
-
change that prompted it.
|
|
78
|
+
`spec` (optional), `release` (optional) and `closes` (optional). The stub
|
|
79
|
+
identifies the plan and defaults to the spec's basename or "untitled". The
|
|
80
|
+
loop uses the spec path to link the plan to the change that prompted it.
|
|
81
81
|
* `rafa:context` — Markdown prose injected into the prompt of EVERY task under
|
|
82
82
|
this plan.
|
|
83
83
|
* `rafa:stage-context` — Markdown prose injected only into tasks under the
|
|
@@ -156,6 +156,20 @@ Recognized fields:
|
|
|
156
156
|
- `issue` — Optional GitHub issue number (integer, e.g., `123`). Links the work back to the `open-tomato/rafa` board.
|
|
157
157
|
- `spec` — Optional path to the specification document that guided the plan.
|
|
158
158
|
- `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.
|
|
159
|
+
- `closes` — Optional list of GitHub issue numbers the plan's pull request closes besides `issue`, such as `closes: [1444, 1479]`. Each entry must be a whole positive number. A value that is not a list, or a list holding anything else (a string, a float, `#12`, a mapping), is reported as `unusable-field` and read as unset: the whole list is refused, never part of it. Unset reads as no extra line, so the pull request closes only `issue`. Duplicates, and an entry equal to `issue`, are dropped where the body is written.
|
|
160
|
+
|
|
161
|
+
The lightest header that uses `closes:` sits beside the `issue` it extends:
|
|
162
|
+
|
|
163
|
+
````markdown
|
|
164
|
+
```rafa:plan
|
|
165
|
+
issue: "1484"
|
|
166
|
+
closes: [1444, 1479]
|
|
167
|
+
```
|
|
168
|
+
````
|
|
169
|
+
|
|
170
|
+
That plan's pull request body reads `Closes #1484`, `Closes #1444` and `Closes #1479`, each once.
|
|
171
|
+
|
|
172
|
+
When a plan comes from a sweep spec, merged outside a stretch, fill `closes:` from the spec's bug list: every `#<n>` that its "Tasks the plan must carry" and "What you get" lines name goes in. The pull request then closes each bug the plan names, not only the spec's own issue.
|
|
159
173
|
|
|
160
174
|
Unknown keys are retained and ignored by the loop; they do not cause parsing to fail.
|
|
161
175
|
|
|
@@ -171,6 +185,7 @@ All rafa work follows a consistent naming scheme across specifications, plans, b
|
|
|
171
185
|
| Git branch | `feat/rafa-<n>-<slug>` | `feat/rafa-20-pr-commands` |
|
|
172
186
|
| Pull request title | `rafa-<n>: <title>` | `rafa-20: Add pull-request commands` |
|
|
173
187
|
| Pull request body | `Closes #<n>` | `Closes #20` |
|
|
188
|
+
| `closes:` field in `rafa:plan` | a list of issue numbers, one `Closes #<m>` line each | `closes: [1444, 1479]` |
|
|
174
189
|
|
|
175
190
|
The slug summarizes what the user gets, using two to four words joined by hyphens. The order of work lives in ONE place: the pinned "Roadmap" issue on the `open-tomato/rafa` board.
|
|
176
191
|
|
|
@@ -260,7 +275,7 @@ out_of_scope_bugs:
|
|
|
260
275
|
kind: bug
|
|
261
276
|
module: "store"
|
|
262
277
|
action: "appending to an open store"
|
|
263
|
-
reproduce: "
|
|
278
|
+
reproduce: "bun test src/tests/store-shared-connection.test.ts"
|
|
264
279
|
cause: "the handle is shared across calls"
|
|
265
280
|
changes:
|
|
266
281
|
- level: minor
|
|
@@ -330,7 +345,7 @@ Out-of-scope bug entry fields:
|
|
|
330
345
|
| `kind` | string | no | `bug` | What sort of leftover the entry is, one of the six below. An absent key reads as `bug` with no issue; a value outside the list is reported as an issue and read as `bug`. A different field from a finding's `kind`, with its own list |
|
|
331
346
|
| `module` | string | no | `unknown` | The module the bug is in. Checked against the project's `issues.vocabulary.modules` when that is set, and read as any name of the shape when it is empty. A name outside the set is filed as `unknown`, with the word kept in the bug's record as `Reported module`; triage never refuses a bug over it |
|
|
332
347
|
| `action` | string | no | `unknown` | What was running: a command, a step, a test. Checked against `issues.vocabulary.actions` the same way, the word kept as `Reported action` |
|
|
333
|
-
| `reproduce` | string | no | "seen while running task <task line> of plan <stub>", or "seen while running `<command>`" for a dispatch with no plan stub |
|
|
348
|
+
| `reproduce` | string | no | "seen while running task <task line> of plan <stub>", or "seen while running `<command>`" for a dispatch with no plan stub | One shell command run from the checkout root, such as `rafa plan needs --issue=12 --dry-run`, whose output or exit code shows the bug; prose only when no command can show it, and then the condition that revealed it. Double-quote it. A blank value or `unknown` takes the default: the bug record never holds `unknown` here |
|
|
334
349
|
| `cause` | string | no | `unknown:new-context` | A cause code from `rafa bug codes`, or the cause in words. Double-quote it. A code the list lacks is filed as `<family>:new-context`, with the code kept as proposed, or as `unknown:new-context` when its family is unlisted; words that are no code are filed as `unknown:new-context`, with the words kept as the suspected cause |
|
|
335
350
|
|
|
336
351
|
Out-of-scope entry kinds:
|