@open-tomato/rafa 0.51.0 → 0.52.1

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.
@@ -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: the steps, or the condition
17
- * that revealed the bug, and the one command that shows it again.
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
- /** The steps, or the condition that revealed the bug. Never `unknown`. */
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`: the steps, or the condition that revealed it. Required, and
113
- never "unknown": when no steps are known, say what was running when it
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> --reproduce="<steps, or the revealing condition>" \
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. After the
116
- approval, close the duplicate groups as the skill says.
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 | `rafa effort dashboard` | cost per task drifting up against the baseline, not explained by the item's size |
31
- | Bugs | the `Bugs:` and `Filed since` lines of the item's closing output | the open count rising, or a bug filed during this loop that repeats an open one |
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 bugs come from the closing output of `rafa stretch item`: `Bugs: <n> open.`,
41
- then `Filed since <time>: <n>.` with one indented line per bug filed after the
42
- last item, open or closed since, as `#<n> <title>: <first line>`. `none` is a
43
- reading, not a failure. A line that says `not read` names its reason; read the
44
- bugs with `rafa issue list --type=bug --limit=200` when a reading is not read.
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 min per task against a 12 min baseline; the plan was large.
79
- - Bugs: 61 open, 64 at the start; none filed during the loop.
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
- Then stop: the person approves the bucket.
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
- Close each duplicate with a comment naming the issue kept, so reopening
111
- is one command:
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). The stub identifies the plan and defaults to the spec's
79
- basename or "untitled". The loop uses the spec path to link the plan to the
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: "run the store tests against a shared connection"
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 | The steps, or the condition that revealed it. Double-quote it. A blank value or `unknown` takes the default: the bug record never holds `unknown` here |
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: