@davidbyoung/software-factory 0.1.10 → 0.1.12
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/agents/factory-e2e-reviewer.md +1 -1
- package/agents/factory-test-reviewer.md +1 -1
- package/agents/factory-ticket-readiness.md +20 -15
- package/agents/factory-ui-reviewer.md +2 -2
- package/dist/board.d.mts +8 -8
- package/dist/board.mjs +53 -37
- package/dist/build.d.mts +4 -0
- package/dist/build.mjs +9 -4
- package/dist/cli.mjs +25 -5
- package/dist/code-host/github.mjs +11 -4
- package/dist/code-host/types.d.mts +8 -2
- package/dist/commands.d.mts +7 -2
- package/dist/commands.mjs +96 -17
- package/dist/config.d.mts +3 -4
- package/dist/config.mjs +7 -8
- package/dist/init.d.mts +11 -0
- package/dist/init.mjs +56 -1
- package/dist/lib/clock.d.mts +3 -1
- package/dist/lib/clock.mjs +12 -6
- package/dist/lib/pull-tickets.d.mts +15 -0
- package/dist/lib/pull-tickets.mjs +12 -0
- package/dist/lib/usage.d.mts +3 -1
- package/dist/lib/usage.mjs +4 -2
- package/dist/lib/work-status.d.mts +28 -24
- package/dist/lib/work-status.mjs +21 -35
- package/dist/merge-policy.mjs +7 -3
- package/dist/poller.d.mts +3 -3
- package/dist/poller.mjs +18 -14
- package/dist/pr.d.mts +26 -6
- package/dist/pr.mjs +92 -28
- package/dist/review-tickets.d.mts +12 -0
- package/dist/review-tickets.mjs +59 -0
- package/dist/review-verdict.d.mts +22 -4
- package/dist/review-verdict.mjs +55 -17
- package/dist/reviewers.d.mts +7 -4
- package/dist/reviewers.mjs +19 -12
- package/dist/runner/github-actions.mjs +6 -7
- package/dist/runner/types.d.mts +7 -6
- package/dist/specs/index.d.mts +6 -0
- package/dist/specs/index.mjs +15 -0
- package/dist/specs/openspec.d.mts +2 -0
- package/dist/specs/openspec.mjs +78 -0
- package/dist/specs/types.d.mts +53 -0
- package/dist/specs/types.mjs +4 -0
- package/dist/status.d.mts +17 -7
- package/dist/status.mjs +35 -23
- package/dist/sync.d.mts +4 -0
- package/dist/sync.mjs +14 -1
- package/dist/ticket.d.mts +15 -7
- package/dist/ticket.mjs +128 -61
- package/dist/tickets/github-access.d.mts +5 -0
- package/dist/tickets/github-access.mjs +22 -0
- package/dist/tickets/github.d.mts +10 -2
- package/dist/tickets/github.mjs +76 -20
- package/dist/tickets/index.d.mts +7 -1
- package/dist/tickets/index.mjs +15 -1
- package/dist/tickets/types.d.mts +63 -30
- package/dist/tickets/types.mjs +13 -3
- package/dist/tool-names.d.mts +2 -0
- package/dist/tool-names.mjs +3 -0
- package/dist/tools.d.mts +2 -0
- package/dist/tools.mjs +3 -0
- package/docs/builds.md +4 -1
- package/docs/cli.md +30 -11
- package/docs/configuration.md +51 -39
- package/docs/developing.md +115 -62
- package/docs/existing-repo.md +4 -3
- package/docs/github/reference.md +1 -1
- package/docs/github/setup.md +20 -3
- package/docs/glossary.md +7 -6
- package/docs/limitations.md +8 -5
- package/docs/plugins.md +6 -6
- package/docs/updating.md +18 -0
- package/docs/workflow.md +25 -8
- package/package.json +1 -1
- package/review.md +11 -11
- package/rules.md +52 -42
- package/skills/factory-address-review/SKILL.md +44 -42
- package/skills/factory-build/SKILL.md +71 -72
- package/skills/factory-refine/SKILL.md +31 -23
- package/skills/factory-resolve-conflicts/SKILL.md +12 -10
- package/workflows/factory-build.yml +6 -5
- package/workflows/factory-claude-review.yml +38 -1
package/docs/limitations.md
CHANGED
|
@@ -27,9 +27,11 @@ as a code host's billing or what its workflows can see, are in
|
|
|
27
27
|
there. A change to those settings is a person's to make.
|
|
28
28
|
- **One ticket, one repository.** A change that spans repositories is two
|
|
29
29
|
tickets.
|
|
30
|
-
- **
|
|
31
|
-
|
|
32
|
-
|
|
30
|
+
- **Review by teams is your code host's to enforce.** A session obeys
|
|
31
|
+
anyone who can write to the repository. Required reviewers for a
|
|
32
|
+
folder, and a number of approvals before a merge, are rules you set on
|
|
33
|
+
the code host, and the factory's pull requests are held by them like
|
|
34
|
+
any other.
|
|
33
35
|
- **The order of the workflow is fixed.** A [plugin](plugins.md) of
|
|
34
36
|
yours can replace how a ticket is refined, how a ticket with one of your
|
|
35
37
|
labels is built, how a test is proved able to fail, which agents review
|
|
@@ -127,8 +129,9 @@ as a code host's billing or what its workflows can see, are in
|
|
|
127
129
|
- **It amplifies the checks it is given.** A repository with weak tests gets
|
|
128
130
|
confident, wrong pull requests faster.
|
|
129
131
|
- **Ticket text, review comments, and changelogs are read by sessions.**
|
|
130
|
-
Only an approver's
|
|
131
|
-
|
|
132
|
+
Only an approver's words are treated as instructions, and that rests on
|
|
133
|
+
who your code host says can write to the repository. Give write access
|
|
134
|
+
as carefully as you would give a session its orders.
|
|
132
135
|
- **An update delivers instructions that run with your tokens.** Read update
|
|
133
136
|
pull requests as carefully as code.
|
|
134
137
|
- **It sits on tools that change.** Several parts work around how today's
|
package/docs/plugins.md
CHANGED
|
@@ -74,12 +74,12 @@ plugins:
|
|
|
74
74
|
skill: acme-refine
|
|
75
75
|
```
|
|
76
76
|
|
|
77
|
-
| Step | What happens
|
|
78
|
-
| ----------- |
|
|
79
|
-
| **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited
|
|
80
|
-
| **Handed** | The ticket's
|
|
81
|
-
| **Returns** | A ticket a build can start from: everything in the list below
|
|
82
|
-
| **Then** | The ticket waits for your approval, and the build reads what the refiner left
|
|
77
|
+
| Step | What happens |
|
|
78
|
+
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
79
|
+
| **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
|
|
80
|
+
| **Handed** | The ticket's key. From `factory-build`, for a round of questions you approved while it waited on your answers, also the words "approved while waiting: fold the owner's replies into the body, post no marker". They tell the refiner to write your replies into the ticket's body and to post no [marker](glossary.md), the hidden comment line the board reads |
|
|
81
|
+
| **Returns** | A ticket a build can start from: everything in the list below |
|
|
82
|
+
| **Then** | The ticket waits for your approval, and the build reads what the refiner left |
|
|
83
83
|
|
|
84
84
|
**What a refiner must deliver.** The board and the build read these, so a
|
|
85
85
|
refiner that leaves one out leaves a ticket that cannot be built.
|
package/docs/updating.md
CHANGED
|
@@ -332,6 +332,24 @@ again, and you close the issue `factory-deps` opened.
|
|
|
332
332
|
`✓ The settings are valid.`, and `factory ticket branch 12` prints the
|
|
333
333
|
branch a build of ticket 12 would push.
|
|
334
334
|
|
|
335
|
+
## A spec for every visible change
|
|
336
|
+
|
|
337
|
+
From this release, a change your users will see, and that isn't small,
|
|
338
|
+
gets the `spec` label and a [Spec, a design, and a list of
|
|
339
|
+
tasks](workflow.md#a-change-your-users-will-see) in its ticket, whatever
|
|
340
|
+
[`specs`](configuration.md#specs) says. Before it, a repository with
|
|
341
|
+
`specs: none`, or no `specs` line, which means the same, got only a list
|
|
342
|
+
of acceptance criteria. Nothing stops on the update: tickets refined
|
|
343
|
+
earlier build as they are, and the next one refinement writes has the
|
|
344
|
+
longer shape.
|
|
345
|
+
|
|
346
|
+
`factory specs change-name N` is gone. A script of yours that ran it
|
|
347
|
+
runs `factory specs new N` and `factory specs finish N` instead
|
|
348
|
+
([Your repository's commands](cli.md#your-repositorys-commands)).
|
|
349
|
+
|
|
350
|
+
The next time you run `factory init`, it asks once which spec tool you
|
|
351
|
+
use, and writes your answer; choosing OpenSpec installs it.
|
|
352
|
+
|
|
335
353
|
## The commands
|
|
336
354
|
|
|
337
355
|
| Command | When |
|
package/docs/workflow.md
CHANGED
|
@@ -188,11 +188,28 @@ verdict.
|
|
|
188
188
|
|
|
189
189
|
## A change your users will see
|
|
190
190
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
191
|
+
A change that adds or alters behavior someone can see, and is not
|
|
192
|
+
[small](#sizing-the-work-to-the-change), gets the `spec` label, which
|
|
193
|
+
refinement adds and the build reads. Refinement writes three things into
|
|
194
|
+
its ticket, after your own text:
|
|
195
|
+
|
|
196
|
+
- **Spec:** what the change must do, as numbered "When this, then that"
|
|
197
|
+
lines, such as "3. When a visitor sends the form with no email, the
|
|
198
|
+
form still sends." To change one, name it by its number where
|
|
199
|
+
refinement asks you, in the session or in a comment on the ticket,
|
|
200
|
+
such as "3: and when the email is not valid, it says so."
|
|
201
|
+
- **Design:** where the change goes and the cases it must handle.
|
|
202
|
+
- **Tasks:** the steps to build it, each naming the test that checks it.
|
|
203
|
+
|
|
204
|
+
The design and tasks sit in a collapsed "For the builder" section, so
|
|
205
|
+
you can read the Spec and approve the ticket as you approve any other
|
|
206
|
+
([From a ticket to a merge](#from-a-ticket-to-a-merge)). The build works
|
|
207
|
+
from the ticket alone, and its pull request's description lists the
|
|
208
|
+
test that checks each Spec line.
|
|
209
|
+
|
|
210
|
+
A [spec tool](configuration.md#specs), such as OpenSpec, also keeps the
|
|
211
|
+
Spec in your repository.
|
|
212
|
+
|
|
213
|
+
Every other ticket, such as a bug fix, a copy change, or a small change,
|
|
214
|
+
has a list of acceptance criteria instead: what must be true for it to
|
|
215
|
+
be done.
|
package/package.json
CHANGED
package/review.md
CHANGED
|
@@ -56,21 +56,21 @@ defend.
|
|
|
56
56
|
the facts; if you still disagree, say so once in the summary, with your
|
|
57
57
|
evidence, rather than opening a new thread.
|
|
58
58
|
|
|
59
|
-
4. Read what the pull request was asked to do
|
|
60
|
-
|
|
59
|
+
4. Read what the pull request was asked to do: its body, and the tickets it
|
|
60
|
+
builds, which the workflow has read for you into the file TICKETS names.
|
|
61
|
+
Read that file with the Read tool. Each ticket there starts with a `## `
|
|
62
|
+
line naming it and its title. When the file says the tickets could not be
|
|
63
|
+
read, say so in the summary and go by the body.
|
|
61
64
|
|
|
62
65
|
```bash
|
|
63
|
-
gh pr view PR_NUMBER --json body
|
|
64
|
-
gh api graphql -F n=ISSUE_NUMBER -f query='query($n: Int!) { repository(owner: "OWNER", name: "NAME") { issue(number: $n) { body } } }' --jq .data.repository.issue.body
|
|
66
|
+
gh pr view PR_NUMBER --json body
|
|
65
67
|
```
|
|
66
68
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
The issue's "Spec" and "Acceptance criteria" sections are what the
|
|
70
|
-
change must do, and its "Decisions" are settled. An issue with neither
|
|
69
|
+
The ticket's "Spec" and "Acceptance criteria" sections are what the
|
|
70
|
+
change must do, and its "Decisions" are settled. A ticket with neither
|
|
71
71
|
is held only to what it plainly asks for: a fix it suggests is not a
|
|
72
|
-
criterion. The follow-ups
|
|
73
|
-
body says this pull request built. A pull request that
|
|
72
|
+
criterion. The follow-ups ticket is held to the lines the
|
|
73
|
+
body says this pull request built. A pull request that builds no ticket,
|
|
74
74
|
such as a source audit, has only its body to go by.
|
|
75
75
|
|
|
76
76
|
## What to look for
|
|
@@ -79,7 +79,7 @@ defend.
|
|
|
79
79
|
that is silently dropped.
|
|
80
80
|
- **What it was asked to do.** A Spec line or criterion from step 4 that
|
|
81
81
|
the whole pull request, `git diff origin/DEFAULT...HEAD`, does not meet, or
|
|
82
|
-
meets only in part, is a finding, since the merge closes the
|
|
82
|
+
meets only in part, is a finding, since the merge closes the ticket as
|
|
83
83
|
done: High when a user would see the gap, Medium otherwise. Behavior
|
|
84
84
|
no line asked for is Medium, unless the body or the owner's comments on
|
|
85
85
|
the pull request explain it. Quote the line either way.
|
package/rules.md
CHANGED
|
@@ -30,11 +30,11 @@ here rather than restate it.
|
|
|
30
30
|
such as "small: one test, red first, one UI reviewer read", so the
|
|
31
31
|
owner can overrule it before the work starts rather than halfway through.
|
|
32
32
|
- **No `spec` label**, even when a user sees it: the issue's acceptance
|
|
33
|
-
criteria are the spec. No
|
|
34
|
-
a line of
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
which then waits for the owner. A fix that restores what a spec says
|
|
33
|
+
criteria are the spec. No spec tool change either, unless the change
|
|
34
|
+
makes a line of a spec `npx --no-install factory specs list` prints
|
|
35
|
+
false, as renaming a label a spec quotes would. That issue also carries
|
|
36
|
+
a Spec section of the changed line, and the build folds it into the
|
|
37
|
+
specs in the same pull request, which then waits for the owner. A fix that restores what a spec says
|
|
38
38
|
changes no line of it.
|
|
39
39
|
- **No `factory-ticket-readiness` read and no read by the test reviewers**
|
|
40
40
|
(`npx --no-install factory plugins test-reviewer` lists them), with two
|
|
@@ -109,8 +109,9 @@ discovering it at push time.
|
|
|
109
109
|
`npx --no-install factory pr state N --wait`, and does not run it, since
|
|
110
110
|
nothing can wake it once it stops.
|
|
111
111
|
- **A pull request that resolves an issue closes it.** When asked to open
|
|
112
|
-
one, start the body with
|
|
113
|
-
so the merge closes them. Check that
|
|
112
|
+
one, start the body with the line `npx --no-install factory ticket link N`
|
|
113
|
+
prints for each issue the branch resolves, so the merge closes them. Check that `npx --no-install factory pr closes PR`
|
|
114
|
+
prints each one.
|
|
114
115
|
- **After pushing, check for review automatically.** The `Claude review`
|
|
115
116
|
workflow reviews every push to a PR. If an open PR exists for the branch,
|
|
116
117
|
wait for the review of that push, then work it with the `factory-address-review` skill
|
|
@@ -167,28 +168,34 @@ always the owner's.
|
|
|
167
168
|
|
|
168
169
|
## Spec track
|
|
169
170
|
|
|
170
|
-
The spec
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
`
|
|
171
|
+
The ticket is the spec: `factory-refine` writes it, the owner
|
|
172
|
+
approves it by moving its card to Ready or telling a session to build
|
|
173
|
+
it, and `factory-build` builds it. A change that adds or alters behavior
|
|
174
|
+
a user can see carries the `spec` label, which `factory-refine` adds,
|
|
175
|
+
unless it is small ("Small changes" above), whatever spec tool the
|
|
176
|
+
repository uses. Its issue holds "Decisions", numbered "Spec" lines, and
|
|
177
|
+
"For the builder" with a design and tasks, so a build needs nothing
|
|
178
|
+
else.
|
|
179
|
+
|
|
180
|
+
Everything else, such as copy, bug fixes that restore intended behavior,
|
|
181
|
+
style tweaks, tooling, CI, and docs, builds from the issue's "Acceptance
|
|
182
|
+
criteria" with no spec files and no "For the builder" section, since the
|
|
183
|
+
area's `CLAUDE.md` says how it is built. A small change that makes a
|
|
184
|
+
spec line false is the one exception ("Small changes" above). Neither
|
|
185
|
+
skill removes `spec` or adds it back once the owner removed it: both act
|
|
186
|
+
through the owner's GitHub account, so a label already decided is the
|
|
187
|
+
owner's call.
|
|
188
|
+
|
|
189
|
+
A spec tool, which `npx --no-install factory config get specs` names,
|
|
190
|
+
also keeps each Spec in the repository: `factory-build` starts it with
|
|
191
|
+
`npx --no-install factory specs new N` and folds it in with
|
|
192
|
+
`npx --no-install factory specs finish N`, in the same pull request.
|
|
193
|
+
`npx --no-install factory specs list` prints the specs the repository
|
|
194
|
+
keeps, its current description of what it does; a change to one starts
|
|
195
|
+
by reading it. With `specs: none` each of these says each ticket holds
|
|
196
|
+
its own spec, and the issue is the only copy. No skill, agent, rule, or
|
|
197
|
+
workflow runs a spec tool's own commands: the `factory specs` commands
|
|
198
|
+
reach it.
|
|
192
199
|
|
|
193
200
|
## Issues that wait on another
|
|
194
201
|
|
|
@@ -211,8 +218,8 @@ npx --no-install factory ticket blockers N
|
|
|
211
218
|
npx --no-install factory ticket unblock N --by M
|
|
212
219
|
```
|
|
213
220
|
|
|
214
|
-
`blockers` prints one line per ticket N waits on,
|
|
215
|
-
it is open. A ticket system without blockers says so: check with
|
|
221
|
+
`blockers` prints one line per ticket N waits on, as the ticket system
|
|
222
|
+
writes it, and whether it is open. A ticket system without blockers says so: check with
|
|
216
223
|
`npx --no-install factory ticket supports blockers`.
|
|
217
224
|
|
|
218
225
|
## Follow-ups
|
|
@@ -229,18 +236,20 @@ labeled `follow-up`, holding a checklist. A line leads with the file or
|
|
|
229
236
|
page it is about:
|
|
230
237
|
|
|
231
238
|
```
|
|
232
|
-
- [ ] <file or page>: <what is wrong, as a user or a maintainer sees it>. Found by <who> while building
|
|
239
|
+
- [ ] <file or page>: <what is wrong, as a user or a maintainer sees it>. Found by <who> while building <ticket>. <The rule it breaks, by its section in the guide that states it (an area's guide under "Rules by area" in CLAUDE.md, CLAUDE.md, or this file), or "Needs a decision: <the question>".>
|
|
233
240
|
```
|
|
234
241
|
|
|
235
242
|
It is added with the file and the rest of the line as two arguments, and
|
|
236
243
|
the script opens the issue when none is open:
|
|
237
244
|
|
|
238
245
|
```bash
|
|
239
|
-
npx --no-install factory follow-up FILE "What is wrong. Found by WHO while building
|
|
246
|
+
npx --no-install factory follow-up FILE "What is wrong. Found by WHO while building TICKET. The rule it breaks."
|
|
240
247
|
```
|
|
241
248
|
|
|
242
|
-
|
|
243
|
-
|
|
249
|
+
TICKET is the ticket as its system writes it, which
|
|
250
|
+
`npx --no-install factory ticket view N --field ref` prints, such as `#12`.
|
|
251
|
+
A reviewer that does not know the ticket writes `TICKET` as it stands, and
|
|
252
|
+
whoever appends the line fills it in.
|
|
244
253
|
|
|
245
254
|
A placeholder or tag name in issue or comment text, such as `<slug>` or
|
|
246
255
|
`<code>`, goes in backticks: GitHub drops an unknown tag and renders a
|
|
@@ -258,18 +267,19 @@ hook refuses the same in text sent to GitHub directly, as the
|
|
|
258
267
|
the line unchecked.
|
|
259
268
|
- A follow-up gets its own issue only when it would need the `spec` label,
|
|
260
269
|
because it adds or alters behavior a user can see, or would make a
|
|
261
|
-
line of `
|
|
262
|
-
own issue.
|
|
270
|
+
line of a spec `factory specs list` prints false. A request from the
|
|
271
|
+
owner is always its own issue.
|
|
263
272
|
- The `factory-resolve-conflicts` conflict stop keeps opening its own issue: which side
|
|
264
273
|
wins is the owner's decision, and nothing else records it.
|
|
265
274
|
|
|
266
275
|
The follow-ups issue builds as one branch and one pull request, one commit
|
|
267
276
|
per line, once the owner approves it, by moving its card to Ready or
|
|
268
|
-
telling a session to build it. The pull request closes it with
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
277
|
+
telling a session to build it. The pull request closes it with the line
|
|
278
|
+
`npx --no-install factory ticket link N` prints only when every line is
|
|
279
|
+
checked; otherwise it starts with the line
|
|
280
|
+
`npx --no-install factory ticket link N --part` prints, and the unchecked
|
|
281
|
+
lines wait there. The sync reads that line as a partial build, so any
|
|
282
|
+
other link to the follow-ups issue words it differently. It has no spec tool change. `factory-build` appends a line and
|
|
273
283
|
builds the issue; `factory-refine` refines it per line. Its lines can be
|
|
274
284
|
about anything, so the one pull request waits for the owner when any line
|
|
275
285
|
touches a file that does, and gets the fresh-agent trace ("Changing the
|
|
@@ -94,25 +94,25 @@ reporting a clean review. Never report a review as clean when none has run.
|
|
|
94
94
|
|
|
95
95
|
## 0a. The owner's review
|
|
96
96
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
OWNER_LOGIN=$(npx --no-install factory config get repository | cut -d/ -f1)
|
|
105
|
-
```
|
|
97
|
+
An approver, anyone whose account can write to the repository, reviews
|
|
98
|
+
pull requests too. Their comments are worked like the Claude reviewer's
|
|
99
|
+
findings, with two differences: a pushback on one stays open for an
|
|
100
|
+
approver to decide, and an approver's reply after a pushback is final.
|
|
101
|
+
Who is an approver is the code host's to say: `factory pr state` and
|
|
102
|
+
`factory pr review-pending` already keep only an approver's reviews and
|
|
103
|
+
turns, so no step here tests a name.
|
|
106
104
|
|
|
107
105
|
**Only reviews count:** inline comments, and the body of a submitted
|
|
108
106
|
review. A Conversation-tab comment that is not part of a review starts
|
|
109
107
|
nothing and is never acted on. Do not go by the review's state: agents open
|
|
110
|
-
pull requests through
|
|
111
|
-
author approve or request changes on their own pull request, so the
|
|
112
|
-
reviews are all
|
|
108
|
+
pull requests through an approver's account, and GitHub does not let an
|
|
109
|
+
author approve or request changes on their own pull request, so the
|
|
110
|
+
reviews of an approver who is the pull request's author are all
|
|
111
|
+
`COMMENTED`.
|
|
113
112
|
|
|
114
113
|
Every comment this skill posts contains `<!-- agent -->` (section 4), so a
|
|
115
|
-
comment from
|
|
114
|
+
comment without it, from an account those commands count, is an
|
|
115
|
+
approver's. Match with
|
|
116
116
|
"contains", not "ends with": an automatic footer can follow the marker.
|
|
117
117
|
|
|
118
118
|
### A run started by the owner's review
|
|
@@ -139,9 +139,10 @@ passed.
|
|
|
139
139
|
It prints the review's author and body, and each comment it left on a
|
|
140
140
|
line with its `id`, `replyTo`, `path`, `line`, and `body`.
|
|
141
141
|
|
|
142
|
-
3. **Nothing of
|
|
143
|
-
a review by someone
|
|
144
|
-
records each thread reply as a review under the
|
|
142
|
+
3. **Nothing of an approver's in it:** stop without changing anything. That
|
|
143
|
+
is a review by someone who is not an approver, or one of this skill's
|
|
144
|
+
own replies: GitHub records each thread reply as a review under the
|
|
145
|
+
account that posted it, with an
|
|
145
146
|
empty body and one comment carrying the marker. Otherwise work the
|
|
146
147
|
comments without the marker, and the body if it is non-empty and lacks
|
|
147
148
|
the marker.
|
|
@@ -162,7 +163,7 @@ passed.
|
|
|
162
163
|
4. Check out the pull request's branch, Dependabot's included. Read whether
|
|
163
164
|
it can merge as `factory-address-review` section 0 does, and if that is `dirty`
|
|
164
165
|
and the pull request is one the conflict sweep's queue admits, run "A
|
|
165
|
-
conflict with the default branch" in the `factory-resolve-conflicts` skill first, then work each comment as "Each
|
|
166
|
+
conflict with the default branch" in the `factory-resolve-conflicts` skill first, then work each comment as "Each approver comment"
|
|
166
167
|
below says. Run the gate ("Gate" under "A
|
|
167
168
|
conflict with the default branch" in that skill), commit, and push to that branch
|
|
168
169
|
only, never with force. **A push refused because the branch moved**
|
|
@@ -176,13 +177,13 @@ passed.
|
|
|
176
177
|
section 8, reporting as section 8 lays out. Otherwise no review is
|
|
177
178
|
coming: work the review threads that already exist, and end with the
|
|
178
179
|
same report. In this loop, section 1 works only the threads
|
|
179
|
-
`github-actions[bot]` opened;
|
|
180
|
+
`github-actions[bot]` opened; approver threads belong to the runs their
|
|
180
181
|
reviews started.
|
|
181
182
|
6. **Only the latest push's run goes on.** In step 5's loop only, before
|
|
182
183
|
working a Claude review and again before each push it makes, compare the pull request's head with your
|
|
183
184
|
last commit (`npx --no-install factory pr view N --field head`). If
|
|
184
185
|
another run has pushed since, stop: its push starts the next Claude
|
|
185
|
-
review, and that run works it, open threads included. A push of
|
|
186
|
+
review, and that run works it, open threads included. A push of approver
|
|
186
187
|
fixes in step 4 that is refused is still pulled and pushed again.
|
|
187
188
|
|
|
188
189
|
Each run works only its own review, and only the run that pushed last
|
|
@@ -197,19 +198,19 @@ This run never merges, enables auto-merge, marks a draft ready, or adds the
|
|
|
197
198
|
branch.
|
|
198
199
|
|
|
199
200
|
**Outside a run started by a review,** as in a local session working the
|
|
200
|
-
pull request, the
|
|
201
|
-
last comment is
|
|
202
|
-
review bodies submitted after the last Conversation comment carrying the
|
|
201
|
+
pull request, the approver comments to work are the unresolved threads
|
|
202
|
+
whose last comment is an approver's and lacks the marker, and the non-empty
|
|
203
|
+
approver review bodies submitted after the last Conversation comment carrying the
|
|
203
204
|
marker. A comment that also carries `<!-- conflict-fix -->`,
|
|
204
205
|
`conflict-stop`, or `<!-- session-handoff -->`, the `factory-resolve-conflicts` skill's
|
|
205
206
|
comment markers, does not count as that last comment, so a sweep's comment
|
|
206
|
-
does not hide an
|
|
207
|
-
not answer a review body. The report lists these as "
|
|
208
|
-
to answer", and marks an unresolved thread "
|
|
209
|
-
comment is
|
|
207
|
+
does not hide an approver's unanswered review body. Thread replies do not count there, since a reply on one thread does
|
|
208
|
+
not answer a review body. The report lists these as "approver review bodies
|
|
209
|
+
to answer", and marks an unresolved thread "approver's turn" when its last
|
|
210
|
+
comment is an approver's without the marker. Read a review body in full
|
|
210
211
|
with `npx --no-install factory pr review N ID`.
|
|
211
212
|
|
|
212
|
-
### Each
|
|
213
|
+
### Each approver comment
|
|
213
214
|
|
|
214
215
|
A comment with a `replyTo` is a reply in an existing thread: read
|
|
215
216
|
the whole thread first (`npx --no-install factory pr threads N --all`
|
|
@@ -223,19 +224,19 @@ to see whether it follows a pushback of yours.
|
|
|
223
224
|
- **Agreed:** fix it (section 3), push, reply with what changed and the
|
|
224
225
|
commit, and resolve the thread.
|
|
225
226
|
- **Disagreed:** reply once with the evidence, a quoted source, a failing
|
|
226
|
-
test, or the code, and leave the thread open. Never resolve an
|
|
227
|
+
test, or the code, and leave the thread open. Never resolve an approver
|
|
227
228
|
thread you did not fix, except as the next bullet says.
|
|
228
|
-
- **
|
|
229
|
+
- **An approver replied after your pushback.** That reply is final; do not
|
|
229
230
|
push back again.
|
|
230
231
|
- **It asks for the change:** make it, reply that you are following the
|
|
231
|
-
|
|
232
|
+
approver's call, with the commit, and resolve the thread.
|
|
232
233
|
- **It accepts the pushback:** reply that you are leaving the code as it
|
|
233
|
-
is, per
|
|
234
|
+
is, per that reply, and resolve the thread.
|
|
234
235
|
- **You cannot tell which:** ask in one line and leave it open.
|
|
235
236
|
- **A review body.** Handle each point in it the same way, and answer it in
|
|
236
237
|
the end comment (section 4); there is no thread to resolve.
|
|
237
238
|
|
|
238
|
-
|
|
239
|
+
Approver threads are outside section 6's round count and its escalation.
|
|
239
240
|
|
|
240
241
|
## 1. Collect
|
|
241
242
|
|
|
@@ -392,8 +393,9 @@ Never accept or reject from reading alone. Each finding gets evidence:
|
|
|
392
393
|
there, say so rather than reasoning from memory.
|
|
393
394
|
- **A claim about the codebase** gets a grep or a file read at the cited line.
|
|
394
395
|
- **A finding that would reverse a choice** also gets the recorded reason:
|
|
395
|
-
read the commit message, the pull request's body, and the
|
|
396
|
-
|
|
396
|
+
read the commit message, the pull request's body, and the Decisions of
|
|
397
|
+
each ticket `npx --no-install factory pr closes PR` prints, with
|
|
398
|
+
`npx --no-install factory ticket view N`, before accepting it. A session without the build context has only these. If
|
|
397
399
|
the finding conflicts with a recorded decision and the evidence does not
|
|
398
400
|
settle it, reply with both and leave the thread open for the owner.
|
|
399
401
|
|
|
@@ -425,7 +427,7 @@ the reasoning survives, and the user reads these instead of the transcript.
|
|
|
425
427
|
|
|
426
428
|
**Every comment this skill posts, a thread reply or a conversation comment,
|
|
427
429
|
contains `<!-- agent -->` on its own line.** That marker is how the next
|
|
428
|
-
run tells its own words from
|
|
430
|
+
run tells its own words from an approver's (section 0a). Put it at the end of
|
|
429
431
|
the body; an automatic footer may follow it.
|
|
430
432
|
|
|
431
433
|
```bash
|
|
@@ -446,9 +448,9 @@ npx --no-install factory pr resolve N COMMENT_ID
|
|
|
446
448
|
```
|
|
447
449
|
|
|
448
450
|
Resolve accepted and rejected threads alike, with one exception: **an
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
thread stays open for
|
|
451
|
+
approver thread is resolved only when you fixed it, or an approver
|
|
452
|
+
overruled or accepted your pushback** (section 0a). A pushback on an
|
|
453
|
+
approver thread stays open for an approver. GitHub has no "ignored" state:
|
|
452
454
|
a rejection is a reply carrying the evidence, followed by the same resolve.
|
|
453
455
|
Resolving without replying destroys the reasoning, which is the only reason
|
|
454
456
|
the user can audit the decision later.
|
|
@@ -506,9 +508,9 @@ other push: pull with
|
|
|
506
508
|
|
|
507
509
|
## 6. Two rounds, then escalate
|
|
508
510
|
|
|
509
|
-
|
|
510
|
-
escalation does not apply to them: an open
|
|
511
|
-
|
|
511
|
+
Approver threads (section 0a) are outside this count, and this section's
|
|
512
|
+
escalation does not apply to them: an open approver thread is already an
|
|
513
|
+
approver's to decide. A run started by the owner's review has no memory of
|
|
512
514
|
earlier sessions, so it counts rounds from the `claude-review sha=`
|
|
513
515
|
summaries of the commits it pushed itself.
|
|
514
516
|
|
|
@@ -550,7 +552,7 @@ again. Add whether the tests are good enough to make a swap verifiable.
|
|
|
550
552
|
First, note what this round of work cost, on the pull request:
|
|
551
553
|
|
|
552
554
|
```bash
|
|
553
|
-
npx --no-install factory
|
|
555
|
+
npx --no-install factory pr cost PR
|
|
554
556
|
```
|
|
555
557
|
|
|
556
558
|
It posts what the session spent at API list prices since its last note, or
|