@davidbyoung/software-factory 0.1.11 → 0.1.13

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 (85) hide show
  1. package/agents/factory-e2e-reviewer.md +1 -1
  2. package/agents/factory-test-reviewer.md +1 -1
  3. package/agents/factory-ui-reviewer.md +2 -2
  4. package/dist/board.d.mts +9 -7
  5. package/dist/board.mjs +59 -36
  6. package/dist/build.d.mts +4 -0
  7. package/dist/build.mjs +9 -4
  8. package/dist/cli.mjs +8 -1
  9. package/dist/code-host/github.mjs +9 -4
  10. package/dist/code-host/types.d.mts +4 -2
  11. package/dist/commands.d.mts +1 -1
  12. package/dist/commands.mjs +16 -7
  13. package/dist/config.d.mts +7 -0
  14. package/dist/config.mjs +68 -5
  15. package/dist/explain.mjs +6 -0
  16. package/dist/guard-commit.d.mts +3 -3
  17. package/dist/guard-commit.mjs +31 -6
  18. package/dist/guard-ticket-text.d.mts +3 -2
  19. package/dist/guard-ticket-text.mjs +7 -4
  20. package/dist/labels.d.mts +28 -0
  21. package/dist/labels.mjs +36 -0
  22. package/dist/lib/clock.d.mts +3 -1
  23. package/dist/lib/clock.mjs +12 -6
  24. package/dist/lib/pull-tickets.d.mts +15 -0
  25. package/dist/lib/pull-tickets.mjs +12 -0
  26. package/dist/lib/refined-check.d.mts +1 -1
  27. package/dist/lib/refined-check.mjs +3 -5
  28. package/dist/lib/usage.d.mts +3 -1
  29. package/dist/lib/usage.mjs +4 -2
  30. package/dist/lib/work-status.d.mts +29 -23
  31. package/dist/lib/work-status.mjs +30 -33
  32. package/dist/merge-policy.d.mts +9 -7
  33. package/dist/merge-policy.mjs +13 -11
  34. package/dist/poller.d.mts +5 -3
  35. package/dist/poller.mjs +27 -17
  36. package/dist/pr.d.mts +22 -0
  37. package/dist/pr.mjs +60 -10
  38. package/dist/remove.mjs +16 -9
  39. package/dist/review-tickets.d.mts +12 -0
  40. package/dist/review-tickets.mjs +59 -0
  41. package/dist/review-verdict.d.mts +6 -1
  42. package/dist/review-verdict.mjs +15 -9
  43. package/dist/reviewers.d.mts +7 -4
  44. package/dist/reviewers.mjs +19 -12
  45. package/dist/runner/github-actions.mjs +6 -7
  46. package/dist/runner/types.d.mts +7 -6
  47. package/dist/status.d.mts +19 -7
  48. package/dist/status.mjs +38 -23
  49. package/dist/sync.d.mts +8 -0
  50. package/dist/sync.mjs +30 -1
  51. package/dist/ticket-fields.d.mts +4 -2
  52. package/dist/ticket-fields.mjs +10 -3
  53. package/dist/ticket.d.mts +14 -7
  54. package/dist/ticket.mjs +121 -72
  55. package/dist/tickets/github.d.mts +10 -2
  56. package/dist/tickets/github.mjs +74 -20
  57. package/dist/tickets/index.d.mts +9 -2
  58. package/dist/tickets/index.mjs +20 -5
  59. package/dist/tickets/types.d.mts +59 -30
  60. package/dist/tickets/types.mjs +13 -3
  61. package/dist/tool-names.d.mts +7 -0
  62. package/dist/tool-names.mjs +1 -0
  63. package/dist/tools.d.mts +4 -1
  64. package/dist/tools.mjs +5 -0
  65. package/docs/cli.md +12 -8
  66. package/docs/configuration.md +179 -9
  67. package/docs/developing.md +17 -9
  68. package/docs/github/by-hand.md +2 -2
  69. package/docs/github/reference.md +22 -22
  70. package/docs/plugins.md +6 -6
  71. package/docs/workflow.md +8 -6
  72. package/package.json +1 -1
  73. package/review.md +11 -11
  74. package/rules.md +25 -16
  75. package/settings.schema.json +45 -0
  76. package/skills/factory-address-review/SKILL.md +7 -6
  77. package/skills/factory-build/SKILL.md +28 -22
  78. package/skills/factory-refine/SKILL.md +1 -1
  79. package/skills/factory-resolve-conflicts/SKILL.md +5 -4
  80. package/workflows/factory-build.yml +6 -5
  81. package/workflows/factory-claude-review.yml +38 -1
  82. package/workflows/factory-conflicts.yml +1 -1
  83. package/workflows/factory-merge-policy.yml +8 -7
  84. package/workflows/factory-review-verdict.yml +1 -1
  85. package/workflows/factory-review.yml +1 -1
package/docs/cli.md CHANGED
@@ -137,21 +137,23 @@ prints what the ticket system returned as one JSON value. `edit`,
137
137
  `comment`, and `open` refuse a body with a bare tag-like `<word>` the
138
138
  ticket system would swallow, name it, and post nothing.
139
139
 
140
+ N is the ticket's key as your ticket system writes it: `12` on GitHub.
141
+
140
142
  | Command | What it does |
141
143
  | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
142
- | `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors |
144
+ | `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors. A label you renamed shows its key beside it |
143
145
  | `factory ticket answers N` | Prints each comment on N that counts as an answer: its author can write to the repository, and it is not the factory's own. Says so when there is none |
144
- | `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else |
145
- | `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs |
146
+ | `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), `body`, or `ref`, how the ticket system writes N in prose, such as `#12`, and nothing else |
147
+ | `factory ticket list` | Lists the open tickets: key, title, and labels, separated by tabs |
146
148
  | `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
147
149
  | `factory ticket edit N [--title TITLE] [--body-file FILE]` | Replaces N's title, its body, or both. `--attach FILE` adds an image to a body |
148
150
  | `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image |
149
- | `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its number. `--label LABEL` adds a label |
151
+ | `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its key. `--label LABEL` adds a label |
150
152
  | `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
151
153
  | `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no` |
152
- | `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12" |
154
+ | `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12". `--part` prints the text that says it builds part of N, such as "Part of #4" |
153
155
  | `factory ticket branch N` | Prints the branch a build of N pushes, from [`code-host.branch-name`](configuration.md#code-host), such as `12` or `feature/octocat/12`. Exits 1 when N does not exist, or the pattern has `{user}` and `gh` is not signed in |
154
- | `factory ticket blockers N` | One line per ticket N waits on: its number and whether it is open |
156
+ | `factory ticket blockers N` | One line per ticket N waits on: the ticket, as its system writes it, and whether it is open |
155
157
  | `factory ticket block N --by M` | Records that N waits on M |
156
158
  | `factory ticket unblock N --by M` | Removes that record |
157
159
  | `factory ticket supports GROUP` | Prints `yes` or `no` for `board`, `blockers`, `label-history`, or `attachments` |
@@ -163,7 +165,7 @@ ticket system would swallow, name it, and post nothing.
163
165
  | `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
164
166
  | `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
165
167
  | `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
166
- | `factory ticket cost N` | Notes what this session spent on N since it started |
168
+ | `factory ticket cost N` | Notes what this session spent on ticket N since it started |
167
169
  | `factory follow-up FILE "what is wrong"` | Adds a line about that file to the follow-ups ticket, opening the ticket if none is open |
168
170
 
169
171
  `factory ticket refined N` posts nothing and exits 1 when N's body lacks a
@@ -183,7 +185,8 @@ ticket system.
183
185
  | `factory pr threads N` | The unresolved review threads, each with its comments. `--all` lists the resolved ones too |
184
186
  | `factory pr reply N COMMENT --body-file FILE` | Replies on a thread |
185
187
  | `factory pr resolve N COMMENT` | Resolves a thread |
186
- | `factory pr closes N` | The tickets N closes |
188
+ | `factory pr closes N` | The tickets N closes, by key |
189
+ | `factory pr cost N` | Notes what this session spent on pull request N since it started |
187
190
  | `factory pr for-branch BRANCH` | The newest pull request from BRANCH, open or not: `#N open`, `#N merged`, or `#N closed`, or `none` when there has been none |
188
191
  | `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
189
192
  | `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified |
@@ -263,6 +266,7 @@ the commit hook blocks a session's git command with it.
263
266
  | `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
264
267
  | `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
265
268
  | `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`pr-review.commands`](configuration.md#pr-review) | Built |
269
+ | `factory review tickets N` | The review workflow | Each ticket pull request N closes or builds part of, headed by its name and title, with its body | Built |
266
270
  | `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
267
271
  | `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings | Built |
268
272
  | `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
@@ -83,18 +83,62 @@ The [glossary](glossary.md) has the rest.
83
83
 
84
84
  ## The shortest file
85
85
 
86
+ These are the settings the factory needs before a session can build a
87
+ ticket. Every other setting has a default.
88
+
86
89
  ```yaml
87
90
  version: 2
88
91
  repository: your-name/your-repo
89
92
  code-host:
90
- type: github
91
93
  branch-name: "{ticket}"
94
+ commands:
95
+ gate:
96
+ - npm test
97
+ ```
98
+
99
+ - [`version`](#version), [`repository`](#repository), and
100
+ [`code-host.branch-name`](#code-host) are required by every command,
101
+ and `factory init` writes all three. Without one, every command stops
102
+ and names it. `"{ticket}"` is a pattern: ticket 12 is built on a branch
103
+ named `12`. The code host is GitHub unless you say otherwise.
104
+ - [`commands.gate`](#commandsgate) is how a session checks a change, such
105
+ as your tests and linter. `factory init` doesn't write it: it lists it
106
+ under "Left to do", and you add it. Without it the factory still
107
+ [refines](workflow.md) tickets, but a session can't build one.
108
+
109
+ With these, the factory refines a ticket when you run `/factory-refine N`
110
+ in a session, builds it when you run `/factory-build N`, nothing merges
111
+ without you, and there is no board.
112
+
113
+ **With a board,** two more settings are required. Skip this part if you
114
+ have none:
115
+ [`tickets.board`](#tickets), your GitHub Project's number, and
116
+ [`tickets.columns`](#ticketscolumns), which of its columns shows each of
117
+ the six [states](workflow.md#the-six-states) a ticket goes through.
118
+ `factory init` writes both from the board you choose:
119
+
120
+ ```yaml
121
+ tickets:
122
+ board: 1
123
+ columns:
124
+ backlog: Backlog
125
+ refining: In refinement
126
+ ready: Ready
127
+ building: In progress
128
+ review: In review
129
+ done: Done
92
130
  ```
93
131
 
94
- With only this, the factory refines a ticket when you run `/factory-refine N` in a session,
95
- nothing merges without you, and there is no board. Before a session can
96
- build a ticket, you also need to tell it how to check a change:
97
- [`commands.gate`](#commandsgate), below.
132
+ Every state needs a line. For a state your board has no column for,
133
+ write `none` as its column. By default nothing starts a build when a
134
+ ticket reaches Ready ([`builds.trigger`](#builds) is `manual`); if you
135
+ set it to `own-server` or `github-action`, `ready` must name a column.
136
+
137
+ `factory init` may write more, such as [`tickets.fields`](#ticketsfields)
138
+ when you confirm the ticket fields it suggests. None of it is required.
139
+
140
+ **It worked when** `factory config check` prints
141
+ `✓ The settings are valid.`
98
142
 
99
143
  ## The settings most repositories change
100
144
 
@@ -197,6 +241,8 @@ tickets:
197
241
  default, `none`, means no board.
198
242
  - **`columns`** says which of the board's columns shows each state, and a
199
243
  board needs it: see [`tickets.columns`](#ticketscolumns).
244
+ - **`labels`** renames the labels the factory puts on tickets: see
245
+ [`tickets.labels`](#ticketslabels). Most repositories leave it out.
200
246
 
201
247
  Without a board, `factory status` still shows every ticket's state, which
202
248
  the factory keeps in comments on the ticket. Builds then start only when
@@ -399,11 +445,79 @@ you confirm them.
399
445
  - **Changing a line** affects tickets refined afterwards. A ticket
400
446
  refined before keeps its factory fields where they were written.
401
447
 
448
+ #### `tickets.labels`
449
+
450
+ The names of the two labels the factory puts on tickets. Most
451
+ repositories never set them: leave the block out, and the factory uses
452
+ the default names. To rename a label on pull requests instead, see
453
+ [`code-host.labels`](#code-hostlabels).
454
+
455
+ Each label has a key and a name. The key is what you write on the left,
456
+ and never changes. The name is what your ticket system shows, and is
457
+ what you set:
458
+
459
+ ```yaml
460
+ tickets:
461
+ labels:
462
+ spec: needs-spec # refinement adds needs-spec, not spec
463
+ follow-up: follow-ups # the follow-ups ticket carries follow-ups
464
+ ```
465
+
466
+ | Key | Default name | What the label marks |
467
+ | ----------- | ------------ | --------------------------------------------------------------------------------------------------------------------- |
468
+ | `spec` | `spec` | A change your users will see, so [refinement writes a Spec](workflow.md#a-change-your-users-will-see) into the ticket |
469
+ | `follow-up` | `follow-up` | The one [follow-ups ticket](workflow.md#follow-ups) |
470
+
471
+ - **Write only the keys you change.** A key you leave out keeps its
472
+ default name. `factory init` doesn't ask about labels, and doesn't write
473
+ this block.
474
+ - **You don't create the label.** The factory creates it on GitHub the
475
+ first time it adds it to a ticket.
476
+ - **Two labels can't share a name,** and capitals don't make two names
477
+ different, so `Spec` and `spec` are one label. On GitHub, a name here
478
+ can't match one under `code-host.labels` either, since one
479
+ repository's labels serve its tickets and its pull requests.
480
+ - **Quote a name with `: ` in it,** such as `spec: "kind: spec"`.
481
+ Without the quotes, YAML can't read the file.
482
+
483
+ To rename a label:
484
+
485
+ 1. Write the new name under `tickets.labels` in `.claude/factory.yaml`.
486
+ 2. If tickets already carry the label, rename it on GitHub to the same
487
+ name, under Issues, Labels, Edit. That moves every ticket that has
488
+ it. The factory finds tickets only by the name in your settings and
489
+ never renames a label, so until you do, it doesn't see them: a
490
+ follow-ups ticket still labeled `follow-up` is ignored, and the next
491
+ follow-up a session records opens a new one.
492
+ 3. Check the file and sync, as for every setting:
493
+
494
+ ```console
495
+ $ factory config check
496
+ ✓ The settings are valid.
497
+ $ factory sync
498
+ wrote .claude/factory.lock
499
+ ```
500
+
501
+ 4. Commit `.claude/factory.yaml` and `.claude/factory.lock`.
502
+
503
+ `factory config check` names a label it refuses, and why:
504
+
505
+ ```text
506
+ .claude/factory.yaml: tickets.labels.spec: must not be empty
507
+ .claude/factory.yaml: tickets.labels.spec: "follow-up" is already tickets.labels.follow-up. Give each label its own name
508
+ ```
509
+
510
+ **It worked when** `factory config explain` shows your names under
511
+ `tickets.labels`, without `# default` after them, and
512
+ `factory ticket view N` on a ticket with the label shows it with its
513
+ key, such as `labels: needs-spec (spec)`.
514
+
402
515
  ### `code-host`
403
516
 
404
- Where your repository and its pull requests live, and what every
405
- [build](#words-this-page-uses) names the branch it pushes, in a session
406
- on your machine and in the cloud alike.
517
+ Where your repository and its pull requests live. It also sets what
518
+ every [build](#words-this-page-uses) names the branch it pushes, in a
519
+ session on your machine and in the cloud alike, and what the labels on
520
+ pull requests are called.
407
521
 
408
522
  ```yaml
409
523
  code-host:
@@ -417,6 +531,8 @@ code-host:
417
531
  default: [`factory init`](github/setup.md) asks for it and offers
418
532
  `{ticket}`, so ticket 12 is built on a branch named `12`. A
419
533
  [preset](#presets) can set it for every repository that follows it.
534
+ - **`labels`** renames the labels on pull requests: see
535
+ [`code-host.labels`](#code-hostlabels). Most repositories leave it out.
420
536
 
421
537
  Without `branch-name`, `factory config check` stops:
422
538
 
@@ -430,7 +546,7 @@ it out:
430
546
 
431
547
  | Placeholder | What it becomes | For ticket 12 |
432
548
  | ----------- | ------------------------------------ | ------------- |
433
- | `{ticket}` | The ticket's number, without `#` | `12` |
549
+ | `{ticket}` | The ticket's key, without `#` | `12` |
434
550
  | `{user}` | The GitHub account the build runs as | `octocat` |
435
551
 
436
552
  In a session, `{user}` is the account the GitHub CLI, `gh`, is signed in
@@ -499,6 +615,60 @@ fault it finds:
499
615
  Commit `.claude/factory.yaml` and `.claude/factory.lock`. The next build
500
616
  uses the new pattern; branches already pushed keep their names.
501
617
 
618
+ #### `code-host.labels`
619
+
620
+ The names of the three labels on pull requests. They stay on your code
621
+ host whatever ticket system you use. Most repositories never set them:
622
+ leave the block out, and each label's name is its key.
623
+
624
+ ```yaml
625
+ code-host:
626
+ branch-name: "{ticket}"
627
+ labels:
628
+ merge-automatic: auto-merge
629
+ merge-manual: needs-owner
630
+ verdict-override: owner-pass
631
+ ```
632
+
633
+ | Key | What the label marks |
634
+ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
635
+ | `merge-automatic` | The pull request [merges itself](workflow.md#who-merges) once every check passes |
636
+ | `merge-manual` | The pull request [waits for a person](workflow.md#who-merges) to merge it |
637
+ | `verdict-override` | A person passed the automated review's verdict on the newest commit, its ruling on whether it is ready. Sessions never add it, under any name |
638
+
639
+ - **The two merge labels appear only if you use
640
+ [`auto-merge`](#auto-merge)**, with a pattern under `auto-merge.allow`.
641
+ Otherwise no pull request gets either, whatever you name them.
642
+ - **The override matters only with [`pr-review`](#pr-review) on**, since
643
+ that review gives the verdict.
644
+ - **Naming a label doesn't turn on `auto-merge` or `pr-review`.**
645
+ - **New names take effect once they are on your default branch**, the
646
+ one pull requests merge into, since the workflows that add and read
647
+ these labels run from its copy. On a branch of its own, a rename
648
+ changes nothing yet, and pull requests keep getting the old names.
649
+
650
+ The rules under [`tickets.labels`](#ticketslabels) hold here too: write
651
+ only the keys you change, give each label its own name, quote a name
652
+ with `: ` in it, and rename a label already on your pull requests on
653
+ GitHub yourself. Then check the file and sync:
654
+
655
+ ```console
656
+ $ factory config check
657
+ ✓ The settings are valid.
658
+ $ factory sync
659
+ wrote .claude/factory.lock
660
+ wrote .github/workflows/factory-review-verdict.yml
661
+ ```
662
+
663
+ The second `wrote` line appears only when you rename `verdict-override`:
664
+ that workflow names the label it starts on, so the sync rewrites it.
665
+ Commit `.claude/factory.yaml`, the lock, and any workflow `factory sync`
666
+ wrote, and merge them.
667
+
668
+ **It worked when** `factory config explain` shows your names under
669
+ `code-host.labels`, without `# default` after them, and once merged, the
670
+ next pull request the merge policy labels gets your name.
671
+
502
672
  ### `builds`
503
673
 
504
674
  What starts a build when you approve a ticket, and where the build runs.
@@ -38,7 +38,7 @@ marked working below exist only in these docs.
38
38
  | Builds that run in GitHub Actions, started by a command | Working |
39
39
  | Starting builds from the board, and the review, conflict, and dependency runs, in GitHub Actions | Working |
40
40
  | Who merges, and the review's verdict | Working |
41
- | The labels `merge: manual` and `verdict: override` | Working |
41
+ | The labels `merge-manual` and `verdict-override` | Working |
42
42
  | These docs | Working |
43
43
  | `.claude/factory.yaml`, and the factory's files kept apart from the host's | Working |
44
44
  | The follow-ups ticket as one checklist | Working |
@@ -226,19 +226,22 @@ the work to that type's adapter.** An adapter is one module in
226
226
 
227
227
  | Operation | In `Tickets` | What it returns or does |
228
228
  | ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
229
- | Read a ticket | `read` | Its number, title, state (`open` or `closed`), when it closed, labels, body, and comments, each with its ID, author, time, and body |
230
- | List open tickets | `listOpen` | Number, title, and labels, for every open ticket however many there are |
229
+ | Parse a key | `key` | The key a person typed, or `KeyError` saying what a key looks like in this system. GitHub's are numbers, such as `12` |
230
+ | Write a ticket | `ref` | How the ticket is written in prose and output, such as `#12` |
231
+ | Read a ticket | `read` | Its key, title, state (`open` or `closed`), when it closed, labels, body, and comments, each with its ID, author, time, and body |
232
+ | List open tickets | `listOpen` | Key, title, and labels, for every open ticket however many there are |
231
233
  | Read everything at once | `readAll` | Every open ticket and the 30 closed ones most recently updated, as `read` returns each; with the board group, each carries its card. Optional: see below |
232
234
  | Write a ticket's body | `writeBody` | |
233
235
  | Comment | `comment` | Returns the comment's ID. Hidden markers pass through unchanged |
234
236
  | Edit a comment | `editComment` | By its ID |
235
237
  | Delete a comment | `deleteComment` | By its ID |
236
238
  | Not found | `NotFoundError` | Reading a ticket that does not exist, or editing or deleting a comment that is gone, throws this, so a caller can tell it from any other failure |
237
- | Open a ticket | `open` | With a title, a body, and labels. Returns its number |
239
+ | Open a ticket | `open` | With a title, a body, and labels. Returns its key |
238
240
  | Add or remove a label | `addLabel`, `removeLabel` | |
239
241
  | Who may decide | `mayDecide` | Whether a comment's author may decide on a ticket, so `factory ticket answers` takes their comment as an answer. GitHub's asks whether they can write to the repository. Rejects when it cannot say |
240
- | Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12" |
241
- | The address of a ticket | `address` | Its page, which the views link a ticket's number to |
242
+ | Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12", and what says it builds part of one, "Part of #4" |
243
+ | Links in a body | `linksIn` | The tickets a pull request's body closes, and those it builds part of, each in the body's order |
244
+ | The address of a ticket | `address` | Its page, which the views link a ticket to |
242
245
 
243
246
  "Read everything at once" has a default, `readAll` in
244
247
  `src/tickets/types.mts`, built from `listOpen` and `read`, so a new adapter
@@ -281,13 +284,18 @@ package.
281
284
  What stays above the interface: working out a ticket's state from its
282
285
  marker comments, costs, and the formatting of every view, in
283
286
  `src/lib/work-status.mts` and the commands. They are the factory's own
284
- logic, the same for any system.
287
+ logic, the same for any system. Nothing there writes `#` or reads a link
288
+ from a pull request's body itself: it asks the adapter. The code host's
289
+ own links, such as GitHub's closing references, count only when the
290
+ tickets are the code host's own (`src/lib/pull-tickets.mts`).
285
291
 
286
292
  A second adapter exists from the start: an in-memory one,
287
293
  `tests/memory-tickets.ts`, that every command's tests run against. It
288
294
  keeps the interface honest, since anything the tests need has to go
289
- through it. The GitHub adapter has its own tests against recorded
290
- responses.
295
+ through it. Its keys are numbers, as GitHub's are; with `strict` they are
296
+ keys like `PROJ-12`, and comment IDs and authors are opaque text, as Jira
297
+ and Linear give them, so a command that treats either as a number fails
298
+ there. The GitHub adapter has its own tests against recorded responses.
291
299
 
292
300
  What an adapter does not cover: pull requests, reviews, and checks, which
293
301
  are the code host's, and where an unattended build runs, which is the
@@ -245,7 +245,7 @@ list, such as documentation.
245
245
  ```
246
246
 
247
247
  Then run `factory sync`, which writes the merge-policy workflow. It
248
- labels each pull request `merge: automatic` or `merge: manual` and
248
+ labels each pull request `merge-automatic` or `merge-manual` and
249
249
  says why.
250
250
 
251
251
  2. **Allow auto-merge** on the repository: Settings, General, "Allow
@@ -253,7 +253,7 @@ list, such as documentation.
253
253
  3. **Store a GitHub token** as `FACTORY_AUTOMERGE_TOKEN` ([Secrets](#secrets)).
254
254
 
255
255
  **It worked when** a pull request that touches only files you listed gets
256
- the `merge: automatic` label.
256
+ the `merge-automatic` label.
257
257
 
258
258
  ## Signed commits from cloud builds
259
259
 
@@ -36,17 +36,17 @@ The "Removing it" column says what `factory remove` does with each.
36
36
 
37
37
  ### On GitHub
38
38
 
39
- | What | Added when | To undo |
40
- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
41
- | Secrets and variables named `FACTORY_...` | You create them | Delete them |
42
- | `CLAUDE_CODE_OAUTH_TOKEN` | You create it, for the automated review and builds in the cloud | Delete it, unless another workflow uses it |
43
- | The secrets your `.npmrc` reads, such as `NPM_TOKEN`, for Actions and for Dependabot | `init`, when you paste them | Leave them if your own CI uses them; otherwise delete both copies |
44
- | Labels: `merge: automatic`, `merge: manual`, `verdict: override`, `follow-up`, `spec` | First use | Delete them. Deleting a label removes it from every ticket |
45
- | A CI check that the factory's files are in step | Setup | Goes with `factory-check.yml` |
46
- | A "Review verdict" required check, as the ruleset "Software factory" | `init`, when the review is on; or you, in your branch rules | Delete the ruleset, under Settings, Rules, **first**, or pull requests wait on it forever |
47
- | Statuses on pull requests: "Who merges", "Review verdict" | Each pull request | They stay in history |
48
- | One open ticket titled "Follow-ups" | The first follow-up | Close it |
49
- | Comments on tickets the factory worked | Each refinement and build | They stay. They hold the ticket's history |
39
+ | What | Added when | To undo |
40
+ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
41
+ | Secrets and variables named `FACTORY_...` | You create them | Delete them |
42
+ | `CLAUDE_CODE_OAUTH_TOKEN` | You create it, for the automated review and builds in the cloud | Delete it, unless another workflow uses it |
43
+ | The secrets your `.npmrc` reads, such as `NPM_TOKEN`, for Actions and for Dependabot | `init`, when you paste them | Leave them if your own CI uses them; otherwise delete both copies |
44
+ | Labels: `merge-automatic`, `merge-manual`, `verdict-override`, `follow-up`, `spec`, or the names under [`tickets.labels`](../configuration.md#ticketslabels) and [`code-host.labels`](../configuration.md#code-hostlabels) | First use | Delete them. Deleting a label removes it from every ticket |
45
+ | A CI check that the factory's files are in step | Setup | Goes with `factory-check.yml` |
46
+ | A "Review verdict" required check, as the ruleset "Software factory" | `init`, when the review is on; or you, in your branch rules | Delete the ruleset, under Settings, Rules, **first**, or pull requests wait on it forever |
47
+ | Statuses on pull requests: "Who merges", "Review verdict" | Each pull request | They stay in history |
48
+ | One open ticket titled "Follow-ups" | The first follow-up | Close it |
49
+ | Comments on tickets the factory worked | Each refinement and build | They stay. They hold the ticket's history |
50
50
 
51
51
  ### On your board
52
52
 
@@ -81,13 +81,13 @@ anything to do, and stops there when there is not.
81
81
  | `factory-deps.yml` | 01:00, 13:00, and 19:00 UTC, or by hand | Runs a session that moves Dependabot's pull requests along, when `factory deps --any` exits 0. Written once `.github/dependabot.yml` exists |
82
82
  | `factory-deps-auto-merge.yml` | Dependabot's pull requests | Lets one merge itself when your [`auto-merge`](../configuration.md#auto-merge) settings allow its files. Written once `.github/dependabot.yml` exists |
83
83
  | `factory-board-sync.yml` | Ticket and pull request events, and nightly | Sets the board's columns and fields from the tickets' marker comments. Written once [`tickets.board`](../configuration.md#tickets) is set |
84
- | `factory-merge-policy.yml` | Every pull request | Labels it `merge: automatic` or `merge: manual`, and turns auto-merge on for the first. Written once `auto-merge.allow` is set |
84
+ | `factory-merge-policy.yml` | Every pull request | Labels it `merge-automatic` or `merge-manual`, and turns auto-merge on for the first. Written once `auto-merge.allow` is set |
85
85
  | `factory-review-verdict.yml` | Each automated review | Posts the "Review verdict" status from the review's summary |
86
86
  | `factory-claude-review.yml` | Every pull request once it is marked ready, and each push after | Runs the automated review. Written once [`pr-review`](../configuration.md#pr-review) is set |
87
87
  | `factory-poller.yml` | Every `builds.poll-minutes` minutes, or by hand | Runs one pass of the poller, starting a build for each Ready ticket. Written once `builds.trigger` is `github-action` |
88
88
 
89
89
  **Starting a build by hand.** The Actions tab, "Factory build", "Run
90
- workflow", and the ticket's number. The board's "Runs in" field then shows
90
+ workflow", and the ticket's key, such as `12`. The board's "Runs in" field then shows
91
91
  "Actions", and "Session" the run's link. The run's log also shows each
92
92
  tool call the session was denied, with the reason.
93
93
 
@@ -149,15 +149,15 @@ number, the last part of its address, is `tickets.board` in your settings.
149
149
 
150
150
  ## Labels and statuses
151
151
 
152
- | Name | Kind | Set by |
153
- | ------------------- | ------------------------ | ------------------------------------------------------------------------------------------------- |
154
- | `merge: automatic` | Label on a pull request | The merge policy, when every file is allowed |
155
- | `merge: manual` | Label on a pull request | The merge policy, otherwise |
156
- | `verdict: override` | Label on a pull request | Only a person: passes the review verdict for one commit. Sessions never add it |
157
- | `follow-up` | Label on a ticket | The first follow-up line, on the one follow-ups ticket |
158
- | `spec` | Label on a ticket | Refinement, for a change your users will see, when [`specs: openspec`](../configuration.md#specs) |
159
- | Who merges | Status on a pull request | The merge policy: which way it goes, and why |
160
- | Review verdict | Status on a pull request | The review-verdict workflow: success only when the review said ready |
152
+ | Name | Kind | Set by |
153
+ | ------------------ | ------------------------ | ------------------------------------------------------------------------------------------------- |
154
+ | `merge-automatic` | Label on a pull request | The merge policy, when every file is allowed |
155
+ | `merge-manual` | Label on a pull request | The merge policy, otherwise |
156
+ | `verdict-override` | Label on a pull request | Only a person: passes the review verdict for one commit. Sessions never add it |
157
+ | `follow-up` | Label on a ticket | The first follow-up line, on the one follow-ups ticket |
158
+ | `spec` | Label on a ticket | Refinement, for a change your users will see, when [`specs: openspec`](../configuration.md#specs) |
159
+ | Who merges | Status on a pull request | The merge policy: which way it goes, and why |
160
+ | Review verdict | Status on a pull request | The review-verdict workflow: success only when the review said ready |
161
161
 
162
162
  ## Hooks
163
163
 
package/docs/plugins.md CHANGED
@@ -74,12 +74,12 @@ plugins:
74
74
  skill: acme-refine
75
75
  ```
76
76
 
77
- | Step | What happens |
78
- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
- | **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
80
- | **Handed** | The ticket's number. From `factory-build`, for a round of questions you approved while it waited on your answers, also the words "approved while waiting: fold the owner's replies into the body, post no marker". They tell the refiner to write your replies into the ticket's body and to post no [marker](glossary.md), the hidden comment line the board reads |
81
- | **Returns** | A ticket a build can start from: everything in the list below |
82
- | **Then** | The ticket waits for your approval, and the build reads what the refiner left |
77
+ | Step | What happens |
78
+ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
+ | **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
80
+ | **Handed** | The ticket's key. From `factory-build`, for a round of questions you approved while it waited on your answers, also the words "approved while waiting: fold the owner's replies into the body, post no marker". They tell the refiner to write your replies into the ticket's body and to post no [marker](glossary.md), the hidden comment line the board reads |
81
+ | **Returns** | A ticket a build can start from: everything in the list below |
82
+ | **Then** | The ticket waits for your approval, and the build reads what the refiner left |
83
83
 
84
84
  **What a refiner must deliver.** The board and the build read these, so a
85
85
  refiner that leaves one out leaves a ticket that cannot be built.
package/docs/workflow.md CHANGED
@@ -137,8 +137,9 @@ Follow-ups
137
137
  - [ ] tests/search.spec.ts: This test passes even when search returns nothing.
138
138
  ```
139
139
 
140
- There is one per repository, it carries the `follow-up` label, and there is
141
- nothing to configure. When you approve it, a session fixes every unchecked
140
+ There is one per repository, and it needs no setup. Its label is
141
+ `follow-up`, unless you rename it under
142
+ [`tickets.labels`](configuration.md#ticketslabels). When you approve it, a session fixes every unchecked
142
143
  line on one branch, one commit per line, in one pull request.
143
144
 
144
145
  **Why a checklist and not a ticket each.** Every ticket costs the same
@@ -161,13 +162,14 @@ rule it breaks, so it can be fixed as written.
161
162
 
162
163
  ## Who merges
163
164
 
164
- Every pull request gets one of two labels:
165
+ Every pull request gets one of two labels, which you can rename under
166
+ [`code-host.labels`](configuration.md#code-hostlabels):
165
167
 
166
- - **`merge: automatic`**: every file is allowed by your
168
+ - **`merge-automatic`**: every file is allowed by your
167
169
  [`auto-merge`](configuration.md#auto-merge) settings, and none of the
168
170
  commands you listed there held it. It merges itself once every check
169
171
  passes.
170
- - **`merge: manual`**: anything else. It waits for a person to merge it,
172
+ - **`merge-manual`**: anything else. It waits for a person to merge it,
171
173
  and a "Who merges" status on the pull request says what held it and
172
174
  why.
173
175
 
@@ -176,7 +178,7 @@ Two more things guard a merge:
176
178
  - **"Review verdict"** is a status, which you can make required on your
177
179
  default branch, that passes only when the automated
178
180
  review of the newest commit said it is ready, or an approver overrode it
179
- with the `verdict: override` label. Sessions never add that label.
181
+ with the `verdict-override` label. Sessions never add that label.
180
182
  - **Every review thread must be resolved.** A session answers each one,
181
183
  fixed or rejected with evidence, before resolving it.
182
184
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.11",
3
+ "version": "0.1.13",
4
4
  "description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/review.md CHANGED
@@ -56,21 +56,21 @@ defend.
56
56
  the facts; if you still disagree, say so once in the summary, with your
57
57
  evidence, rather than opening a new thread.
58
58
 
59
- 4. Read what the pull request was asked to do. Its body, and the issues it
60
- closes:
59
+ 4. Read what the pull request was asked to do: its body, and the tickets it
60
+ builds, which the workflow has read for you into the file TICKETS names.
61
+ Read that file with the Read tool. Each ticket there starts with a `## `
62
+ line naming it and its title. When the file says the tickets could not be
63
+ read, say so in the summary and go by the body.
61
64
 
62
65
  ```bash
63
- gh pr view PR_NUMBER --json body,closingIssuesReferences
64
- gh api graphql -F n=ISSUE_NUMBER -f query='query($n: Int!) { repository(owner: "OWNER", name: "NAME") { issue(number: $n) { body } } }' --jq .data.repository.issue.body
66
+ gh pr view PR_NUMBER --json body
65
67
  ```
66
68
 
67
- OWNER and NAME are the two halves of REPO.
68
-
69
- The issue's "Spec" and "Acceptance criteria" sections are what the
70
- change must do, and its "Decisions" are settled. An issue with neither
69
+ The ticket's "Spec" and "Acceptance criteria" sections are what the
70
+ change must do, and its "Decisions" are settled. A ticket with neither
71
71
  is held only to what it plainly asks for: a fix it suggests is not a
72
- criterion. The follow-ups issue, closed or only linked, is held to the lines the
73
- body says this pull request built. A pull request that closes no issue,
72
+ criterion. The follow-ups ticket is held to the lines the
73
+ body says this pull request built. A pull request that builds no ticket,
74
74
  such as a source audit, has only its body to go by.
75
75
 
76
76
  ## What to look for
@@ -79,7 +79,7 @@ defend.
79
79
  that is silently dropped.
80
80
  - **What it was asked to do.** A Spec line or criterion from step 4 that
81
81
  the whole pull request, `git diff origin/DEFAULT...HEAD`, does not meet, or
82
- meets only in part, is a finding, since the merge closes the issue as
82
+ meets only in part, is a finding, since the merge closes the ticket as
83
83
  done: High when a user would see the gap, Medium otherwise. Behavior
84
84
  no line asked for is Medium, unless the body or the owner's comments on
85
85
  the pull request explain it. Quote the line either way.