@davidbyoung/software-factory 0.1.2 → 0.1.4
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/README.md +20 -20
- package/actions/factory-agent/action.yml +1 -1
- package/agents/factory-e2e-reviewer.md +102 -0
- package/agents/factory-test-reviewer.md +26 -64
- package/agents/factory-ticket-readiness.md +14 -6
- package/dist/agent/claude-code.d.mts +3 -0
- package/dist/agent/claude-code.mjs +89 -0
- package/dist/agent/index.d.mts +2 -0
- package/dist/agent/index.mjs +5 -0
- package/dist/board.mjs +1 -1
- package/dist/cli.mjs +46 -4
- package/dist/code-host/github-setup.d.mts +5 -0
- package/dist/code-host/github-setup.mjs +133 -0
- package/dist/code-host/github.mjs +4 -0
- package/dist/code-host/index.d.mts +1 -1
- package/dist/code-host/index.mjs +2 -1
- package/dist/code-host/types.d.mts +2 -0
- package/dist/commands.d.mts +16 -0
- package/dist/commands.mjs +129 -0
- package/dist/config.d.mts +87 -20
- package/dist/config.mjs +344 -89
- package/dist/deps.d.mts +7 -4
- package/dist/deps.mjs +20 -9
- package/dist/doctor.d.mts +9 -16
- package/dist/doctor.mjs +71 -68
- package/dist/explain.d.mts +4 -0
- package/dist/explain.mjs +174 -0
- package/dist/guard-commit.d.mts +7 -2
- package/dist/guard-commit.mjs +58 -21
- package/dist/init.d.mts +12 -14
- package/dist/init.mjs +194 -136
- package/dist/lib/default-branch.d.mts +35 -0
- package/dist/lib/default-branch.mjs +117 -0
- package/dist/lib/has-command.d.mts +5 -0
- package/dist/lib/has-command.mjs +8 -0
- package/dist/lib/listed.d.mts +2 -0
- package/dist/lib/listed.mjs +4 -0
- package/dist/lib/refined-check.d.mts +7 -0
- package/dist/lib/refined-check.mjs +76 -0
- package/dist/lib/work-status.d.mts +12 -2
- package/dist/lib/work-status.mjs +14 -3
- package/dist/parts.d.mts +18 -15
- package/dist/parts.mjs +15 -43
- package/dist/patch-coverage.d.mts +13 -0
- package/dist/patch-coverage.mjs +73 -0
- package/dist/poller.d.mts +20 -3
- package/dist/poller.mjs +62 -15
- package/dist/pr-watch.d.mts +3 -2
- package/dist/pr-watch.mjs +22 -5
- package/dist/pr.mjs +34 -2
- package/dist/remove.d.mts +11 -0
- package/dist/remove.mjs +156 -0
- package/dist/runner/github-actions.d.mts +1 -1
- package/dist/runner/github-actions.mjs +12 -0
- package/dist/runner/index.d.mts +1 -1
- package/dist/runner/index.mjs +2 -1
- package/dist/runner/setup.d.mts +2 -0
- package/dist/runner/setup.mjs +22 -0
- package/dist/runner/types.d.mts +3 -0
- package/dist/runner/types.mjs +0 -2
- package/dist/session-start.d.mts +23 -13
- package/dist/session-start.mjs +56 -44
- package/dist/setup.d.mts +98 -0
- package/dist/setup.mjs +3 -0
- package/dist/site/servers.d.mts +6 -2
- package/dist/site/servers.mjs +14 -9
- package/dist/site.mjs +2 -2
- package/dist/status.d.mts +4 -4
- package/dist/status.mjs +8 -7
- package/dist/sync.d.mts +26 -2
- package/dist/sync.mjs +177 -13
- package/dist/ticket.mjs +19 -1
- package/dist/tickets/github-setup.d.mts +2 -0
- package/dist/tickets/github-setup.mjs +50 -0
- package/dist/tickets/github.mjs +0 -2
- package/dist/tickets/index.mjs +2 -1
- package/dist/tickets/transport.mjs +1 -3
- package/dist/tickets/types.mjs +0 -2
- package/dist/tool-names.d.mts +11 -0
- package/dist/tool-names.mjs +20 -0
- package/dist/tools.d.mts +56 -0
- package/dist/tools.mjs +76 -0
- package/docs/builds.md +111 -59
- package/docs/cli.md +106 -69
- package/docs/configuration.md +489 -171
- package/docs/design.md +18 -5
- package/docs/developing.md +179 -73
- package/docs/existing-repo.md +25 -12
- package/docs/github/by-hand.md +334 -0
- package/docs/github/reference.md +76 -67
- package/docs/github/setup.md +105 -286
- package/docs/glossary.md +18 -7
- package/docs/limitations.md +39 -12
- package/docs/plugins.md +305 -56
- package/docs/quick-start.md +85 -100
- package/docs/removing.md +37 -17
- package/docs/skills.md +121 -62
- package/docs/updating.md +150 -9
- package/docs/workflow.md +23 -19
- package/package.json +1 -1
- package/poller.Dockerfile +10 -18
- package/review.md +20 -11
- package/rules.md +36 -30
- package/settings.schema.json +313 -69
- package/skills/factory-address-review/SKILL.md +50 -30
- package/skills/factory-build/SKILL.md +76 -23
- package/skills/factory-deps/SKILL.md +46 -21
- package/skills/factory-design/SKILL.md +17 -8
- package/skills/factory-diagnose/SKILL.md +22 -20
- package/skills/factory-mutate/SKILL.md +38 -24
- package/skills/factory-refine/SKILL.md +55 -31
- package/skills/factory-resolve-conflicts/SKILL.md +76 -34
- package/skills/factory-trace/SKILL.md +80 -0
- package/workflows/factory-build.yml +6 -5
- package/workflows/factory-conflicts.yml +8 -8
- package/workflows/factory-deps-auto-merge.yml +3 -2
- package/workflows/factory-deps.yml +1 -1
- package/workflows/factory-poller.yml +46 -0
- package/workflows/factory-review.yml +1 -1
- package/skills/factory-address-review/patch-coverage.py +0 -68
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
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
|
|
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 the default branch, 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
4
|
---
|
|
5
5
|
|
|
6
6
|
# Handling a pull request review
|
|
@@ -45,6 +45,9 @@ Everything here that reads or changes a pull request goes through
|
|
|
45
45
|
`npx --no-install factory pr`. It exits nonzero with the error when a read
|
|
46
46
|
fails: a failed read, never an empty answer.
|
|
47
47
|
|
|
48
|
+
The default branch's name is what `npx --no-install factory default-branch`
|
|
49
|
+
prints. A command below writes it as DEFAULT.
|
|
50
|
+
|
|
48
51
|
## 0. Is there anything to review yet
|
|
49
52
|
|
|
50
53
|
**Started by the owner's review** ("the owner's review REVIEW_ID on #N",
|
|
@@ -55,7 +58,7 @@ The reviewer runs on pull requests, not branches. One command reads
|
|
|
55
58
|
everything sections 0 to 1b need: the open pull request for the branch,
|
|
56
59
|
its mergeable state, the `Claude review` run and summary for the head
|
|
57
60
|
commit, the owner's review bodies still to answer, the unresolved review
|
|
58
|
-
threads, every check, and the
|
|
61
|
+
threads, every check, and the coverage service's comment.
|
|
59
62
|
|
|
60
63
|
```bash
|
|
61
64
|
npx --no-install factory pr state # the branch's pull request
|
|
@@ -66,9 +69,9 @@ npx --no-install factory pr state N --wait
|
|
|
66
69
|
coming. Say that in one line and stop; do not open one, because a PR is
|
|
67
70
|
the user's call.
|
|
68
71
|
|
|
69
|
-
**Then check for a conflict with
|
|
70
|
-
report's first lines. If `mergeable` is `dirty` and the pull request is based on
|
|
71
|
-
Dependabot's, and not from a fork, run "A conflict with
|
|
72
|
+
**Then check for a conflict with the default branch,** before anything else, from the
|
|
73
|
+
report's first lines. If `mergeable` is `dirty` and the pull request is based on the default branch, not a draft, not
|
|
74
|
+
Dependabot's, and not from a fork, run "A conflict with the default branch" in the
|
|
72
75
|
`factory-resolve-conflicts` skill first, including in a session woken by the desktop
|
|
73
76
|
app, then carry on here: a fix is a push, so wait for its review as
|
|
74
77
|
below. After a stop, no review is coming, so work the review threads that
|
|
@@ -159,9 +162,9 @@ passed.
|
|
|
159
162
|
4. Check out the pull request's branch, Dependabot's included. Read whether
|
|
160
163
|
it can merge as `factory-address-review` section 0 does, and if that is `dirty`
|
|
161
164
|
and the pull request is one the conflict sweep's queue admits, run "A
|
|
162
|
-
conflict with
|
|
165
|
+
conflict with the default branch" in the `factory-resolve-conflicts` skill first, then work each comment as "Each owner comment"
|
|
163
166
|
below says. Run the gate ("Gate" under "A
|
|
164
|
-
conflict with
|
|
167
|
+
conflict with the default branch" in that skill), commit, and push to that branch
|
|
165
168
|
only, never with force. **A push refused because the branch moved**
|
|
166
169
|
means another run, working another review, pushed first: pull with
|
|
167
170
|
`git pull --no-rebase`, run the gate again, and push. Then reply and
|
|
@@ -307,32 +310,47 @@ second try is a flake that will fail someone else.
|
|
|
307
310
|
|
|
308
311
|
## 1b. Coverage report
|
|
309
312
|
|
|
313
|
+
Coverage is read from the settings, under `commands.coverage`: the command
|
|
314
|
+
that measures it, and where its lcov report lands.
|
|
315
|
+
|
|
316
|
+
```bash
|
|
317
|
+
npx --no-install factory config get commands.coverage.run
|
|
318
|
+
npx --no-install factory config get commands.coverage.report
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
**Skip this whole section when they print `none`,** a coverage service's
|
|
322
|
+
checks included: the settings name no coverage command, so there are no
|
|
323
|
+
lines to judge. A repository that reports to a coverage service sets
|
|
324
|
+
`commands.coverage` to get its verdicts.
|
|
325
|
+
|
|
310
326
|
If the repository reports to Codecov, read its checks in the same pass,
|
|
311
327
|
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
|
-
|
|
328
|
+
coverage to judge. Its bot comments on the PR only when coverage moved,
|
|
329
|
+
so a missing comment is normal, not a failed upload.
|
|
314
330
|
|
|
315
|
-
The report names the
|
|
316
|
-
|
|
331
|
+
The report names the bot's comment's ID, if there is one, and lists the
|
|
332
|
+
service's patch and project checks among the checks. Read the comment
|
|
317
333
|
with `npx --no-install factory pr comment-view ID`.
|
|
318
334
|
|
|
319
335
|
The comment's red cross on patch coverage is not the status check. Say which
|
|
320
|
-
one failed, if either did.
|
|
321
|
-
|
|
322
|
-
floors
|
|
323
|
-
verdicts below.
|
|
336
|
+
one failed, if either did. Unless the default branch's ruleset requires
|
|
337
|
+
them, a red one blocks nothing on its own; project coverage is gated by
|
|
338
|
+
whatever floors the coverage command enforces inside the CI check, and
|
|
339
|
+
patch coverage by the verdicts below.
|
|
324
340
|
|
|
325
341
|
Neither the checks nor the comment name lines. Get them from the same lcov
|
|
326
|
-
report CI uploads: run the
|
|
342
|
+
report CI uploads: run the coverage command, the first of the two above,
|
|
343
|
+
then
|
|
327
344
|
|
|
328
345
|
```bash
|
|
329
|
-
|
|
346
|
+
npx --no-install factory pr uncovered origin/DEFAULT REPORT
|
|
330
347
|
```
|
|
331
348
|
|
|
332
349
|
which prints each uncovered (`MISS`) or partly covered (`PART`) line in the
|
|
333
|
-
branch's diff.
|
|
334
|
-
total should roughly match
|
|
335
|
-
from CI, and that has to be settled
|
|
350
|
+
branch's diff. REPORT is the report's path, the second of the two above.
|
|
351
|
+
Its total should roughly match the coverage service's, where there is one;
|
|
352
|
+
if it does not, the local run differs from CI, and that has to be settled
|
|
353
|
+
before any verdict.
|
|
336
354
|
|
|
337
355
|
Each line gets a verdict, as a review finding does:
|
|
338
356
|
|
|
@@ -342,9 +360,9 @@ Each line gets a verdict, as a review finding does:
|
|
|
342
360
|
- **Fine as-is**, with the reason, which must be one of these:
|
|
343
361
|
- Covered by an end-to-end test, which unit coverage does not count. Name
|
|
344
362
|
the test.
|
|
345
|
-
- Only runs at build time or on the server, such as a
|
|
346
|
-
|
|
347
|
-
- Declarative, like a
|
|
363
|
+
- Only runs at build time or on the server, such as a static route
|
|
364
|
+
handler, and the build exercises it.
|
|
365
|
+
- Declarative, like a setting a route exports, where the build fails
|
|
348
366
|
without it.
|
|
349
367
|
- Defensive and unreachable by construction. Say what guarantees it.
|
|
350
368
|
|
|
@@ -353,8 +371,9 @@ is whether a regression would go unnoticed, not the number.
|
|
|
353
371
|
|
|
354
372
|
A test written for a coverage line follows the same rules as any other. It
|
|
355
373
|
asserts behavior, not that the line ran, and it fails when the code it covers
|
|
356
|
-
is broken, which the
|
|
357
|
-
|
|
374
|
+
is broken, which the prover, the skill
|
|
375
|
+
`npx --no-install factory plugins prover` prints, proves for a test written
|
|
376
|
+
after the code. A test that only executes a line pads the number and locks nothing
|
|
358
377
|
in.
|
|
359
378
|
|
|
360
379
|
There are no threads to resolve. Put the verdicts in the end-of-review PR
|
|
@@ -394,9 +413,10 @@ a rejection, not a puzzle to work around.
|
|
|
394
413
|
- Re-run the real workload, not just the fixture: for the extractor that means
|
|
395
414
|
the real corpus, and the output should be unchanged unless the fix was
|
|
396
415
|
meant to change it.
|
|
397
|
-
- Then run the
|
|
398
|
-
|
|
399
|
-
|
|
416
|
+
- Then run the gate, `npx --no-install factory gate`: the commands the
|
|
417
|
+
settings list under `commands.gate`, such as a formatter, a type or
|
|
418
|
+
static check, a linter, and the tests. Do not invent a gate, and do not
|
|
419
|
+
skip one.
|
|
400
420
|
|
|
401
421
|
## 4. Record the decision on the thread
|
|
402
422
|
|
|
@@ -480,7 +500,7 @@ reviewer. Push to the PR branch.
|
|
|
480
500
|
|
|
481
501
|
A sweep and a live session can push to the same branch, so a push can be
|
|
482
502
|
refused because the branch moved. A conflict fix follows "Commit and
|
|
483
|
-
push" under "A conflict with
|
|
503
|
+
push" under "A conflict with the default branch" in the `factory-resolve-conflicts` skill. Every
|
|
484
504
|
other push: pull with
|
|
485
505
|
`git pull --no-rebase`, run the gate again, and push.
|
|
486
506
|
|
|
@@ -540,7 +560,7 @@ report.
|
|
|
540
560
|
|
|
541
561
|
A table of thread, verdict and evidence: fixed, rejected or escalated. Then
|
|
542
562
|
the summary-only findings, and the coverage lines, in the same form. Then
|
|
543
|
-
any conflict with
|
|
563
|
+
any conflict with the default branch: which pull request it was with, which files, and
|
|
544
564
|
whether it was fixed (with the merge commit) or stopped (with why, and the
|
|
545
565
|
issue opened). A sweep lists every pull request it read as `skip`, with
|
|
546
566
|
why, `fixed`, or `stopped`. Then what was committed and pushed, which round this was, and what is still open
|
|
@@ -14,13 +14,19 @@ and every pull request's conversation through `factory pr`, so the skill
|
|
|
14
14
|
works whatever the ticket system. A command that cannot read exits
|
|
15
15
|
nonzero with the error: that is a failed read, never an empty answer.
|
|
16
16
|
|
|
17
|
+
Every command a build runs is the settings' own: the gate, one test, an
|
|
18
|
+
end-to-end spec, and the spec check each have a `factory` command below
|
|
19
|
+
that runs what `.claude/factory.yaml` lists under `commands` and `specs`.
|
|
20
|
+
The default branch's name is what `npx --no-install factory default-branch`
|
|
21
|
+
prints, and the commands below write it as DEFAULT.
|
|
22
|
+
|
|
17
23
|
## How a build starts
|
|
18
24
|
|
|
19
25
|
- **Local:** the owner tells a session to work an issue by number. The
|
|
20
26
|
card stays where it is until the claim moves it.
|
|
21
27
|
|
|
22
28
|
- **GitHub Actions:** the owner moves the issue's card to Ready on the
|
|
23
|
-
board, and the
|
|
29
|
+
board, and the poller posts a start comment and dispatches
|
|
24
30
|
"Factory build" with the issue's number; or a person runs
|
|
25
31
|
`npx --no-install factory build N`, or "Run workflow" on the Actions
|
|
26
32
|
tab. The two are the same run. The run's prompt says so. There is no
|
|
@@ -74,6 +80,16 @@ live, and prints `not live; posted nothing` otherwise, so it never ends a
|
|
|
74
80
|
newer session's claim. A dirty tree in step 1 is a pause for a live user,
|
|
75
81
|
not a stop.
|
|
76
82
|
|
|
83
|
+
**Right after `claimed`, and before the branch,** check that the settings
|
|
84
|
+
name a gate:
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
npx --no-install factory config get commands.gate
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
When it prints nothing, stop as above, saying `commands.gate` is not set,
|
|
91
|
+
so the build would have no way to check its work.
|
|
92
|
+
|
|
77
93
|
**Before opening the pull request,** check the claim once more:
|
|
78
94
|
|
|
79
95
|
```bash
|
|
@@ -151,8 +167,9 @@ counts only for an issue that has:
|
|
|
151
167
|
- the `follow-up` label, since the follow-ups issue's unchecked lines are
|
|
152
168
|
its criteria.
|
|
153
169
|
|
|
154
|
-
Without either, run
|
|
155
|
-
|
|
170
|
+
Without either, run the refiner, the skill
|
|
171
|
+
`npx --no-install factory plugins refiner` prints, and stop: no claim, and
|
|
172
|
+
nothing to release. Do not guess at what content should say or how a page
|
|
156
173
|
should behave.
|
|
157
174
|
|
|
158
175
|
Otherwise, claim it now ("The claim"), then read on.
|
|
@@ -170,11 +187,24 @@ Otherwise, claim it now ("The claim"), then read on.
|
|
|
170
187
|
- **Approved while a comment round waits on the owner:** the newest
|
|
171
188
|
refinement marker on the issue is `<!-- work-status: waiting -->`.
|
|
172
189
|
Approval means the round's defaults stand, along with the owner's
|
|
173
|
-
replies. After the claim,
|
|
174
|
-
no
|
|
175
|
-
|
|
190
|
+
replies. After the claim, first invoke the refiner, the skill
|
|
191
|
+
`npx --no-install factory plugins refiner` prints, with the Skill tool,
|
|
192
|
+
giving it the issue's number and the words "approved while
|
|
193
|
+
waiting: fold the owner's replies into the body, post no marker". For
|
|
194
|
+
`factory-refine` that is its steps 4 and 5: it folds the replies in and
|
|
195
|
+
reads the result for readiness. Then check that the body is one a build
|
|
196
|
+
can read:
|
|
197
|
+
|
|
198
|
+
```bash
|
|
199
|
+
npx --no-install factory ticket refined N --check
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
It prints `sound` and posts nothing. When it prints what the body is
|
|
203
|
+
missing instead, release the claim and stop, with its output in the
|
|
204
|
+
report. If a reply raises a new decision, or the read finds a
|
|
176
205
|
question only the owner can answer, comment it on the issue, release
|
|
177
206
|
the claim, and stop.
|
|
207
|
+
|
|
178
208
|
- **Already done, or no longer true:** say so with the evidence, release
|
|
179
209
|
the claim, and leave the issue open for the owner to close.
|
|
180
210
|
|
|
@@ -189,20 +219,20 @@ step 2 with the proposal and spec delta only, and step 4.
|
|
|
189
219
|
|
|
190
220
|
First, `git status --short`. If it shows anything, stop and ask the user
|
|
191
221
|
whether to commit it, on the current branch or on a new branch of its own if
|
|
192
|
-
the current one is
|
|
222
|
+
the current one is the default branch, or to stash it with `git stash -u`. A plain
|
|
193
223
|
`git stash` leaves untracked files behind. A switch carries
|
|
194
224
|
uncommitted changes onto the new branch, where the issue's commit would sweep
|
|
195
225
|
them into its PR, and refuses outright when a changed file differs between
|
|
196
226
|
the branches.
|
|
197
227
|
|
|
198
|
-
Then, from the latest origin
|
|
228
|
+
Then, from the latest default branch on `origin`, named for the issue:
|
|
199
229
|
|
|
200
230
|
```bash
|
|
201
231
|
git fetch origin
|
|
202
|
-
git switch -c issue-N-short-slug origin/
|
|
232
|
+
git switch -c issue-N-short-slug origin/DEFAULT
|
|
203
233
|
```
|
|
204
234
|
|
|
205
|
-
If the branch you left has commits not on origin/
|
|
235
|
+
If the branch you left has commits not on `origin/DEFAULT`, name it in the
|
|
206
236
|
report, so that work is not lost.
|
|
207
237
|
|
|
208
238
|
## 2. Create the change from the issue (`spec`, or a Spec section)
|
|
@@ -237,7 +267,7 @@ validates and archives a change without `design.md` or `tasks.md`.
|
|
|
237
267
|
Then check that every Spec line is exactly one scenario and every
|
|
238
268
|
scenario is a Spec line. If one does not map, stop and comment on the
|
|
239
269
|
issue with the line and why, rather than rewording it to fit. Run the
|
|
240
|
-
spec check
|
|
270
|
+
spec check, `npx --no-install factory specs check`, and commit the
|
|
241
271
|
change on its own.
|
|
242
272
|
|
|
243
273
|
## 3. Build it
|
|
@@ -247,9 +277,17 @@ Read the `CLAUDE.md` for the area first ("Rules by area" in `CLAUDE.md`).
|
|
|
247
277
|
**A builder plug-in:** list them with
|
|
248
278
|
`npx --no-install factory plugins builder`, which prints each one's
|
|
249
279
|
labels. When the issue carries one of a builder's labels, invoke that skill
|
|
250
|
-
with the Skill tool to build it, in place of the steps below
|
|
251
|
-
|
|
252
|
-
|
|
280
|
+
with the Skill tool to build it, in place of the steps below up to the
|
|
281
|
+
reviewers. The reviewers still run on what it built, the test reviewers
|
|
282
|
+
and the repository's own, and so does everything after them. Which
|
|
283
|
+
reviewers those are is decided by the change's own path: a small change's
|
|
284
|
+
by "Small changes" in `.claude/factory/rules.md`, content the repository
|
|
285
|
+
reviews by what changed by that path in `CLAUDE.md`, and anything else by
|
|
286
|
+
the items below. A reviewer
|
|
287
|
+
the builder's report shows it already ran is not run again: its line in
|
|
288
|
+
the pull request is the skip line "already run by the builder". What the
|
|
289
|
+
builder's report says goes in the pull request body at step 6, where the
|
|
290
|
+
owner reads it before merging.
|
|
253
291
|
|
|
254
292
|
**Content the repository reviews by what changed:** when `CLAUDE.md` gives
|
|
255
293
|
a kind of content its own path by what changed in it, an edit to that
|
|
@@ -262,11 +300,15 @@ content follows that path.
|
|
|
262
300
|
and say why in the pull request.
|
|
263
301
|
- Write the test first, where there is a defect to reproduce or a behavior
|
|
264
302
|
to add, and watch it fail before making the change, as the area's rules
|
|
265
|
-
for tests say ("Rules by area" in `CLAUDE.md`).
|
|
303
|
+
for tests say ("Rules by area" in `CLAUDE.md`). One test runs alone with
|
|
304
|
+
`npx --no-install factory test-one FILE NAME`.
|
|
266
305
|
- A small change takes the path in "Small changes" in
|
|
267
306
|
`.claude/factory/rules.md` instead of the next two items.
|
|
268
|
-
- Prove each new test can fail, by its red run or the
|
|
269
|
-
|
|
307
|
+
- Prove each new test can fail, by its red run or the prover, the skill
|
|
308
|
+
`npx --no-install factory plugins prover` prints, and have each test
|
|
309
|
+
reviewer, the agents `npx --no-install factory plugins test-reviewer`
|
|
310
|
+
prints, read them: one listed with `files` only when the change touches
|
|
311
|
+
a file that matches them.
|
|
270
312
|
- **The repository's own reviewers** are listed by
|
|
271
313
|
`npx --no-install factory plugins reviewer`, each with its
|
|
272
314
|
`files`. A reviewer is considered when a file the branch changed matches
|
|
@@ -288,7 +330,7 @@ content follows that path.
|
|
|
288
330
|
Verify before archiving: for every scenario in the change's specs, name
|
|
289
331
|
the test that exercises it, in which file, and run it. A scenario with no
|
|
290
332
|
test gets one now; a scenario whose test cannot fail (its red run before
|
|
291
|
-
the change shows, or
|
|
333
|
+
the change shows, or the prover) is not verified. Record the mapping in the pull request.
|
|
292
334
|
|
|
293
335
|
Then fold the change into the specs, as the last commit before the pull
|
|
294
336
|
request:
|
|
@@ -297,15 +339,26 @@ request:
|
|
|
297
339
|
DO_NOT_TRACK=1 npx --no-install openspec archive issue-N-short-slug --yes
|
|
298
340
|
```
|
|
299
341
|
|
|
300
|
-
Then run the spec check
|
|
342
|
+
Then run the spec check, `npx --no-install factory specs check`.
|
|
301
343
|
|
|
302
344
|
## 5. Gate, commit, push
|
|
303
345
|
|
|
304
|
-
Run the gate
|
|
346
|
+
Run the gate:
|
|
347
|
+
|
|
348
|
+
```bash
|
|
349
|
+
npx --no-install factory gate
|
|
350
|
+
```
|
|
351
|
+
|
|
352
|
+
It runs each command under `commands.gate` in the settings, in order, and
|
|
353
|
+
stops at the first that fails. When it says `commands.gate is not set`,
|
|
354
|
+
stop: a build cannot finish until the settings name a gate.
|
|
305
355
|
|
|
306
|
-
Run the end-to-end specs the change added or changed
|
|
307
|
-
|
|
308
|
-
|
|
356
|
+
Run the end-to-end specs the change added or changed. Where
|
|
357
|
+
`npx --no-install factory config get commands.end-to-end` prints a
|
|
358
|
+
command, run each with `npx --no-install factory end-to-end FILE`, and a
|
|
359
|
+
new one ten times, with `--times 10` after FILE. Where it prints `none`,
|
|
360
|
+
run them the way the repository's `CLAUDE.md` says, or say there is no
|
|
361
|
+
end-to-end suite. CI runs the full suite on the draft (step 6).
|
|
309
362
|
Commit and push as "Branching, pushing, and review" in
|
|
310
363
|
`.claude/factory/rules.md` describes: one commit per coherent change,
|
|
311
364
|
describing the defect or the feature, not the issue number alone.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: factory-deps
|
|
3
|
-
description: Move every open Dependabot pull request one step closer to merged: resolve conflicts with
|
|
3
|
+
description: Move every open Dependabot pull request one step closer to merged: resolve conflicts with the default branch, fix failing CI, do a major bump's migration, and open an issue for anything it cannot fix. Use when asked to look after, unstick, or fix Dependabot pull requests, and from the workflow that runs it.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Shepherding Dependabot pull requests
|
|
@@ -13,10 +13,22 @@ never turns it on or merges anything: the owner reads a major's migration,
|
|
|
13
13
|
and every update of the factory, before it lands.
|
|
14
14
|
|
|
15
15
|
Every command below goes through `factory deps`, `factory ticket`, or
|
|
16
|
-
`factory pr`.
|
|
16
|
+
`factory pr`. The default branch's name is what
|
|
17
|
+
`npx --no-install factory default-branch` prints, and the commands below
|
|
18
|
+
write it as DEFAULT.
|
|
17
19
|
|
|
18
20
|
## 0. The queue, and each one's state
|
|
19
21
|
|
|
22
|
+
First, check that the settings name a gate:
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npx --no-install factory config get commands.gate
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
When it prints nothing, `commands.gate` is not set, and no fix here could
|
|
29
|
+
be checked: do nothing for any pull request, open no issue, and say so
|
|
30
|
+
once in the report.
|
|
31
|
+
|
|
20
32
|
A run started by the workflow ran `factory deps --any` first, which exits
|
|
21
33
|
0 when a Dependabot pull request is open, and starts a session only then.
|
|
22
34
|
Read the list again, since time has passed.
|
|
@@ -45,16 +57,21 @@ in the report and the next one starts.
|
|
|
45
57
|
- **Two earlier shepherd comments already report a fix that did not turn
|
|
46
58
|
CI green:** stop on it. Open an issue (step 6) if none is linked yet.
|
|
47
59
|
|
|
48
|
-
## 2. Conflicts with
|
|
60
|
+
## 2. Conflicts with the default branch
|
|
49
61
|
|
|
50
|
-
The ruleset does not require a branch to be up to date with
|
|
62
|
+
The ruleset does not require a branch to be up to date with the default
|
|
63
|
+
branch, so a
|
|
51
64
|
pull request that is only `behind` merges as it is; leave it. Updating it
|
|
52
65
|
would only start CI again.
|
|
53
66
|
|
|
54
|
-
A `dirty` state is a conflict, almost always in
|
|
55
|
-
blocks the merge. Check the branch out (step 3), merge `origin/
|
|
56
|
-
|
|
57
|
-
|
|
67
|
+
A `dirty` state is a conflict, almost always in the lock file, and
|
|
68
|
+
blocks the merge. Check the branch out (step 3), merge `origin/DEFAULT`,
|
|
69
|
+
take the default branch's lock file, run `commands.relock`, the command
|
|
70
|
+
`npx --no-install factory config get commands.relock` prints, so the bump
|
|
71
|
+
is reapplied on top of it, and commit the merge. Any other conflicted file
|
|
72
|
+
that matches the `files` of a resolver
|
|
73
|
+
(`npx --no-install factory plugins resolver`) is that resolver's, as
|
|
74
|
+
"Merge" in the `factory-resolve-conflicts` skill says.
|
|
58
75
|
|
|
59
76
|
Then go on: a branch with a conflict can be failing as well.
|
|
60
77
|
|
|
@@ -64,12 +81,13 @@ Check out the branch and reproduce the failure before changing anything:
|
|
|
64
81
|
|
|
65
82
|
```bash
|
|
66
83
|
git fetch origin HEAD_REF && git switch HEAD_REF
|
|
67
|
-
npm ci
|
|
68
84
|
```
|
|
69
85
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
86
|
+
Install what the branch's lock file lists, the way the repository's
|
|
87
|
+
`CLAUDE.md` says to install, which is `npm ci` for npm. Then
|
|
88
|
+
run the gate, `npx --no-install factory gate`, and the end-to-end suite
|
|
89
|
+
where the repository has one, as its `CLAUDE.md` says to run it, with what
|
|
90
|
+
it needs, such as a browser, installed first.
|
|
73
91
|
|
|
74
92
|
Read the failing job's log too, since a failure can be specific to CI:
|
|
75
93
|
|
|
@@ -81,7 +99,8 @@ It prints what a failed check wrote about itself, and each failed job's
|
|
|
81
99
|
name and the end of its log.
|
|
82
100
|
|
|
83
101
|
Fix what the new version broke, in the code, tests or config that use it,
|
|
84
|
-
following `CLAUDE.md
|
|
102
|
+
following `CLAUDE.md` and the area's rules it lists under "Rules by area".
|
|
103
|
+
The fix adapts
|
|
85
104
|
the project to the new version. It never:
|
|
86
105
|
|
|
87
106
|
- pins or downgrades the dependency back, or adds an override for it;
|
|
@@ -92,10 +111,10 @@ the project to the new version. It never:
|
|
|
92
111
|
If the only fix is one of those, or needs a decision about how the site
|
|
93
112
|
should look or behave, stop and open an issue (step 6).
|
|
94
113
|
|
|
95
|
-
Run the gate again (
|
|
114
|
+
Run the gate again (`npx --no-install factory gate`), then commit one coherent
|
|
96
115
|
change whose message describes the defect, and push to the same branch.
|
|
97
|
-
No attribution trailer naming an AI assistant. Never push to
|
|
98
|
-
never force push.
|
|
116
|
+
No attribution trailer naming an AI assistant. Never push to the default
|
|
117
|
+
branch and never force push.
|
|
99
118
|
|
|
100
119
|
Wait for the checks of the new head, up to 20 minutes:
|
|
101
120
|
|
|
@@ -121,7 +140,13 @@ A pull request that bumps `@davidbyoung/software-factory` gets steps 2 and
|
|
|
121
140
|
npx --no-install factory sync
|
|
122
141
|
```
|
|
123
142
|
|
|
124
|
-
|
|
143
|
+
When the sync, or any other `factory` command, fails on the settings after
|
|
144
|
+
the update, the release changed the settings' shape, as version 2 does.
|
|
145
|
+
Stop (step 6), and say the settings are the owner's to move, as "Moving to
|
|
146
|
+
settings version 2" in the factory's `docs/updating.md` says for that
|
|
147
|
+
release. Never edit `.claude/factory.yaml`.
|
|
148
|
+
|
|
149
|
+
Commit what the sync wrote as a second commit, "Sync the factory's files to
|
|
125
150
|
VERSION", and push. The push changes workflows, so it needs a token with
|
|
126
151
|
the `workflow` scope, such as the build token; a refused push is a stop
|
|
127
152
|
(step 6), with GitHub's error. Until then CI's `factory sync --check` fails, which is
|
|
@@ -137,10 +162,10 @@ A major gets steps 2 and 3, plus the migration:
|
|
|
137
162
|
- Read the release notes and migration guide between the two versions,
|
|
138
163
|
from the package's GitHub releases or its changelog in `node_modules`.
|
|
139
164
|
- Make every change the guide calls for, not only the ones CI caught.
|
|
140
|
-
- Update instruction files that name the version
|
|
141
|
-
`CLAUDE.md
|
|
142
|
-
`node_modules/` that
|
|
143
|
-
contradict.
|
|
165
|
+
- Update instruction files that name the version, such as the "Stack"
|
|
166
|
+
section of `CLAUDE.md` and any file it imports. For a framework, read
|
|
167
|
+
the new docs under `node_modules/` that those instructions point to and
|
|
168
|
+
correct any rule they contradict.
|
|
144
169
|
- Never enable auto-merge, never approve and never merge.
|
|
145
170
|
|
|
146
171
|
Then comment on the pull request with what the migration changed, what
|
|
@@ -87,21 +87,30 @@ depends on the one before.
|
|
|
87
87
|
|
|
88
88
|
1. **A scratch worktree of the default branch**, and the change made in
|
|
89
89
|
it. Note what `git worktree list` shows first. From the checkout this
|
|
90
|
-
session works in, with the
|
|
91
|
-
`
|
|
90
|
+
session works in, with the default branch's name, which
|
|
91
|
+
`npx --no-install factory default-branch` prints, in place of DEFAULT:
|
|
92
92
|
|
|
93
93
|
```bash
|
|
94
|
-
git worktree add --detach ../mockup-SLUG origin/
|
|
94
|
+
git worktree add --detach ../mockup-SLUG origin/DEFAULT
|
|
95
95
|
```
|
|
96
96
|
|
|
97
97
|
An option is its own worktree, made the same way. The change need not
|
|
98
98
|
be committed: the comparison pictures the worktree as it stands.
|
|
99
99
|
|
|
100
|
-
2. **Install it,**
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
100
|
+
2. **Install it,** in the scratch worktree: run there the command
|
|
101
|
+
`commands.relock` holds, which installs the repository's dependencies,
|
|
102
|
+
then each command under `commands.build-setup`. Read both from the
|
|
103
|
+
checkout this session works in, where the factory is already installed:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
npx --no-install factory config get commands.relock
|
|
107
|
+
npx --no-install factory config get commands.build-setup
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
The comparison installs the default branch's side, not this one, and
|
|
111
|
+
the factory, the browser, and `site.start` all run from the scratch
|
|
112
|
+
worktree.
|
|
113
|
+
|
|
105
114
|
3. **Picture it,** from the scratch worktree:
|
|
106
115
|
|
|
107
116
|
```bash
|
|
@@ -15,33 +15,35 @@ The loop is one command that fails on this bug and passes once it is
|
|
|
15
15
|
fixed. Everything after it only spends it, so spend the effort here.
|
|
16
16
|
Reach for the cheapest that gets to the symptom:
|
|
17
17
|
|
|
18
|
-
1. A unit test at the seam nearest the bug, run alone with
|
|
19
|
-
|
|
20
|
-
moves into
|
|
21
|
-
|
|
18
|
+
1. A unit test at the seam nearest the bug, run alone with
|
|
19
|
+
`npx --no-install factory test-one FILE NAME`. A decision buried where
|
|
20
|
+
no unit test reaches it moves into a plain function first, where the
|
|
21
|
+
area's rules say logic goes ("Rules by area" in `CLAUDE.md`).
|
|
22
22
|
2. A script in the scratchpad that imports the module and calls it with
|
|
23
|
-
the failing input
|
|
24
|
-
3. For a script
|
|
25
|
-
its output diffed against a known-good copy.
|
|
26
|
-
4. An end-to-end spec, when the symptom needs
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
23
|
+
the failing input.
|
|
24
|
+
3. For a script the repository runs, the real invocation on a fixture
|
|
25
|
+
input, its output diffed against a known-good copy.
|
|
26
|
+
4. An end-to-end spec, when the symptom needs the whole application
|
|
27
|
+
running, such as in a browser, run alone with
|
|
28
|
+
`npx --no-install factory end-to-end FILE`, and repeated with
|
|
29
|
+
`--times K`. It usually builds the application first, so it is the
|
|
30
|
+
slowest loop.
|
|
31
31
|
5. `git bisect run` with any of the above, when the bug arrived between
|
|
32
32
|
two known commits.
|
|
33
33
|
6. A CI failure that will not reproduce locally: read the failed job's log
|
|
34
34
|
(`npx --no-install factory pr failed N`), then close the gap between the two
|
|
35
|
-
environments one difference at a time
|
|
36
|
-
|
|
35
|
+
environments one difference at a time, such as the number of workers,
|
|
36
|
+
a fresh build, and `CI` being set.
|
|
37
37
|
|
|
38
38
|
Then tighten it: faster (one file, one test, a filtered page), sharper (it
|
|
39
39
|
asserts the symptom the report names, not "did not throw"), and steadier
|
|
40
|
-
(
|
|
40
|
+
(a fake clock or fake timers, a seeded source of randomness).
|
|
41
41
|
|
|
42
42
|
**A flaky failure** needs a reproduction rate, not a clean repro. Repeat
|
|
43
|
-
it (
|
|
44
|
-
|
|
43
|
+
it (`npx --no-install factory end-to-end FILE --times 50` for an
|
|
44
|
+
end-to-end spec, which stops at the first run that fails and says which,
|
|
45
|
+
or the test runner's own repeat option for a unit test),
|
|
46
|
+
and add the load CI has, more workers or a second suite at once, until it fails
|
|
45
47
|
often enough to tell a fix from luck. A 1-in-100 flake cannot be
|
|
46
48
|
debugged; a 1-in-3 can.
|
|
47
49
|
|
|
@@ -71,14 +73,14 @@ otherwise go on.
|
|
|
71
73
|
Each probe tests one prediction. Prefer a breakpoint or a REPL to logs;
|
|
72
74
|
when logging, tag every line `[DEBUG-xxxx]` with one random tag, so
|
|
73
75
|
removing them is one grep. For a slowdown, measure before changing
|
|
74
|
-
anything (a timer, the profiler,
|
|
76
|
+
anything (a timer, the profiler, the test runner's trace), and bisect against
|
|
75
77
|
the number.
|
|
76
78
|
|
|
77
79
|
## 5. Fix it
|
|
78
80
|
|
|
79
81
|
Turn the shrunk repro into a test at a seam that runs the real path the
|
|
80
|
-
bug took. Run it red before the fix, then green after, as
|
|
81
|
-
`
|
|
82
|
+
bug took. Run it red before the fix, then green after, as the area's rules
|
|
83
|
+
for tests say ("Rules by area" in `CLAUDE.md`). When no seam reaches the bug, the test would pass
|
|
82
84
|
either way: say so in the pull request rather than ship it, and name the
|
|
83
85
|
decision that should move into a plain function.
|
|
84
86
|
|