@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.
Files changed (120) hide show
  1. package/README.md +20 -20
  2. package/actions/factory-agent/action.yml +1 -1
  3. package/agents/factory-e2e-reviewer.md +102 -0
  4. package/agents/factory-test-reviewer.md +26 -64
  5. package/agents/factory-ticket-readiness.md +14 -6
  6. package/dist/agent/claude-code.d.mts +3 -0
  7. package/dist/agent/claude-code.mjs +89 -0
  8. package/dist/agent/index.d.mts +2 -0
  9. package/dist/agent/index.mjs +5 -0
  10. package/dist/board.mjs +1 -1
  11. package/dist/cli.mjs +46 -4
  12. package/dist/code-host/github-setup.d.mts +5 -0
  13. package/dist/code-host/github-setup.mjs +133 -0
  14. package/dist/code-host/github.mjs +4 -0
  15. package/dist/code-host/index.d.mts +1 -1
  16. package/dist/code-host/index.mjs +2 -1
  17. package/dist/code-host/types.d.mts +2 -0
  18. package/dist/commands.d.mts +16 -0
  19. package/dist/commands.mjs +129 -0
  20. package/dist/config.d.mts +87 -20
  21. package/dist/config.mjs +344 -89
  22. package/dist/deps.d.mts +7 -4
  23. package/dist/deps.mjs +20 -9
  24. package/dist/doctor.d.mts +9 -16
  25. package/dist/doctor.mjs +71 -68
  26. package/dist/explain.d.mts +4 -0
  27. package/dist/explain.mjs +174 -0
  28. package/dist/guard-commit.d.mts +7 -2
  29. package/dist/guard-commit.mjs +58 -21
  30. package/dist/init.d.mts +12 -14
  31. package/dist/init.mjs +194 -136
  32. package/dist/lib/default-branch.d.mts +35 -0
  33. package/dist/lib/default-branch.mjs +117 -0
  34. package/dist/lib/has-command.d.mts +5 -0
  35. package/dist/lib/has-command.mjs +8 -0
  36. package/dist/lib/listed.d.mts +2 -0
  37. package/dist/lib/listed.mjs +4 -0
  38. package/dist/lib/refined-check.d.mts +7 -0
  39. package/dist/lib/refined-check.mjs +76 -0
  40. package/dist/lib/work-status.d.mts +12 -2
  41. package/dist/lib/work-status.mjs +14 -3
  42. package/dist/parts.d.mts +18 -15
  43. package/dist/parts.mjs +15 -43
  44. package/dist/patch-coverage.d.mts +13 -0
  45. package/dist/patch-coverage.mjs +73 -0
  46. package/dist/poller.d.mts +20 -3
  47. package/dist/poller.mjs +62 -15
  48. package/dist/pr-watch.d.mts +3 -2
  49. package/dist/pr-watch.mjs +22 -5
  50. package/dist/pr.mjs +34 -2
  51. package/dist/remove.d.mts +11 -0
  52. package/dist/remove.mjs +156 -0
  53. package/dist/runner/github-actions.d.mts +1 -1
  54. package/dist/runner/github-actions.mjs +12 -0
  55. package/dist/runner/index.d.mts +1 -1
  56. package/dist/runner/index.mjs +2 -1
  57. package/dist/runner/setup.d.mts +2 -0
  58. package/dist/runner/setup.mjs +22 -0
  59. package/dist/runner/types.d.mts +3 -0
  60. package/dist/runner/types.mjs +0 -2
  61. package/dist/session-start.d.mts +23 -13
  62. package/dist/session-start.mjs +56 -44
  63. package/dist/setup.d.mts +98 -0
  64. package/dist/setup.mjs +3 -0
  65. package/dist/site/servers.d.mts +6 -2
  66. package/dist/site/servers.mjs +14 -9
  67. package/dist/site.mjs +2 -2
  68. package/dist/status.d.mts +4 -4
  69. package/dist/status.mjs +8 -7
  70. package/dist/sync.d.mts +26 -2
  71. package/dist/sync.mjs +177 -13
  72. package/dist/ticket.mjs +19 -1
  73. package/dist/tickets/github-setup.d.mts +2 -0
  74. package/dist/tickets/github-setup.mjs +50 -0
  75. package/dist/tickets/github.mjs +0 -2
  76. package/dist/tickets/index.mjs +2 -1
  77. package/dist/tickets/transport.mjs +1 -3
  78. package/dist/tickets/types.mjs +0 -2
  79. package/dist/tool-names.d.mts +11 -0
  80. package/dist/tool-names.mjs +20 -0
  81. package/dist/tools.d.mts +56 -0
  82. package/dist/tools.mjs +76 -0
  83. package/docs/builds.md +111 -59
  84. package/docs/cli.md +106 -69
  85. package/docs/configuration.md +489 -171
  86. package/docs/design.md +18 -5
  87. package/docs/developing.md +179 -73
  88. package/docs/existing-repo.md +25 -12
  89. package/docs/github/by-hand.md +334 -0
  90. package/docs/github/reference.md +76 -67
  91. package/docs/github/setup.md +105 -286
  92. package/docs/glossary.md +18 -7
  93. package/docs/limitations.md +39 -12
  94. package/docs/plugins.md +305 -56
  95. package/docs/quick-start.md +85 -100
  96. package/docs/removing.md +37 -17
  97. package/docs/skills.md +121 -62
  98. package/docs/updating.md +150 -9
  99. package/docs/workflow.md +23 -19
  100. package/package.json +1 -1
  101. package/poller.Dockerfile +10 -18
  102. package/review.md +20 -11
  103. package/rules.md +36 -30
  104. package/settings.schema.json +313 -69
  105. package/skills/factory-address-review/SKILL.md +50 -30
  106. package/skills/factory-build/SKILL.md +76 -23
  107. package/skills/factory-deps/SKILL.md +46 -21
  108. package/skills/factory-design/SKILL.md +17 -8
  109. package/skills/factory-diagnose/SKILL.md +22 -20
  110. package/skills/factory-mutate/SKILL.md +38 -24
  111. package/skills/factory-refine/SKILL.md +55 -31
  112. package/skills/factory-resolve-conflicts/SKILL.md +76 -34
  113. package/skills/factory-trace/SKILL.md +80 -0
  114. package/workflows/factory-build.yml +6 -5
  115. package/workflows/factory-conflicts.yml +8 -8
  116. package/workflows/factory-deps-auto-merge.yml +3 -2
  117. package/workflows/factory-deps.yml +1 -1
  118. package/workflows/factory-poller.yml +46 -0
  119. package/workflows/factory-review.yml +1 -1
  120. 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 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.
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 Codecov comment.
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 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
+ **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 main" in the `factory-resolve-conflicts` skill first, then work each comment as "Each owner comment"
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 main" in that skill), commit, and push to that branch
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
- (`codecov.yml`), so a missing comment is normal, not a failed upload.
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 Codecov comment's ID, if there is one, and lists
316
- `codecov/patch` and `codecov/project` among the checks. Read the comment
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. 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.
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 project's coverage command, then
342
+ report CI uploads: run the coverage command, the first of the two above,
343
+ then
327
344
 
328
345
  ```bash
329
- python3 .claude/skills/factory-address-review/patch-coverage.py [base] [lcov]
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. 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.
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 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
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 `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
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 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.
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 main" in the `factory-resolve-conflicts` skill. Every
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 main: which pull request it was with, which files, and
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 `ready-poller` worker posts a start comment and dispatches
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 `factory-refine` and stop: no claim, and nothing to
155
- release. Do not guess at what content should say or how a page
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, run `factory-refine` steps 4 and 5 first, posting
174
- no refinement marker: fold the replies in and read the result for
175
- readiness. If a reply raises a new decision, or the read finds a
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 `main`, or to stash it with `git stash -u`. A plain
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/main, named for the issue:
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/main
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/main, name it in the
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 ("After every code change" in `CLAUDE.md`), and commit the
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. What its
251
- report says goes in the pull request body at step 6, where the owner reads
252
- it before merging.
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 `factory-mutate`
269
- skill, and have `factory-test-reviewer` read them.
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 `factory-mutate`) is not verified. Record the mapping in the pull request.
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 ("After every code change" in `CLAUDE.md`).
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 ("After every code change" in `CLAUDE.md`).
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, with
307
- `--repeat-each=10` for a new one, with the command "After every code
308
- change" in `CLAUDE.md` gives; CI runs the full suite on the draft (step 6).
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 main, 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.
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 main
60
+ ## 2. Conflicts with the default branch
49
61
 
50
- The ruleset does not require a branch to be up to date with main, so a
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 `package-lock.json`, and
55
- blocks the merge. Check the branch out (step 3), merge `origin/main`, take
56
- main's lock file, run `npm install` so the bump is reapplied on top of it,
57
- and commit the merge.
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
- Then run the gate's check and the end-to-end suite, with its browser
71
- installed first, by the commands "After every code change" in `CLAUDE.md`
72
- gives.
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`, `AGENTS.md` and `tests/CLAUDE.md`. The fix adapts
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 ("After every code change" in `CLAUDE.md`), then commit one coherent
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 main and
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
- Commit what it wrote as a second commit, "Sync the factory's files to
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: the "Stack" section of
141
- `CLAUDE.md`, and `AGENTS.md`. For a framework, read the new docs under
142
- `node_modules/` that `AGENTS.md` points to and correct any rule they
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 repository's default branch in place of
91
- `main`:
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/main
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,** from the scratch worktree: `npm ci` where the
101
- repository has a lock file, then each command `npx --no-install factory
102
- config get build-setup` prints. The comparison installs the default
103
- branch's side, not this one, and the factory, the browser, and
104
- `site.start` all run from here.
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 the command
19
- "After every code change" in `CLAUDE.md` gives. A decision buried in a component
20
- moves into its `.ts` sibling first, as `AGENTS.md` prefers, where a
21
- unit test reaches it without a DOM.
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, run with `node`.
24
- 3. For a script under `scripts/`, the real invocation on a fixture input,
25
- its output diffed against a known-good copy.
26
- 4. An end-to-end spec, when the symptom needs a browser, run alone and
27
- repeated with the command "After every code change" in `CLAUDE.md`
28
- gives. It builds the site first,
29
- so it is the slowest loop; never `next dev`, which rewrites
30
- `AGENTS.md`.
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 (CI runs Playwright on 2
36
- workers, against a fresh build, with `CI` set).
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
- (`page.clock` or fake timers, a seeded `Math.random`).
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 (`--repeat-each=50`, or `{ repeats: 50 }` on a Vitest test), and add
44
- the load CI has, more workers or a second suite at once, until it fails
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, Playwright's trace), and bisect against
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
- `tests/CLAUDE.md` says. When no seam reaches the bug, the test would pass
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