@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.
- package/agents/factory-e2e-reviewer.md +1 -1
- package/agents/factory-test-reviewer.md +1 -1
- package/agents/factory-ui-reviewer.md +2 -2
- package/dist/board.d.mts +9 -7
- package/dist/board.mjs +59 -36
- package/dist/build.d.mts +4 -0
- package/dist/build.mjs +9 -4
- package/dist/cli.mjs +8 -1
- package/dist/code-host/github.mjs +9 -4
- package/dist/code-host/types.d.mts +4 -2
- package/dist/commands.d.mts +1 -1
- package/dist/commands.mjs +16 -7
- package/dist/config.d.mts +7 -0
- package/dist/config.mjs +68 -5
- package/dist/explain.mjs +6 -0
- package/dist/guard-commit.d.mts +3 -3
- package/dist/guard-commit.mjs +31 -6
- package/dist/guard-ticket-text.d.mts +3 -2
- package/dist/guard-ticket-text.mjs +7 -4
- package/dist/labels.d.mts +28 -0
- package/dist/labels.mjs +36 -0
- package/dist/lib/clock.d.mts +3 -1
- package/dist/lib/clock.mjs +12 -6
- package/dist/lib/pull-tickets.d.mts +15 -0
- package/dist/lib/pull-tickets.mjs +12 -0
- package/dist/lib/refined-check.d.mts +1 -1
- package/dist/lib/refined-check.mjs +3 -5
- package/dist/lib/usage.d.mts +3 -1
- package/dist/lib/usage.mjs +4 -2
- package/dist/lib/work-status.d.mts +29 -23
- package/dist/lib/work-status.mjs +30 -33
- package/dist/merge-policy.d.mts +9 -7
- package/dist/merge-policy.mjs +13 -11
- package/dist/poller.d.mts +5 -3
- package/dist/poller.mjs +27 -17
- package/dist/pr.d.mts +22 -0
- package/dist/pr.mjs +60 -10
- package/dist/remove.mjs +16 -9
- package/dist/review-tickets.d.mts +12 -0
- package/dist/review-tickets.mjs +59 -0
- package/dist/review-verdict.d.mts +6 -1
- package/dist/review-verdict.mjs +15 -9
- package/dist/reviewers.d.mts +7 -4
- package/dist/reviewers.mjs +19 -12
- package/dist/runner/github-actions.mjs +6 -7
- package/dist/runner/types.d.mts +7 -6
- package/dist/status.d.mts +19 -7
- package/dist/status.mjs +38 -23
- package/dist/sync.d.mts +8 -0
- package/dist/sync.mjs +30 -1
- package/dist/ticket-fields.d.mts +4 -2
- package/dist/ticket-fields.mjs +10 -3
- package/dist/ticket.d.mts +14 -7
- package/dist/ticket.mjs +121 -72
- package/dist/tickets/github.d.mts +10 -2
- package/dist/tickets/github.mjs +74 -20
- package/dist/tickets/index.d.mts +9 -2
- package/dist/tickets/index.mjs +20 -5
- package/dist/tickets/types.d.mts +59 -30
- package/dist/tickets/types.mjs +13 -3
- package/dist/tool-names.d.mts +7 -0
- package/dist/tool-names.mjs +1 -0
- package/dist/tools.d.mts +4 -1
- package/dist/tools.mjs +5 -0
- package/docs/cli.md +12 -8
- package/docs/configuration.md +179 -9
- package/docs/developing.md +17 -9
- package/docs/github/by-hand.md +2 -2
- package/docs/github/reference.md +22 -22
- package/docs/plugins.md +6 -6
- package/docs/workflow.md +8 -6
- package/package.json +1 -1
- package/review.md +11 -11
- package/rules.md +25 -16
- package/settings.schema.json +45 -0
- package/skills/factory-address-review/SKILL.md +7 -6
- package/skills/factory-build/SKILL.md +28 -22
- package/skills/factory-refine/SKILL.md +1 -1
- package/skills/factory-resolve-conflicts/SKILL.md +5 -4
- package/workflows/factory-build.yml +6 -5
- package/workflows/factory-claude-review.yml +38 -1
- package/workflows/factory-conflicts.yml +1 -1
- package/workflows/factory-merge-policy.yml +8 -7
- package/workflows/factory-review-verdict.yml +1 -1
- 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 `
|
|
145
|
-
| `factory ticket list` | Lists the open tickets:
|
|
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
|
|
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
|
|
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 |
|
package/docs/configuration.md
CHANGED
|
@@ -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
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
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
|
|
405
|
-
[build](#words-this-page-uses) names the branch it pushes, in a
|
|
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
|
|
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.
|
package/docs/developing.md
CHANGED
|
@@ -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
|
|
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
|
-
|
|
|
230
|
-
|
|
|
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
|
|
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
|
-
|
|
|
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.
|
|
290
|
-
|
|
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
|
package/docs/github/by-hand.md
CHANGED
|
@@ -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
|
|
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
|
|
256
|
+
the `merge-automatic` label.
|
|
257
257
|
|
|
258
258
|
## Signed commits from cloud builds
|
|
259
259
|
|
package/docs/github/reference.md
CHANGED
|
@@ -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
|
|
40
|
-
|
|
|
41
|
-
| Secrets and variables named `FACTORY_...`
|
|
42
|
-
| `CLAUDE_CODE_OAUTH_TOKEN`
|
|
43
|
-
| The secrets your `.npmrc` reads, such as `NPM_TOKEN`, for Actions and for Dependabot
|
|
44
|
-
| Labels: `merge
|
|
45
|
-
| A CI check that the factory's files are in step
|
|
46
|
-
| A "Review verdict" required check, as the ruleset "Software factory"
|
|
47
|
-
| Statuses on pull requests: "Who merges", "Review verdict"
|
|
48
|
-
| One open ticket titled "Follow-ups"
|
|
49
|
-
| Comments on tickets the factory worked
|
|
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
|
|
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
|
|
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
|
|
153
|
-
|
|
|
154
|
-
| `merge
|
|
155
|
-
| `merge
|
|
156
|
-
| `verdict
|
|
157
|
-
| `follow-up`
|
|
158
|
-
| `spec`
|
|
159
|
-
| Who merges
|
|
160
|
-
| Review verdict
|
|
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
|
|
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
|
|
141
|
-
|
|
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
|
|
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
|
|
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
|
|
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
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
|
|
60
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
73
|
-
body says this pull request built. A pull request that
|
|
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
|
|
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.
|