@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.
Files changed (141) hide show
  1. package/.claude-plugin/plugin.json +5 -0
  2. package/LICENSE +21 -0
  3. package/README.md +135 -2
  4. package/actions/factory-agent/action.yml +218 -0
  5. package/agents/factory-test-reviewer.md +129 -0
  6. package/agents/factory-ticket-readiness.md +107 -0
  7. package/agents/factory-ui-reviewer.md +160 -0
  8. package/bin/factory.js +45 -0
  9. package/bin/launch.js +67 -0
  10. package/dist/board.d.mts +128 -0
  11. package/dist/board.mjs +456 -0
  12. package/dist/build.d.mts +18 -0
  13. package/dist/build.mjs +60 -0
  14. package/dist/cli.d.mts +17 -0
  15. package/dist/cli.mjs +264 -0
  16. package/dist/code-host/github.d.mts +118 -0
  17. package/dist/code-host/github.mjs +419 -0
  18. package/dist/code-host/index.d.mts +9 -0
  19. package/dist/code-host/index.mjs +18 -0
  20. package/dist/code-host/types.d.mts +205 -0
  21. package/dist/code-host/types.mjs +12 -0
  22. package/dist/config.d.mts +166 -0
  23. package/dist/config.mjs +548 -0
  24. package/dist/deps.d.mts +32 -0
  25. package/dist/deps.mjs +126 -0
  26. package/dist/doctor.d.mts +34 -0
  27. package/dist/doctor.mjs +188 -0
  28. package/dist/guard-commit.d.mts +41 -0
  29. package/dist/guard-commit.mjs +209 -0
  30. package/dist/guard-permission.d.mts +15 -0
  31. package/dist/guard-permission.mjs +52 -0
  32. package/dist/guard-ticket-text.d.mts +27 -0
  33. package/dist/guard-ticket-text.mjs +288 -0
  34. package/dist/guard.d.mts +4 -0
  35. package/dist/guard.mjs +37 -0
  36. package/dist/init.d.mts +58 -0
  37. package/dist/init.mjs +556 -0
  38. package/dist/lib/clock.d.mts +14 -0
  39. package/dist/lib/clock.mjs +36 -0
  40. package/dist/lib/gh.d.mts +28 -0
  41. package/dist/lib/gh.mjs +92 -0
  42. package/dist/lib/glob.d.mts +2 -0
  43. package/dist/lib/glob.mjs +41 -0
  44. package/dist/lib/pricing.d.mts +25 -0
  45. package/dist/lib/pricing.mjs +77 -0
  46. package/dist/lib/usage.d.mts +34 -0
  47. package/dist/lib/usage.mjs +128 -0
  48. package/dist/lib/work-status.d.mts +251 -0
  49. package/dist/lib/work-status.mjs +510 -0
  50. package/dist/merge-policy.d.mts +66 -0
  51. package/dist/merge-policy.mjs +146 -0
  52. package/dist/parts.d.mts +39 -0
  53. package/dist/parts.mjs +138 -0
  54. package/dist/poller.d.mts +61 -0
  55. package/dist/poller.mjs +247 -0
  56. package/dist/pr-watch.d.mts +45 -0
  57. package/dist/pr-watch.mjs +244 -0
  58. package/dist/pr.d.mts +65 -0
  59. package/dist/pr.mjs +571 -0
  60. package/dist/review-cost.d.mts +18 -0
  61. package/dist/review-cost.mjs +95 -0
  62. package/dist/review-tools.d.mts +5 -0
  63. package/dist/review-tools.mjs +46 -0
  64. package/dist/review-verdict.d.mts +50 -0
  65. package/dist/review-verdict.mjs +171 -0
  66. package/dist/reviewers.d.mts +54 -0
  67. package/dist/reviewers.mjs +312 -0
  68. package/dist/runner/github-actions.d.mts +12 -0
  69. package/dist/runner/github-actions.mjs +97 -0
  70. package/dist/runner/index.d.mts +9 -0
  71. package/dist/runner/index.mjs +22 -0
  72. package/dist/runner/types.d.mts +60 -0
  73. package/dist/runner/types.mjs +7 -0
  74. package/dist/session-start.d.mts +20 -0
  75. package/dist/session-start.mjs +115 -0
  76. package/dist/site/capture.d.mts +44 -0
  77. package/dist/site/capture.mjs +114 -0
  78. package/dist/site/measure.d.mts +83 -0
  79. package/dist/site/measure.mjs +225 -0
  80. package/dist/site/pages.d.mts +10 -0
  81. package/dist/site/pages.mjs +71 -0
  82. package/dist/site/pixels.d.mts +47 -0
  83. package/dist/site/pixels.mjs +157 -0
  84. package/dist/site/servers.d.mts +47 -0
  85. package/dist/site/servers.mjs +141 -0
  86. package/dist/site.d.mts +60 -0
  87. package/dist/site.mjs +341 -0
  88. package/dist/status.d.mts +100 -0
  89. package/dist/status.mjs +514 -0
  90. package/dist/sync.d.mts +59 -0
  91. package/dist/sync.mjs +292 -0
  92. package/dist/ticket.d.mts +61 -0
  93. package/dist/ticket.mjs +562 -0
  94. package/dist/tickets/github.d.mts +128 -0
  95. package/dist/tickets/github.mjs +491 -0
  96. package/dist/tickets/index.d.mts +15 -0
  97. package/dist/tickets/index.mjs +27 -0
  98. package/dist/tickets/transport.d.mts +42 -0
  99. package/dist/tickets/transport.mjs +158 -0
  100. package/dist/tickets/types.d.mts +191 -0
  101. package/dist/tickets/types.mjs +76 -0
  102. package/docs/builds.md +227 -0
  103. package/docs/cli.md +221 -0
  104. package/docs/configuration.md +809 -0
  105. package/docs/design.md +106 -0
  106. package/docs/developing.md +400 -0
  107. package/docs/existing-repo.md +138 -0
  108. package/docs/github/reference.md +288 -0
  109. package/docs/github/setup.md +312 -0
  110. package/docs/glossary.md +106 -0
  111. package/docs/limitations.md +115 -0
  112. package/docs/plugins.md +192 -0
  113. package/docs/quick-start.md +222 -0
  114. package/docs/removing.md +76 -0
  115. package/docs/skills.md +270 -0
  116. package/docs/updating.md +108 -0
  117. package/docs/workflow.md +195 -0
  118. package/package.json +67 -4
  119. package/poller.Dockerfile +21 -0
  120. package/review.md +170 -0
  121. package/rules.md +313 -0
  122. package/settings.schema.json +411 -0
  123. package/skills/factory-address-review/SKILL.md +547 -0
  124. package/skills/factory-address-review/patch-coverage.py +68 -0
  125. package/skills/factory-build/SKILL.md +412 -0
  126. package/skills/factory-deps/SKILL.md +185 -0
  127. package/skills/factory-design/SKILL.md +159 -0
  128. package/skills/factory-diagnose/SKILL.md +93 -0
  129. package/skills/factory-mutate/SKILL.md +76 -0
  130. package/skills/factory-refine/SKILL.md +417 -0
  131. package/skills/factory-resolve-conflicts/SKILL.md +235 -0
  132. package/workflows/factory-board-sync.yml +91 -0
  133. package/workflows/factory-build.yml +72 -0
  134. package/workflows/factory-check.yml +37 -0
  135. package/workflows/factory-claude-review.yml +133 -0
  136. package/workflows/factory-conflicts.yml +69 -0
  137. package/workflows/factory-deps-auto-merge.yml +43 -0
  138. package/workflows/factory-deps.yml +59 -0
  139. package/workflows/factory-merge-policy.yml +121 -0
  140. package/workflows/factory-review-verdict.yml +54 -0
  141. 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]}")