@davidbyoung/software-factory 0.0.0-stage → 0.1.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.
- package/.claude-plugin/plugin.json +5 -0
- package/LICENSE +21 -0
- package/README.md +135 -2
- package/actions/factory-agent/action.yml +218 -0
- package/agents/factory-test-reviewer.md +129 -0
- package/agents/factory-ticket-readiness.md +107 -0
- package/agents/factory-ui-reviewer.md +160 -0
- package/bin/factory.js +45 -0
- package/bin/launch.js +67 -0
- package/dist/board.d.mts +128 -0
- package/dist/board.mjs +456 -0
- package/dist/build.d.mts +18 -0
- package/dist/build.mjs +60 -0
- package/dist/cli.d.mts +17 -0
- package/dist/cli.mjs +264 -0
- package/dist/code-host/github.d.mts +118 -0
- package/dist/code-host/github.mjs +419 -0
- package/dist/code-host/index.d.mts +9 -0
- package/dist/code-host/index.mjs +18 -0
- package/dist/code-host/types.d.mts +205 -0
- package/dist/code-host/types.mjs +12 -0
- package/dist/config.d.mts +166 -0
- package/dist/config.mjs +548 -0
- package/dist/deps.d.mts +32 -0
- package/dist/deps.mjs +126 -0
- package/dist/doctor.d.mts +34 -0
- package/dist/doctor.mjs +188 -0
- package/dist/guard-commit.d.mts +41 -0
- package/dist/guard-commit.mjs +209 -0
- package/dist/guard-permission.d.mts +15 -0
- package/dist/guard-permission.mjs +52 -0
- package/dist/guard-ticket-text.d.mts +27 -0
- package/dist/guard-ticket-text.mjs +288 -0
- package/dist/guard.d.mts +4 -0
- package/dist/guard.mjs +37 -0
- package/dist/init.d.mts +58 -0
- package/dist/init.mjs +556 -0
- package/dist/lib/clock.d.mts +14 -0
- package/dist/lib/clock.mjs +36 -0
- package/dist/lib/gh.d.mts +28 -0
- package/dist/lib/gh.mjs +92 -0
- package/dist/lib/glob.d.mts +2 -0
- package/dist/lib/glob.mjs +41 -0
- package/dist/lib/pricing.d.mts +25 -0
- package/dist/lib/pricing.mjs +77 -0
- package/dist/lib/usage.d.mts +34 -0
- package/dist/lib/usage.mjs +128 -0
- package/dist/lib/work-status.d.mts +251 -0
- package/dist/lib/work-status.mjs +510 -0
- package/dist/merge-policy.d.mts +66 -0
- package/dist/merge-policy.mjs +146 -0
- package/dist/parts.d.mts +39 -0
- package/dist/parts.mjs +138 -0
- package/dist/poller.d.mts +61 -0
- package/dist/poller.mjs +247 -0
- package/dist/pr-watch.d.mts +45 -0
- package/dist/pr-watch.mjs +244 -0
- package/dist/pr.d.mts +65 -0
- package/dist/pr.mjs +571 -0
- package/dist/review-cost.d.mts +18 -0
- package/dist/review-cost.mjs +95 -0
- package/dist/review-tools.d.mts +5 -0
- package/dist/review-tools.mjs +46 -0
- package/dist/review-verdict.d.mts +50 -0
- package/dist/review-verdict.mjs +171 -0
- package/dist/reviewers.d.mts +54 -0
- package/dist/reviewers.mjs +312 -0
- package/dist/runner/github-actions.d.mts +12 -0
- package/dist/runner/github-actions.mjs +97 -0
- package/dist/runner/index.d.mts +9 -0
- package/dist/runner/index.mjs +22 -0
- package/dist/runner/types.d.mts +60 -0
- package/dist/runner/types.mjs +7 -0
- package/dist/session-start.d.mts +20 -0
- package/dist/session-start.mjs +115 -0
- package/dist/site/capture.d.mts +44 -0
- package/dist/site/capture.mjs +114 -0
- package/dist/site/measure.d.mts +83 -0
- package/dist/site/measure.mjs +225 -0
- package/dist/site/pages.d.mts +10 -0
- package/dist/site/pages.mjs +71 -0
- package/dist/site/pixels.d.mts +47 -0
- package/dist/site/pixels.mjs +157 -0
- package/dist/site/servers.d.mts +47 -0
- package/dist/site/servers.mjs +141 -0
- package/dist/site.d.mts +60 -0
- package/dist/site.mjs +341 -0
- package/dist/status.d.mts +100 -0
- package/dist/status.mjs +514 -0
- package/dist/sync.d.mts +59 -0
- package/dist/sync.mjs +292 -0
- package/dist/ticket.d.mts +61 -0
- package/dist/ticket.mjs +562 -0
- package/dist/tickets/github.d.mts +128 -0
- package/dist/tickets/github.mjs +491 -0
- package/dist/tickets/index.d.mts +15 -0
- package/dist/tickets/index.mjs +27 -0
- package/dist/tickets/transport.d.mts +42 -0
- package/dist/tickets/transport.mjs +158 -0
- package/dist/tickets/types.d.mts +191 -0
- package/dist/tickets/types.mjs +76 -0
- package/docs/builds.md +227 -0
- package/docs/cli.md +221 -0
- package/docs/configuration.md +809 -0
- package/docs/design.md +106 -0
- package/docs/developing.md +400 -0
- package/docs/existing-repo.md +138 -0
- package/docs/github/reference.md +288 -0
- package/docs/github/setup.md +312 -0
- package/docs/glossary.md +106 -0
- package/docs/limitations.md +115 -0
- package/docs/plugins.md +192 -0
- package/docs/quick-start.md +222 -0
- package/docs/removing.md +76 -0
- package/docs/skills.md +270 -0
- package/docs/updating.md +108 -0
- package/docs/workflow.md +195 -0
- package/package.json +67 -4
- package/poller.Dockerfile +21 -0
- package/review.md +170 -0
- package/rules.md +313 -0
- package/settings.schema.json +411 -0
- package/skills/factory-address-review/SKILL.md +547 -0
- package/skills/factory-address-review/patch-coverage.py +68 -0
- package/skills/factory-build/SKILL.md +412 -0
- package/skills/factory-deps/SKILL.md +185 -0
- package/skills/factory-design/SKILL.md +159 -0
- package/skills/factory-diagnose/SKILL.md +93 -0
- package/skills/factory-mutate/SKILL.md +76 -0
- package/skills/factory-refine/SKILL.md +417 -0
- package/skills/factory-resolve-conflicts/SKILL.md +235 -0
- package/workflows/factory-board-sync.yml +91 -0
- package/workflows/factory-build.yml +72 -0
- package/workflows/factory-check.yml +37 -0
- package/workflows/factory-claude-review.yml +133 -0
- package/workflows/factory-conflicts.yml +69 -0
- package/workflows/factory-deps-auto-merge.yml +43 -0
- package/workflows/factory-deps.yml +59 -0
- package/workflows/factory-merge-policy.yml +121 -0
- package/workflows/factory-review-verdict.yml +54 -0
- package/workflows/factory-review.yml +75 -0
|
@@ -0,0 +1,547 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: factory-address-review
|
|
3
|
+
description: Address a pull request's review until it can merge: the Claude review's threads and summary, the owner's comments, failed checks, patch coverage, and a conflict with main, each verified with a repro or a quoted source and answered on its thread. Use when asked to address, handle, or work the review on a pull request, after every push to a branch with an open pull request, and as the run a workflow starts for the owner's review.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Handling a pull request review
|
|
7
|
+
|
|
8
|
+
A Claude reviewer runs in GitHub Actions on every push to a pull request that is not a draft
|
|
9
|
+
(`.github/workflows/factory-claude-review.yml`, instructions in
|
|
10
|
+
`.github/factory-review.md`). It leaves inline review threads, some with
|
|
11
|
+
one-click ```suggestion blocks, and one summary comment per push. The point
|
|
12
|
+
of this skill is that the user does not have to relay messages between it
|
|
13
|
+
and you. You decide, you act, you record the decision on the thread, and you
|
|
14
|
+
report once at the end.
|
|
15
|
+
|
|
16
|
+
**The merge also needs `Review verdict` on the head commit.** A workflow
|
|
17
|
+
posts it from the marker at the end of each review summary: success only
|
|
18
|
+
when the review said ready. A push starts the next commit without one. When
|
|
19
|
+
a round ends with rejections only and nothing to push, the verdict stays at
|
|
20
|
+
the last review's failure, so ask for a fresh read of the same commit
|
|
21
|
+
(`npx --no-install factory pr review-again N`); the reviewer
|
|
22
|
+
reads your replies and posts a new verdict. Never add the `verdict: override`
|
|
23
|
+
label, never enable auto-merge, and never merge: the override is the
|
|
24
|
+
owner's alone, and the merge-policy workflow decides auto-merge.
|
|
25
|
+
|
|
26
|
+
**The repository will not merge with an unresolved thread.** Every thread
|
|
27
|
+
ends in one of three states, and only the first two are yours to reach:
|
|
28
|
+
|
|
29
|
+
- **Fixed**: you made the change, replied with what changed, and resolved it.
|
|
30
|
+
- **Rejected**: you disproved it, replied with the evidence, and resolved it.
|
|
31
|
+
GitHub has no "closed" or "ignored" state; a rejection is a resolved thread
|
|
32
|
+
whose reply carries the evidence.
|
|
33
|
+
- **Escalated**: left open for the user, with a reply saying why. See
|
|
34
|
+
section 6.
|
|
35
|
+
|
|
36
|
+
A finding is not an instruction. The reviewer reads the repository, but it
|
|
37
|
+
cannot run the code or open the source documents. Where it was measured,
|
|
38
|
+
automated review was wrong about a third of the time on content that cites
|
|
39
|
+
outside sources and close to always right on scripts. **Take the finding, design the
|
|
40
|
+
fix yourself.**
|
|
41
|
+
|
|
42
|
+
## The scripts
|
|
43
|
+
|
|
44
|
+
Everything here that reads or changes a pull request goes through
|
|
45
|
+
`npx --no-install factory pr`. It exits nonzero with the error when a read
|
|
46
|
+
fails: a failed read, never an empty answer.
|
|
47
|
+
|
|
48
|
+
## 0. Is there anything to review yet
|
|
49
|
+
|
|
50
|
+
**Started by the owner's review** ("the owner's review REVIEW_ID on #N",
|
|
51
|
+
as the workflow that listens for it says) is the run under "A run started by the owner's review" in section 0a: it
|
|
52
|
+
works the owner's comments, pushes, and then calls this skill from here.
|
|
53
|
+
|
|
54
|
+
The reviewer runs on pull requests, not branches. One command reads
|
|
55
|
+
everything sections 0 to 1b need: the open pull request for the branch,
|
|
56
|
+
its mergeable state, the `Claude review` run and summary for the head
|
|
57
|
+
commit, the owner's review bodies still to answer, the unresolved review
|
|
58
|
+
threads, every check, and the Codecov comment.
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
npx --no-install factory pr state # the branch's pull request
|
|
62
|
+
npx --no-install factory pr state N --wait
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`no open pull request for this branch` means no review exists and none is
|
|
66
|
+
coming. Say that in one line and stop; do not open one, because a PR is
|
|
67
|
+
the user's call.
|
|
68
|
+
|
|
69
|
+
**Then check for a conflict with main,** before anything else, from the
|
|
70
|
+
report's first lines. If `mergeable` is `dirty` and the pull request is based on main, not a draft, not
|
|
71
|
+
Dependabot's, and not from a fork, run "A conflict with main" in the
|
|
72
|
+
`factory-resolve-conflicts` skill first, including in a session woken by the desktop
|
|
73
|
+
app, then carry on here: a fix is a push, so wait for its review as
|
|
74
|
+
below. After a stop, no review is coming, so work the review threads that
|
|
75
|
+
already exist and name the stop in the report. GitHub computes the state
|
|
76
|
+
lazily, so the script reads `unknown` again, up to 5 times, 10 seconds
|
|
77
|
+
apart; still `unknown` counts as no conflict.
|
|
78
|
+
|
|
79
|
+
After a push, wait for the review of that commit, not an older one. Its
|
|
80
|
+
summary ends with `<!-- claude-review sha=HEAD_SHA -->`, and the report
|
|
81
|
+
reads only that commit's run and summary. With `--wait` it reports once
|
|
82
|
+
the head's review has posted, or its run has failed, and every check has
|
|
83
|
+
finished; a run in GitHub Actions, which nothing can wake later,
|
|
84
|
+
uses that, and a local one is woken by
|
|
85
|
+
`watch-pr` instead. Read the summary in full with
|
|
86
|
+
`npx --no-install factory pr comment-view ID`, by the ID
|
|
87
|
+
the report names.
|
|
88
|
+
|
|
89
|
+
A run that failed or was cancelled has posted nothing; say so rather than
|
|
90
|
+
reporting a clean review. Never report a review as clean when none has run.
|
|
91
|
+
|
|
92
|
+
## 0a. The owner's review
|
|
93
|
+
|
|
94
|
+
The repository owner reviews pull requests too. Their comments are worked
|
|
95
|
+
like the Claude reviewer's findings, with two differences: a pushback on
|
|
96
|
+
one stays open for the owner to decide, and the owner's reply after a
|
|
97
|
+
pushback is final. The owner is the repository owner's login, read rather
|
|
98
|
+
than hard-coded: the part of the repository's name before the slash.
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
OWNER_LOGIN=$(npx --no-install factory config get repository | cut -d/ -f1)
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
**Only reviews count:** inline comments, and the body of a submitted
|
|
105
|
+
review. A Conversation-tab comment that is not part of a review starts
|
|
106
|
+
nothing and is never acted on. Do not go by the review's state: agents open
|
|
107
|
+
pull requests through the owner's account, and GitHub does not let an
|
|
108
|
+
author approve or request changes on their own pull request, so the owner's
|
|
109
|
+
reviews are all `COMMENTED`.
|
|
110
|
+
|
|
111
|
+
Every comment this skill posts contains `<!-- agent -->` (section 4), so a
|
|
112
|
+
comment from `OWNER_LOGIN` without it is the owner's. Match with
|
|
113
|
+
"contains", not "ends with": an automatic footer can follow the marker.
|
|
114
|
+
|
|
115
|
+
### A run started by the owner's review
|
|
116
|
+
|
|
117
|
+
The run's setup, and the commands it uses, are as the `factory-resolve-conflicts`
|
|
118
|
+
skill's opening says: the workflow has set the run up, so a run does no
|
|
119
|
+
setup of its own, and tickets go through `factory ticket` and a pull
|
|
120
|
+
request through `factory pr`.
|
|
121
|
+
|
|
122
|
+
The workflow starts one run for each submitted review and passes the pull
|
|
123
|
+
request and the review's ID ("the owner's review REVIEW_ID on #N"). It
|
|
124
|
+
ran `factory pr review-pending N REVIEW_ID` first, which is steps 1 to 3
|
|
125
|
+
below without the hand-off to a watching local session, and starts a
|
|
126
|
+
session only when it exits 0. Read what it read again, since time has
|
|
127
|
+
passed.
|
|
128
|
+
|
|
129
|
+
1. **Closed or merged:** stop.
|
|
130
|
+
2. **Read that review** and its comments:
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
npx --no-install factory pr review N REVIEW_ID
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
It prints the review's author and body, and each comment it left on a
|
|
137
|
+
line with its `id`, `replyTo`, `path`, `line`, and `body`.
|
|
138
|
+
|
|
139
|
+
3. **Nothing of the owner's in it:** stop without changing anything. That is
|
|
140
|
+
a review by someone else, or one of this skill's own replies: GitHub
|
|
141
|
+
records each thread reply as a review under the owner's account, with an
|
|
142
|
+
empty body and one comment carrying the marker. Otherwise work the
|
|
143
|
+
comments without the marker, and the body if it is non-empty and lacks
|
|
144
|
+
the marker.
|
|
145
|
+
**A local session is watching:** the pull request's body has a
|
|
146
|
+
`<!-- session-watching: TIME -->` mark less than an hour old. That session
|
|
147
|
+
has the build context and answers the review, so change nothing else. This
|
|
148
|
+
run is the only one this review gets, so post one comment before stopping,
|
|
149
|
+
so a session that has gone does not lose the review silently:
|
|
150
|
+
|
|
151
|
+
> A local session was watching this pull request at TIME and should answer
|
|
152
|
+
> this review. If it has not within an hour, submit the review again.
|
|
153
|
+
>
|
|
154
|
+
> `<!-- agent -->`
|
|
155
|
+
> `<!-- session-handoff -->`
|
|
156
|
+
|
|
157
|
+
An older mark is from a session that has gone, so go on.
|
|
158
|
+
|
|
159
|
+
4. Check out the pull request's branch, Dependabot's included. Read whether
|
|
160
|
+
it can merge as `factory-address-review` section 0 does, and if that is `dirty`
|
|
161
|
+
and the pull request is one the conflict sweep's queue admits, run "A
|
|
162
|
+
conflict with main" in the `factory-resolve-conflicts` skill first, then work each comment as "Each owner comment"
|
|
163
|
+
below says. Run the gate ("Gate" under "A
|
|
164
|
+
conflict with main" in that skill), commit, and push to that branch
|
|
165
|
+
only, never with force. **A push refused because the branch moved**
|
|
166
|
+
means another run, working another review, pushed first: pull with
|
|
167
|
+
`git pull --no-rebase`, run the gate again, and push. Then reply and
|
|
168
|
+
resolve.
|
|
169
|
+
5. **When the Claude review runs on the push,** that is, the pull request
|
|
170
|
+
is not a draft, not Dependabot's, not from a fork
|
|
171
|
+
(`factory-claude-review.yml`), and not `dirty`, run this skill from section 0, past its note on a run started by the owner's review: wait for the review of the
|
|
172
|
+
push, and work it as a whole, its preamble through
|
|
173
|
+
section 8, reporting as section 8 lays out. Otherwise no review is
|
|
174
|
+
coming: work the review threads that already exist, and end with the
|
|
175
|
+
same report. In this loop, section 1 works only the threads
|
|
176
|
+
`github-actions[bot]` opened; owner threads belong to the runs their
|
|
177
|
+
reviews started.
|
|
178
|
+
6. **Only the latest push's run goes on.** In step 5's loop only, before
|
|
179
|
+
working a Claude review and again before each push it makes, compare the pull request's head with your
|
|
180
|
+
last commit (`npx --no-install factory pr view N --field head`). If
|
|
181
|
+
another run has pushed since, stop: its push starts the next Claude
|
|
182
|
+
review, and that run works it, open threads included. A push of owner
|
|
183
|
+
fixes in step 4 that is refused is still pulled and pushed again.
|
|
184
|
+
|
|
185
|
+
Each run works only its own review, and only the run that pushed last
|
|
186
|
+
works the Claude review, so two runs never take the same thread, and no
|
|
187
|
+
lock is needed.
|
|
188
|
+
|
|
189
|
+
If the gate or the push fails, reply on the affected threads with the
|
|
190
|
+
error and leave them open.
|
|
191
|
+
|
|
192
|
+
This run never merges, enables auto-merge, marks a draft ready, or adds the
|
|
193
|
+
`verdict: override` label, and it pushes only to the pull request's
|
|
194
|
+
branch.
|
|
195
|
+
|
|
196
|
+
**Outside a run started by a review,** as in a local session working the
|
|
197
|
+
pull request, the owner comments to work are the unresolved threads whose
|
|
198
|
+
last comment is the owner's and lacks the marker, and the non-empty owner
|
|
199
|
+
review bodies submitted after the last Conversation comment carrying the
|
|
200
|
+
marker. A comment that also carries `<!-- conflict-fix -->`,
|
|
201
|
+
`conflict-stop`, or `<!-- session-handoff -->`, the `factory-resolve-conflicts` skill's
|
|
202
|
+
comment markers, does not count as that last comment, so a sweep's comment
|
|
203
|
+
does not hide an owner's unanswered review body. Thread replies do not count there, since a reply on one thread does
|
|
204
|
+
not answer a review body. The report lists these as "owner review bodies
|
|
205
|
+
to answer", and marks an unresolved thread "owner's turn" when its last
|
|
206
|
+
comment is the owner's without the marker. Read a review body in full
|
|
207
|
+
with `npx --no-install factory pr review N ID`.
|
|
208
|
+
|
|
209
|
+
### Each owner comment
|
|
210
|
+
|
|
211
|
+
A comment with a `replyTo` is a reply in an existing thread: read
|
|
212
|
+
the whole thread first (`npx --no-install factory pr threads N --all`
|
|
213
|
+
lists every thread with its comments, resolved or not),
|
|
214
|
+
to see whether it follows a pushback of yours.
|
|
215
|
+
|
|
216
|
+
- **No pushback yet.** Verify it as section 2 verifies a finding. Comments
|
|
217
|
+
on outdated lines and suggestion blocks get the same treatment; say in
|
|
218
|
+
the reply if the code has moved, and apply a suggestion through the gate
|
|
219
|
+
as section 1 says.
|
|
220
|
+
- **Agreed:** fix it (section 3), push, reply with what changed and the
|
|
221
|
+
commit, and resolve the thread.
|
|
222
|
+
- **Disagreed:** reply once with the evidence, a quoted source, a failing
|
|
223
|
+
test, or the code, and leave the thread open. Never resolve an owner
|
|
224
|
+
thread you did not fix, except as the next bullet says.
|
|
225
|
+
- **The owner replied after your pushback.** That reply is final; do not
|
|
226
|
+
push back again.
|
|
227
|
+
- **It asks for the change:** make it, reply that you are following the
|
|
228
|
+
owner's call, with the commit, and resolve the thread.
|
|
229
|
+
- **It accepts the pushback:** reply that you are leaving the code as it
|
|
230
|
+
is, per the owner's reply, and resolve the thread.
|
|
231
|
+
- **You cannot tell which:** ask in one line and leave it open.
|
|
232
|
+
- **A review body.** Handle each point in it the same way, and answer it in
|
|
233
|
+
the end comment (section 4); there is no thread to resolve.
|
|
234
|
+
|
|
235
|
+
Owner threads are outside section 6's round count and its escalation.
|
|
236
|
+
|
|
237
|
+
## 1. Collect
|
|
238
|
+
|
|
239
|
+
The reviewer posts as `github-actions[bot]`: its threads are the review
|
|
240
|
+
threads that account opened, and its summaries are the issue comments ending
|
|
241
|
+
in `<!-- claude-review sha=… -->`. The inline comment tool strips HTML
|
|
242
|
+
comments, so the threads carry no marker of their own.
|
|
243
|
+
|
|
244
|
+
The unresolved threads, each with its comments in full:
|
|
245
|
+
|
|
246
|
+
```bash
|
|
247
|
+
npx --no-install factory pr threads N
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
Work every thread it lists, whoever opened it. Keep each thread's
|
|
251
|
+
`commentId`, its first comment: you need it to reply and resolve.
|
|
252
|
+
|
|
253
|
+
**The summary is part of the review.** Read the latest one in full. It holds
|
|
254
|
+
findings that are not about specific lines, the reviewer's verdict, and any
|
|
255
|
+
earlier rejection it still disagrees with. Those have no thread, so handle
|
|
256
|
+
them exactly as you would a thread and record the verdict in your end
|
|
257
|
+
comment. A Low is the exception: take it when it is quick and right, leave
|
|
258
|
+
it otherwise, and say which in one line of the end comment. A Low never
|
|
259
|
+
causes a push on its own, and one left undone is not a finding.
|
|
260
|
+
|
|
261
|
+
**A suggestion block is a proposal, not a patch to apply blind.** Verify it
|
|
262
|
+
like any finding. If it is right as written, apply the same change locally,
|
|
263
|
+
run the gate, and commit it yourself rather than pressing "Commit
|
|
264
|
+
suggestion", so the change passes the gate before it lands.
|
|
265
|
+
|
|
266
|
+
## 1a. CI checks
|
|
267
|
+
|
|
268
|
+
A review that says ready is not a ready pull request. Wait until **every**
|
|
269
|
+
check on the head commit has finished, not only the review:
|
|
270
|
+
|
|
271
|
+
```bash
|
|
272
|
+
npx --no-install factory pr state N --wait
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
In a local session, `npx --no-install factory pr watch N` (see `.claude/factory/rules.md`) already
|
|
276
|
+
wakes the session on a failure and when every check has finished, so this
|
|
277
|
+
wait is not needed.
|
|
278
|
+
|
|
279
|
+
Never report a pull request ready while a check is pending or failing, and
|
|
280
|
+
never report a check you have not seen finish.
|
|
281
|
+
|
|
282
|
+
For each failed check, read the failing job's log and find the failure:
|
|
283
|
+
|
|
284
|
+
```bash
|
|
285
|
+
npx --no-install factory pr failed N
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
It prints each failed job's name and the end of its log, and what a failed
|
|
289
|
+
check wrote about itself.
|
|
290
|
+
|
|
291
|
+
Then reproduce it locally before deciding anything, with the `factory-diagnose`
|
|
292
|
+
skill when the cause is not plain from the log. A failure gets the same
|
|
293
|
+
treatment as a review finding, with evidence:
|
|
294
|
+
|
|
295
|
+
- **Caused by this pull request**: fix it on this branch, as part of the
|
|
296
|
+
round.
|
|
297
|
+
- **Already on the base branch**, a flaky test or a break that landed
|
|
298
|
+
earlier: it is still a bug, and it still blocks the merge. Reproduce it,
|
|
299
|
+
for a flake with a repeated run, find the race and fix it on its own
|
|
300
|
+
branch, so the fix lands on the base branch and not only here. Say so in
|
|
301
|
+
the report.
|
|
302
|
+
- **Not reproducible and not understood**: escalate. Do not guess.
|
|
303
|
+
|
|
304
|
+
**Never re-run a failed check to get it green** without a diagnosed cause,
|
|
305
|
+
and never make a check optional to get past it. A check that passes on the
|
|
306
|
+
second try is a flake that will fail someone else.
|
|
307
|
+
|
|
308
|
+
## 1b. Coverage report
|
|
309
|
+
|
|
310
|
+
If the repository reports to Codecov, read its checks in the same pass,
|
|
311
|
+
including when the review did not run: a failed review still leaves
|
|
312
|
+
coverage to judge. Its bot comments on the PR only when coverage moved
|
|
313
|
+
(`codecov.yml`), so a missing comment is normal, not a failed upload.
|
|
314
|
+
|
|
315
|
+
The report names the Codecov comment's ID, if there is one, and lists
|
|
316
|
+
`codecov/patch` and `codecov/project` among the checks. Read the comment
|
|
317
|
+
with `npx --no-install factory pr comment-view ID`.
|
|
318
|
+
|
|
319
|
+
The comment's red cross on patch coverage is not the status check. Say which
|
|
320
|
+
one failed, if either did. Neither check is required by the `main` ruleset,
|
|
321
|
+
so a red one blocks nothing on its own; project coverage is gated by the
|
|
322
|
+
floors in `vitest.config.ts` inside the CI check, and patch coverage by the
|
|
323
|
+
verdicts below.
|
|
324
|
+
|
|
325
|
+
Neither the checks nor the comment name lines. Get them from the same lcov
|
|
326
|
+
report CI uploads: run the project's coverage command, then
|
|
327
|
+
|
|
328
|
+
```bash
|
|
329
|
+
python3 .claude/skills/factory-address-review/patch-coverage.py [base] [lcov]
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
which prints each uncovered (`MISS`) or partly covered (`PART`) line in the
|
|
333
|
+
branch's diff. The defaults are `origin/main` and `coverage/lcov.info`. Its
|
|
334
|
+
total should roughly match Codecov's; if it does not, the local run differs
|
|
335
|
+
from CI, and that has to be settled before any verdict.
|
|
336
|
+
|
|
337
|
+
Each line gets a verdict, as a review finding does:
|
|
338
|
+
|
|
339
|
+
- **Worth a test**: behavior someone could break without any test noticing.
|
|
340
|
+
A handler no unit or end-to-end test drives, a branch with a user-visible
|
|
341
|
+
outcome.
|
|
342
|
+
- **Fine as-is**, with the reason, which must be one of these:
|
|
343
|
+
- Covered by an end-to-end test, which unit coverage does not count. Name
|
|
344
|
+
the test.
|
|
345
|
+
- Only runs at build time or on the server, such as a React server
|
|
346
|
+
snapshot or a static route handler, and the build exercises it.
|
|
347
|
+
- Declarative, like a route's `export const dynamic`, where the build fails
|
|
348
|
+
without it.
|
|
349
|
+
- Defensive and unreachable by construction. Say what guarantees it.
|
|
350
|
+
|
|
351
|
+
"It's only a few lines" is not a reason. Neither is the percentage: the bar
|
|
352
|
+
is whether a regression would go unnoticed, not the number.
|
|
353
|
+
|
|
354
|
+
A test written for a coverage line follows the same rules as any other. It
|
|
355
|
+
asserts behavior, not that the line ran, and it fails when the code it covers
|
|
356
|
+
is broken, which the `factory-mutate` skill proves for a test written after
|
|
357
|
+
the code. A test that only executes a line pads the number and locks nothing
|
|
358
|
+
in.
|
|
359
|
+
|
|
360
|
+
There are no threads to resolve. Put the verdicts in the end-of-review PR
|
|
361
|
+
comment beside any summary-only findings, grouped as fixed and fine as-is.
|
|
362
|
+
|
|
363
|
+
## 2. Verify before acting
|
|
364
|
+
|
|
365
|
+
Never accept or reject from reading alone. Each finding gets evidence:
|
|
366
|
+
|
|
367
|
+
- **A claim about behavior** gets a repro. Build the smallest input that
|
|
368
|
+
should trigger it and run the real code. Nearly every true finding on this
|
|
369
|
+
repo was confirmed in under ten lines, and more than one _looked_ obviously
|
|
370
|
+
right and was wrong.
|
|
371
|
+
- **A claim about a document** gets the passage quoted from the document.
|
|
372
|
+
If the project keeps extracted sources locally, read them; if they are not
|
|
373
|
+
there, say so rather than reasoning from memory.
|
|
374
|
+
- **A claim about the codebase** gets a grep or a file read at the cited line.
|
|
375
|
+
- **A finding that would reverse a choice** also gets the recorded reason:
|
|
376
|
+
read the commit message, the pull request's body, and the issue's Decisions
|
|
377
|
+
before accepting it. A session without the build context has only these. If
|
|
378
|
+
the finding conflicts with a recorded decision and the evidence does not
|
|
379
|
+
settle it, reply with both and leave the thread open for the owner.
|
|
380
|
+
|
|
381
|
+
Watch your own search as hard as the claim. A finding was once "confirmed" by
|
|
382
|
+
a grep whose window was too small, and a regulation was declared truncated
|
|
383
|
+
when the search string was wrong. If evidence contradicts the finding, that is
|
|
384
|
+
a rejection, not a puzzle to work around.
|
|
385
|
+
|
|
386
|
+
## 3. Fix, and prove the fix
|
|
387
|
+
|
|
388
|
+
- Write the smallest change that resolves the underlying defect, not the one
|
|
389
|
+
the reviewer described.
|
|
390
|
+
- Add a regression test and **prove it can fail**, as the area's rules for
|
|
391
|
+
tests say ("Rules by area" in `CLAUDE.md`): red before the fix and green after, or the fix mutated back. A test
|
|
392
|
+
that cannot fail has not locked anything in. This has caught two tests on
|
|
393
|
+
this repo that passed either way.
|
|
394
|
+
- Re-run the real workload, not just the fixture: for the extractor that means
|
|
395
|
+
the real corpus, and the output should be unchanged unless the fix was
|
|
396
|
+
meant to change it.
|
|
397
|
+
- Then run the project's own pre-commit gate, whatever its CLAUDE.md or
|
|
398
|
+
contributing docs define: formatter, type or static check, linter, tests
|
|
399
|
+
with coverage, build. Do not invent a gate, and do not skip one.
|
|
400
|
+
|
|
401
|
+
## 4. Record the decision on the thread
|
|
402
|
+
|
|
403
|
+
Every thread gets a reply before it is resolved. The reply is the only place
|
|
404
|
+
the reasoning survives, and the user reads these instead of the transcript.
|
|
405
|
+
|
|
406
|
+
**Every comment this skill posts, a thread reply or a conversation comment,
|
|
407
|
+
contains `<!-- agent -->` on its own line.** That marker is how the next
|
|
408
|
+
run tells its own words from the owner's (section 0a). Put it at the end of
|
|
409
|
+
the body; an automatic footer may follow it.
|
|
410
|
+
|
|
411
|
+
```bash
|
|
412
|
+
npx --no-install factory pr reply N COMMENT_ID --body-file reply.md
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
The script adds the marker when the body lacks it.
|
|
416
|
+
|
|
417
|
+
- **Accepted**: what changed, in one or two sentences, plus the test that now
|
|
418
|
+
covers it. Say so when the fix differs from what was suggested, and why.
|
|
419
|
+
- **Rejected**: the evidence that disproves it, quoted. A rejection with no
|
|
420
|
+
citation is not a rejection, it is a disagreement.
|
|
421
|
+
|
|
422
|
+
Then resolve it:
|
|
423
|
+
|
|
424
|
+
```bash
|
|
425
|
+
npx --no-install factory pr resolve N COMMENT_ID
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
Resolve accepted and rejected threads alike, with one exception: **an
|
|
429
|
+
owner thread is resolved only when you fixed it, the owner overruled your
|
|
430
|
+
pushback, or the owner accepted it** (section 0a). A pushback on an owner
|
|
431
|
+
thread stays open for the owner. GitHub has no "ignored" state:
|
|
432
|
+
a rejection is a reply carrying the evidence, followed by the same resolve.
|
|
433
|
+
Resolving without replying destroys the reasoning, which is the only reason
|
|
434
|
+
the user can audit the decision later.
|
|
435
|
+
|
|
436
|
+
**Never resolve a thread you neither fixed nor disproved.** If a finding is
|
|
437
|
+
real but out of scope, or you cannot settle it either way, say so in the reply
|
|
438
|
+
and leave it open: that is an escalation (section 6), and the pull request
|
|
439
|
+
cannot merge until the user decides it.
|
|
440
|
+
|
|
441
|
+
For summary-only findings there is no thread, so collect their verdicts and
|
|
442
|
+
post one PR comment at the end:
|
|
443
|
+
|
|
444
|
+
```bash
|
|
445
|
+
npx --no-install factory pr comment N --body-file comment.md
|
|
446
|
+
```
|
|
447
|
+
|
|
448
|
+
## 5. Commit and push
|
|
449
|
+
|
|
450
|
+
Signing is whatever git config says; do not name a key here, and do not
|
|
451
|
+
change the signing setup to get a commit through. If signing blocks, that is
|
|
452
|
+
the thing to report, not to work around. A GPG key whose pinentry opens a
|
|
453
|
+
dialog will hang an unattended commit forever rather than failing, which is
|
|
454
|
+
why this machine signs with SSH.
|
|
455
|
+
|
|
456
|
+
Confirm the signature landed rather than assuming:
|
|
457
|
+
|
|
458
|
+
```bash
|
|
459
|
+
git log --format='%G? %h %s' -1 # G or U, never N or E
|
|
460
|
+
```
|
|
461
|
+
|
|
462
|
+
`N` means nothing was signed. `E` usually means the verifying side cannot
|
|
463
|
+
check it, most often an allowed-signers file that does not list the key this
|
|
464
|
+
machine signs with, which is a local verification gap rather than a bad
|
|
465
|
+
commit. After pushing, confirm the host agrees:
|
|
466
|
+
|
|
467
|
+
```bash
|
|
468
|
+
npx --no-install factory pr unverified N
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
It prints each commit the code host does not show as signed, with the
|
|
472
|
+
reason, and nothing when it shows them all.
|
|
473
|
+
|
|
474
|
+
`factory pr ready` enforces the same check: when git is set to sign, it
|
|
475
|
+
refuses to mark a pull request ready while GitHub shows one of its commits
|
|
476
|
+
as not verified.
|
|
477
|
+
|
|
478
|
+
One commit per coherent change, message describing the defect rather than the
|
|
479
|
+
reviewer. Push to the PR branch.
|
|
480
|
+
|
|
481
|
+
A sweep and a live session can push to the same branch, so a push can be
|
|
482
|
+
refused because the branch moved. A conflict fix follows "Commit and
|
|
483
|
+
push" under "A conflict with main" in the `factory-resolve-conflicts` skill. Every
|
|
484
|
+
other push: pull with
|
|
485
|
+
`git pull --no-rebase`, run the gate again, and push.
|
|
486
|
+
|
|
487
|
+
## 6. Two rounds, then escalate
|
|
488
|
+
|
|
489
|
+
Owner threads (section 0a) are outside this count, and this section's
|
|
490
|
+
escalation does not apply to them: an open owner thread is already the
|
|
491
|
+
owner's to decide. A run started by the owner's review has no memory of
|
|
492
|
+
earlier sessions, so it counts rounds from the `claude-review sha=`
|
|
493
|
+
summaries of the commits it pushed itself.
|
|
494
|
+
|
|
495
|
+
A round is one review you work: you reply to and resolve its threads, push
|
|
496
|
+
your fixes, and the push triggers the next review. Handle **at most two
|
|
497
|
+
rounds**. When the third review arrives:
|
|
498
|
+
|
|
499
|
+
- **Agreement**: its summary says ready to merge, it opened no new threads,
|
|
500
|
+
nothing is open, and every CI check on the head commit has passed. You and
|
|
501
|
+
the reviewer agree; report that the pull request is ready.
|
|
502
|
+
- **Anything else**: new threads, a finding repeated after your fix, or a
|
|
503
|
+
rejection the reviewer still disputes. Stop. Do not reply, fix or resolve.
|
|
504
|
+
Escalate.
|
|
505
|
+
|
|
506
|
+
Escalate sooner, at any round, when:
|
|
507
|
+
|
|
508
|
+
- the same finding returns after a fix, which means the fix was wrong
|
|
509
|
+
- a finding is real but you cannot settle it either way with evidence
|
|
510
|
+
- a fix needs a new dependency
|
|
511
|
+
- the three-strikes rule below fires
|
|
512
|
+
- a finding would change behavior the user chose deliberately
|
|
513
|
+
|
|
514
|
+
To escalate, leave the threads open and give the user, for each one, the
|
|
515
|
+
reviewer's position, yours, and the evidence on both sides. The pull request
|
|
516
|
+
cannot merge until they decide, which is the point. If they side with you,
|
|
517
|
+
the `verdict: override` label is how they pass the verdict for this commit, and
|
|
518
|
+
resolving the escalated threads is theirs too.
|
|
519
|
+
|
|
520
|
+
## 7. Three strikes on one unit
|
|
521
|
+
|
|
522
|
+
The three-strikes rule, "Stepping back from a rabbit hole" in
|
|
523
|
+
`.claude/factory/rules.md`, applies here too: when one
|
|
524
|
+
function or file has taken three or more rounds of corrective work for the
|
|
525
|
+
same class of defect, stop and write the comparison it asks for before fixing
|
|
526
|
+
again. Add whether the tests are good enough to make a swap verifiable.
|
|
527
|
+
|
|
528
|
+
## 8. Report once
|
|
529
|
+
|
|
530
|
+
First, note what this round of work cost, on the pull request:
|
|
531
|
+
|
|
532
|
+
```bash
|
|
533
|
+
npx --no-install factory ticket cost PR
|
|
534
|
+
```
|
|
535
|
+
|
|
536
|
+
It posts what the session spent at API list prices since its last note, or
|
|
537
|
+
since it started, and the board sync adds it to the issue's Cost. It
|
|
538
|
+
exits 0 even when the cost cannot be measured, so it never holds up the
|
|
539
|
+
report.
|
|
540
|
+
|
|
541
|
+
A table of thread, verdict and evidence: fixed, rejected or escalated. Then
|
|
542
|
+
the summary-only findings, and the coverage lines, in the same form. Then
|
|
543
|
+
any conflict with main: which pull request it was with, which files, and
|
|
544
|
+
whether it was fixed (with the merge commit) or stopped (with why, and the
|
|
545
|
+
issue opened). A sweep lists every pull request it read as `skip`, with
|
|
546
|
+
why, `fixed`, or `stopped`. Then what was committed and pushed, which round this was, and what is still open
|
|
547
|
+
and why. Name everything you resolved as rejected, so the user can reopen it.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""Lines a branch adds or changes that its tests leave uncovered.
|
|
3
|
+
|
|
4
|
+
Codecov's PR comment names files and counts, not lines. This reads the same
|
|
5
|
+
lcov report CI uploads and keeps only the lines in the diff against the base.
|
|
6
|
+
|
|
7
|
+
python3 patch-coverage.py [base] [lcov]
|
|
8
|
+
|
|
9
|
+
Run the project's coverage command first. Defaults: origin/main and
|
|
10
|
+
coverage/lcov.info. MISS is a line never run; PART is a line with a branch
|
|
11
|
+
never taken.
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
import os
|
|
15
|
+
import re
|
|
16
|
+
import subprocess
|
|
17
|
+
import sys
|
|
18
|
+
|
|
19
|
+
base = sys.argv[1] if len(sys.argv) > 1 else "origin/main"
|
|
20
|
+
lcov = sys.argv[2] if len(sys.argv) > 2 else "coverage/lcov.info"
|
|
21
|
+
|
|
22
|
+
coverage = {}
|
|
23
|
+
current = None
|
|
24
|
+
for line in open(lcov):
|
|
25
|
+
line = line.strip()
|
|
26
|
+
if line.startswith("SF:"):
|
|
27
|
+
current = os.path.relpath(line[3:])
|
|
28
|
+
coverage[current] = {"miss": set(), "part": set()}
|
|
29
|
+
elif line.startswith("DA:"):
|
|
30
|
+
number, hits = line[3:].split(",")[:2]
|
|
31
|
+
if hits == "0":
|
|
32
|
+
coverage[current]["miss"].add(int(number))
|
|
33
|
+
elif line.startswith("BRDA:"):
|
|
34
|
+
number, _, _, taken = line[5:].split(",")
|
|
35
|
+
if taken in ("0", "-"):
|
|
36
|
+
coverage[current]["part"].add(int(number))
|
|
37
|
+
|
|
38
|
+
diff = subprocess.run(
|
|
39
|
+
["git", "diff", "-U0", f"{base}...HEAD"],
|
|
40
|
+
capture_output=True,
|
|
41
|
+
text=True,
|
|
42
|
+
check=True,
|
|
43
|
+
).stdout
|
|
44
|
+
changed = {}
|
|
45
|
+
path = None
|
|
46
|
+
for line in diff.splitlines():
|
|
47
|
+
if line.startswith("+++ "):
|
|
48
|
+
path = line[6:] if line.startswith("+++ b/") else None
|
|
49
|
+
if path:
|
|
50
|
+
changed[path] = set()
|
|
51
|
+
hunk = re.match(r"@@ .* \+(\d+)(?:,(\d+))? @@", line)
|
|
52
|
+
if hunk and path:
|
|
53
|
+
start, count = int(hunk[1]), int(hunk[2] or 1)
|
|
54
|
+
changed[path].update(range(start, start + count))
|
|
55
|
+
|
|
56
|
+
for path, lines in sorted(changed.items()):
|
|
57
|
+
report = coverage.get(path)
|
|
58
|
+
if not report:
|
|
59
|
+
continue
|
|
60
|
+
missed = report["miss"] & lines
|
|
61
|
+
partial = (report["part"] & lines) - missed
|
|
62
|
+
if not missed and not partial:
|
|
63
|
+
continue
|
|
64
|
+
source = open(path).read().splitlines()
|
|
65
|
+
print(f"=== {path}")
|
|
66
|
+
for number in sorted(missed | partial):
|
|
67
|
+
kind = "MISS" if number in missed else "PART"
|
|
68
|
+
print(f"{kind} {number}: {source[number - 1].strip()[:110]}")
|