@davidbyoung/software-factory 0.1.9 → 0.1.10

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/dist/ticket.mjs CHANGED
@@ -67,6 +67,7 @@ import { boardConfigOf, checkFields } from "./board.mjs";
67
67
  import { refuseBareTags, refuseOverride } from "./guard-ticket-text.mjs";
68
68
  import { openTickets } from "./tickets/index.mjs";
69
69
  import { GROUPS, need, supports, } from "./tickets/types.mjs";
70
+ import { NotSignedInError } from "./code-host/types.mjs";
70
71
  export async function readComments(c, issue) {
71
72
  return (await c.tickets.read(issue)).comments;
72
73
  }
@@ -292,11 +293,28 @@ const READS_AND_WRITES = new Set([
292
293
  "open",
293
294
  "label",
294
295
  "link",
296
+ "branch",
295
297
  "blockers",
296
298
  "block",
297
299
  "unblock",
298
300
  "supports",
299
301
  ]);
302
+ /** The branch a build of `ticket` pushes, from `code-host.branch-name`. */
303
+ async function branchOf(ticket, d) {
304
+ let user = "";
305
+ if (d.branchName.includes("{user}"))
306
+ try {
307
+ user = await d.signedInAs(d.repository, d.codeHost);
308
+ }
309
+ catch (e) {
310
+ if (!(e instanceof NotSignedInError))
311
+ throw e;
312
+ throw new Error("code-host.branch-name uses {user}, and gh is not signed in: run gh auth login", { cause: e });
313
+ }
314
+ return d.branchName
315
+ .replaceAll("{ticket}", String(ticket))
316
+ .replaceAll("{user}", user);
317
+ }
300
318
  /** The commands that read or write a ticket for a skill. Null when
301
319
  * `command` is not one of them. */
302
320
  async function ticketCommand(command, args, d) {
@@ -413,6 +431,11 @@ async function ticketCommand(command, args, d) {
413
431
  case "link":
414
432
  d.out(t.linkText(numbered()));
415
433
  return 0;
434
+ case "branch": {
435
+ const ticket = await t.read(numbered());
436
+ d.out(await branchOf(ticket.number, d));
437
+ return 0;
438
+ }
416
439
  case "blockers": {
417
440
  const list = await need(t, "blockers").list(numbered());
418
441
  for (const b of list)
@@ -437,7 +460,7 @@ async function ticketCommand(command, args, d) {
437
460
  return null;
438
461
  }
439
462
  }
440
- const USAGE = "Usage: npx --no-install factory ticket claim|still-live|stop|end|refining|waiting|refined|ready|cost|view|list|edit|comment|open|label|link|blockers|block|unblock|supports|follow-up ...";
463
+ const USAGE = "Usage: npx --no-install factory ticket claim|still-live|stop|end|refining|waiting|refined|ready|cost|view|list|edit|comment|open|label|link|branch|blockers|block|unblock|supports|follow-up ...";
441
464
  export async function main(argv, deps) {
442
465
  const [command, first, ...rest] = argv;
443
466
  const issue = Number(first);
@@ -450,6 +473,8 @@ export async function main(argv, deps) {
450
473
  ...deps,
451
474
  config: boardConfigOf(settings),
452
475
  codeHost: settings.codeHost.type,
476
+ // Null only when init reads the settings to ask for it.
477
+ branchName: settings.codeHost.branchName,
453
478
  repository,
454
479
  board,
455
480
  ...opened,
@@ -561,6 +586,7 @@ export async function run(argv) {
561
586
  return main(argv, {
562
587
  open: (settings, target) => openTickets(settings, target),
563
588
  openPulls: (repository, codeHost) => openCodeHost(repository, codeHost).open(),
589
+ signedInAs: (repository, codeHost) => openCodeHost(repository, codeHost).signedInAs(),
564
590
  runner: (repository, name) => openRunner(repository, name),
565
591
  settings: () => loadSettings(),
566
592
  env: process.env,
package/docs/builds.md CHANGED
@@ -116,28 +116,40 @@ does no further check.
116
116
  ### What it reads from its environment
117
117
 
118
118
  On a server you host, the poller runs with no copy of your repository, so
119
- it takes everything from environment variables. All four are required; it
120
- exits at startup naming any that is missing. On a schedule it has a
119
+ it takes everything from environment variables. All five are required.
120
+ Without `FACTORY_REPOSITORY` it doesn't start. Without any of the others,
121
+ it logs `not polling:` naming each that is missing, and starts no build
122
+ until they are set. On a schedule it has a
121
123
  checkout, and needs only the token.
122
124
 
123
125
  | Variable | What it is |
124
126
  | ---------------------- | ------------------------------------------------------------------- |
125
127
  | `FACTORY_REPOSITORY` | The repository, as `owner/name` |
126
128
  | `FACTORY_BOARD_OWNER` | The account the board belongs to |
127
- | `FACTORY_BOARD_NUMBER` | Which board |
129
+ | `FACTORY_BOARD_NUMBER` | The board's number, the last part of its address |
128
130
  | `FACTORY_BOARD_TOKEN` | An access token that can read the board, comment, and start a build |
131
+ | `FACTORY_READY_COLUMN` | The column that approves a build |
129
132
 
130
- One more is optional. `FACTORY_READY_COLUMN` is the name of the column
131
- that approves a build, and defaults to Ready. The poller has no settings
132
- file, so a repository whose
133
- [`tickets.columns.ready`](configuration.md#ticketscolumns) names another
134
- column sets it where the poller runs. `factory board check` reminds you
135
- when it applies.
133
+ The repository, the board's number, and the ready column repeat what your
134
+ settings file says, because the poller cannot read it. The ready column
135
+ is the one [`tickets.columns.ready`](configuration.md#ticketscolumns)
136
+ names. [`factory board check`](cli.md) prints it on the ready row, for
137
+ you to copy:
136
138
 
137
- The repository and the board's number repeat what your settings file says,
138
- because the poller cannot read it. The factory takes the board's owner to
139
- be the repository's owner everywhere else, a person or an organization, so
140
- a board owned by another account is not supported yet.
139
+ ```text
140
+ ? ready Ready: the poller needs FACTORY_READY_COLUMN set to "Ready"
141
+ ```
142
+
143
+ A poller only runs with a ready column: with `ready: none`, builds start
144
+ only when you ask, and there is no poller to host.
145
+
146
+ A poller set up before `FACTORY_READY_COLUMN` was required logs
147
+ `not polling: FACTORY_READY_COLUMN not set` after an update, and polls
148
+ nothing until you set it.
149
+
150
+ The factory takes the board's owner to be the repository's owner
151
+ everywhere else, a person or an organization, so a board owned by another
152
+ account is not supported yet.
141
153
 
142
154
  ### Its limits
143
155
 
@@ -171,6 +183,7 @@ docker run \
171
183
  -e FACTORY_BOARD_OWNER=your-name \
172
184
  -e FACTORY_BOARD_NUMBER=1 \
173
185
  -e FACTORY_BOARD_TOKEN \
186
+ -e FACTORY_READY_COLUMN=Ready \
174
187
  ghcr.io/davidbyoung/software-factory-poller:0.2.0
175
188
  ```
176
189
 
package/docs/cli.md CHANGED
@@ -51,7 +51,7 @@ nothing to fix.
51
51
  `doctor` prints its checks under headings: `Settings and files`, then
52
52
  each tool's name, such as `GitHub` or `Claude Code`, then the parts you
53
53
  left off. Each check starts with a mark: ✓ works, ✗ needs fixing, ?
54
- can't be told from here, and - off on purpose. `doctor` exits 1 when a
54
+ worth a look, and - off on purpose. `doctor` exits 1 when a
55
55
  check fails. GitHub never lets a secret be read back, so `doctor` checks
56
56
  only that each secret your parts read is set.
57
57
 
@@ -137,32 +137,33 @@ 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
- | Command | What it does |
141
- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
142
- | `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors |
143
- | `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else |
144
- | `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs |
145
- | `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
146
- | `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 |
147
- | `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image |
148
- | `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its number. `--label LABEL` adds a label |
149
- | `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
150
- | `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no` |
151
- | `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12" |
152
- | `factory ticket blockers N` | One line per ticket N waits on: its number and whether it is open |
153
- | `factory ticket block N --by M` | Records that N waits on M |
154
- | `factory ticket unblock N --by M` | Removes that record |
155
- | `factory ticket supports GROUP` | Prints `yes` or `no` for `board`, `blockers`, `label-history`, or `attachments` |
156
- | `factory ticket claim N` | Claims ticket N for this session. Prints `claimed`, `held by`, or `blocked by` |
157
- | `factory ticket still-live N` | Says whether this session still holds N |
158
- | `factory ticket stop N "reason"` | Releases N and says why |
159
- | `factory ticket end N` | A run's last step: releases this session's claim if no open pull request links N. Prints `released`, `kept`, or `not live` |
160
- | `factory ticket refining N` | Marks N as being refined |
161
- | `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
162
- | `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
163
- | `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
164
- | `factory ticket cost N` | Notes what this session spent on N since it started |
165
- | `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 |
140
+ | Command | What it does |
141
+ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
142
+ | `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors |
143
+ | `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else |
144
+ | `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs |
145
+ | `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
146
+ | `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 |
147
+ | `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image |
148
+ | `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its number. `--label LABEL` adds a label |
149
+ | `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
150
+ | `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no` |
151
+ | `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12" |
152
+ | `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 |
153
+ | `factory ticket blockers N` | One line per ticket N waits on: its number and whether it is open |
154
+ | `factory ticket block N --by M` | Records that N waits on M |
155
+ | `factory ticket unblock N --by M` | Removes that record |
156
+ | `factory ticket supports GROUP` | Prints `yes` or `no` for `board`, `blockers`, `label-history`, or `attachments` |
157
+ | `factory ticket claim N` | Claims ticket N for this session. Prints `claimed`, `held by`, or `blocked by` |
158
+ | `factory ticket still-live N` | Says whether this session still holds N |
159
+ | `factory ticket stop N "reason"` | Releases N and says why |
160
+ | `factory ticket end N` | A run's last step: releases this session's claim if no open pull request links N. Prints `released`, `kept`, or `not live` |
161
+ | `factory ticket refining N` | Marks N as being refined |
162
+ | `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
163
+ | `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
164
+ | `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
165
+ | `factory ticket cost N` | Notes what this session spent on N since it started |
166
+ | `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 |
166
167
 
167
168
  `factory ticket refined N` posts nothing and exits 1 when N's body lacks a
168
169
  section a build reads, printing one line for each, such as
@@ -182,6 +183,7 @@ ticket system.
182
183
  | `factory pr reply N COMMENT --body-file FILE` | Replies on a thread |
183
184
  | `factory pr resolve N COMMENT` | Resolves a thread |
184
185
  | `factory pr closes N` | The tickets N closes |
186
+ | `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 |
185
187
  | `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
186
188
  | `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 |
187
189
  | `factory pr comments N` | N's conversation comments: ID, author, time, and first line. `--author LOGIN`, `--contains TEXT`, and `--json`, which prints each comment's `id`, `user.login`, `body`, and `created_at` |
@@ -223,6 +225,7 @@ You can run them too.
223
225
  | `factory test-one FILE [NAME]` | Runs [`commands.test-one`](configuration.md#commandstest-one), one test file alone or the one test NAME in it, and exits with its status |
224
226
  | `factory end-to-end FILE [--times K]` | Runs [`commands.end-to-end`](configuration.md#commandsend-to-end), one end-to-end spec alone, and exits with its status. With `--times K`, K times in a row, stopping at the first run that fails. Ends with `✓ The test passed.` or `✗ The test failed.` |
225
227
  | `factory specs check` | Runs [`specs.check`](configuration.md#specscheck), the check of your written specs, and exits with its status, ending with `✓ The specs check passed.` or `✗ The specs check failed.`. Prints `specs are off` when `specs` is `none` |
228
+ | `factory specs change-name N` | Prints the name of the OpenSpec change a build of N writes, always `issue-N` whatever [`code-host.branch-name`](configuration.md#code-host) says. Exits 1 with `specs are off: there is no spec change to name` when [`specs`](configuration.md#specs) is `none` |
226
229
  | `factory default-branch` | Prints the name of your repository's default branch, which nothing in the factory assumes is `main` |
227
230
 
228
231
  `factory default-branch` asks, in turn, the event of the workflow run it
@@ -34,9 +34,10 @@ The [glossary](glossary.md) has the rest.
34
34
 
35
35
  ## How the file works
36
36
 
37
- - **Two settings are required, and a third before any build.** Every
38
- file has [`version`](#version) and [`repository`](#repository), and a
39
- session can't build a ticket until you set
37
+ - **Three settings are required, and a fourth before any build.** Every
38
+ file has [`version`](#version), [`repository`](#repository), and
39
+ [`code-host.branch-name`](#code-host), which `factory init` writes for
40
+ you, and a session can't build a ticket until you set
40
41
  [`commands.gate`](#commandsgate). Every other setting has a default, and
41
42
  you write it only when you want something else.
42
43
  - **It holds only what a script needs.** Anything that needs judgment,
@@ -85,6 +86,9 @@ The [glossary](glossary.md) has the rest.
85
86
  ```yaml
86
87
  version: 2
87
88
  repository: your-name/your-repo
89
+ code-host:
90
+ type: github
91
+ branch-name: "{ticket}"
88
92
  ```
89
93
 
90
94
  With only this, the factory refines a ticket when you run `/factory-refine N` in a session,
@@ -177,6 +181,13 @@ Where your tickets live, and which board shows them.
177
181
  tickets:
178
182
  type: github
179
183
  board: 1
184
+ columns:
185
+ backlog: Backlog
186
+ refining: In refinement
187
+ ready: Ready
188
+ building: In progress
189
+ review: In review
190
+ done: Done
180
191
  ```
181
192
 
182
193
  - **`type`** is the ticket system. Only `github` is built, and it is the
@@ -184,6 +195,8 @@ tickets:
184
195
  - **`board`** is your GitHub Project's number: the last part of its
185
196
  address, such as `1` in `github.com/users/your-name/projects/1`. The
186
197
  default, `none`, means no board.
198
+ - **`columns`** says which of the board's columns shows each state, and a
199
+ board needs it: see [`tickets.columns`](#ticketscolumns).
187
200
 
188
201
  Without a board, `factory status` still shows every ticket's state, which
189
202
  the factory keeps in comments on the ticket. Builds then start only when
@@ -199,12 +212,14 @@ with it.
199
212
  #### `tickets.columns`
200
213
 
201
214
  The board has one column for each of the six
202
- [states](workflow.md#the-six-states) a ticket goes through. If your
203
- board's columns have the factory's names, write nothing here. If they have
204
- other names, or your board has fewer columns, say which column shows each
205
- state. `factory init` suggests this block when you choose a board without the
206
- factory's columns: see
215
+ [states](workflow.md#the-six-states) a ticket goes through. This block
216
+ says which of your board's columns shows each state, and it names all
217
+ six. `factory init` writes it for you, from the board you choose: see
207
218
  [You already have a board](existing-repo.md#you-already-have-a-board).
219
+ There is no default: your board's column names may not be the
220
+ factory's, and a guess would put tickets in the wrong column without
221
+ telling you.
222
+
208
223
  A new GitHub Project starts with only Todo, In Progress, and Done,
209
224
  so its settings would be:
210
225
 
@@ -213,73 +228,86 @@ tickets:
213
228
  board: 7
214
229
  columns:
215
230
  backlog: Todo
216
- building: In Progress
217
- done: Done
218
231
  refining: none
219
232
  ready: none
233
+ building: In Progress
220
234
  review: none
235
+ done: Done
221
236
  builds:
222
237
  trigger: manual
223
238
  ```
224
239
 
225
- The factory's own names, used for any state you leave out, are:
240
+ When init creates your board, or adds columns to one, it gives them the
241
+ factory's own names:
226
242
 
227
- | State | Column the factory looks for |
228
- | ---------- | ---------------------------- |
229
- | `backlog` | Backlog |
230
- | `refining` | In refinement |
231
- | `ready` | Ready |
232
- | `building` | In progress |
233
- | `review` | In review |
234
- | `done` | Done |
243
+ | Key | Name of the column init creates |
244
+ | ---------- | ------------------------------- |
245
+ | `backlog` | Backlog |
246
+ | `refining` | In refinement |
247
+ | `ready` | Ready |
248
+ | `building` | In progress |
249
+ | `review` | In review |
250
+ | `done` | Done |
235
251
 
236
252
  - **Capitals don't matter,** so "In progress" finds your "In Progress".
237
253
  - **`none` means your board has no column for that state.** A ticket in
238
254
  that state stays in the column of the state before it. With
239
255
  `review: none`, a ticket whose pull request is in review stays in In
240
- progress. Every state can be `none` except `backlog`.
256
+ Progress. Every state can be `none` except `backlog`.
241
257
  - **A state can take a list of columns,** when more than one of yours
242
- means it. `factory init` suggests one column for each state, so you
243
- write a list yourself. A ticket in any of the columns is in that
244
- state. When the factory moves a ticket into the state, it uses the
245
- first, and a ticket already in any of them stays where it is:
258
+ means it. Init never writes a list, so add one to the block yourself.
259
+ A ticket in any of the columns is in that state. When the factory
260
+ moves a ticket into the state, it uses the first, and a ticket already
261
+ in any of them stays where it is:
246
262
 
247
263
  ```yaml
248
264
  tickets:
249
265
  board: 7
250
266
  columns:
251
267
  backlog: Todo
268
+ refining: none
269
+ ready: none
270
+ building: In Progress
252
271
  # When a pull request opens, its ticket moves to Code review.
253
272
  # One you moved to QA stays there.
254
273
  review: [Code review, QA]
274
+ done: Done
255
275
  ```
256
276
 
257
277
  `ready` takes one column, since only a ticket you approved goes there.
258
278
 
259
- - **A ticket never falls back into Ready,** since only a ticket you
260
- approved goes there, so the fallback skips it. With `building: none`
261
- alone, a ticket being built has no column of its own, the state before
262
- building is ready, and Ready is skipped, so it shows in In refinement.
279
+ - **A ticket never stays in the ready column unless you approved it.**
280
+ With `building: none`, a ticket being built would stay in ready's
281
+ column, so it stays in refining's column instead. On a board with the
282
+ factory's columns and `building: none`, it shows in In refinement.
263
283
  - **With `ready: none`, nothing on the board approves a build,** so you
264
284
  need `builds.trigger: manual`, and you start each build by asking a
265
285
  session.
266
286
  - **A ticket in a column no state uses is left alone.** The board sync
267
287
  doesn't move it or fill in its fields, and nothing builds it.
268
- - **If you host your own poller** and rename the Ready column, the poller
269
- needs the new name too: see `FACTORY_READY_COLUMN` in
288
+ - **If you host your own poller,** it needs `FACTORY_READY_COLUMN` set
289
+ to the column `ready` names: see
270
290
  [Builds](builds.md#what-it-reads-from-its-environment).
271
291
 
272
292
  `factory config check` stops, naming the key, when `columns` has:
273
293
 
294
+ - no `board` beside it, or a `board` with no `columns`;
295
+ - a state left out, naming each one;
274
296
  - a state it doesn't know;
275
297
  - `backlog: none`;
276
298
  - one column for two states;
277
299
  - an empty list, or a list for `ready`;
278
- - no `board` beside it;
279
300
  - `ready: none` while [`builds.trigger`](#builds) isn't `manual`,
280
301
  since then a build starts only from the ready column.
281
302
 
282
- It doesn't read your board: `factory board check` does.
303
+ Such as:
304
+
305
+ ```text
306
+ .claude/factory.yaml: tickets.columns: building and done have no column: give each a column, a list of columns, or none, or run factory init to choose them
307
+ ```
308
+
309
+ `factory config check` doesn't read your board. `factory board check`
310
+ does, and says which of the columns you named the board lacks.
283
311
 
284
312
  #### `tickets.fields`
285
313
 
@@ -373,13 +401,104 @@ you confirm them.
373
401
 
374
402
  ### `code-host`
375
403
 
376
- Where your repository and its pull requests live. Only `github` is built,
377
- and it is the default, so most files leave this out.
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.
378
407
 
379
408
  ```yaml
380
- code-host: github
409
+ code-host:
410
+ type: github
411
+ branch-name: "feature/{user}/{ticket}"
412
+ ```
413
+
414
+ - **`type`** is the code host. GitHub is the only one so far, and it is
415
+ the default.
416
+ - **`branch-name`** is the pattern for the branch's name. It has no
417
+ default: [`factory init`](github/setup.md) asks for it and offers
418
+ `{ticket}`, so ticket 12 is built on a branch named `12`. A
419
+ [preset](#presets) can set it for every repository that follows it.
420
+
421
+ Without `branch-name`, `factory config check` stops:
422
+
423
+ ```text
424
+ .claude/factory.yaml: code-host.branch-name: is required. Run factory init to set it, or add it, such as branch-name: "{ticket}"
425
+ ```
426
+
427
+ A pattern uses these placeholders. It must have `{ticket}`; `{user}` is
428
+ for a convention that names who did the work, and a pattern can leave
429
+ it out:
430
+
431
+ | Placeholder | What it becomes | For ticket 12 |
432
+ | ----------- | ------------------------------------ | ------------- |
433
+ | `{ticket}` | The ticket's number, without `#` | `12` |
434
+ | `{user}` | The GitHub account the build runs as | `octocat` |
435
+
436
+ In a session, `{user}` is the account the GitHub CLI, `gh`, is signed in
437
+ as, exactly as GitHub spells it, so the same ticket built by two people
438
+ gets two branches. In GitHub Actions, it is the owner of
439
+ the [token the build runs with](github/reference.md#workflows), not
440
+ whoever approved the ticket, so with a shared bot account every branch
441
+ built in Actions carries the bot's name.
442
+
443
+ Keep the quotes, as in the examples. YAML reads an unquoted
444
+ `branch-name: {ticket}` as a map rather than as text, and
445
+ `factory config check` stops and says to quote it.
446
+
447
+ `{ticket}` gives each ticket its own branch, and the same branch every
448
+ time. So a ticket built a second time, such as the
449
+ [follow-ups ticket](workflow.md#follow-ups), a reopened ticket, or one whose first
450
+ build stopped, finds its earlier branch still on GitHub, unless GitHub
451
+ deleted it when its pull request merged. What the build does depends on
452
+ that branch's newest pull request:
453
+
454
+ - **Merged, with nothing pushed to the branch since:** the build deletes
455
+ the old branch and starts fresh, since its work is already merged.
456
+ - **Open:** the build stops before it starts and names the pull request.
457
+ Work that one instead, with `/factory-address-review N` for pull
458
+ request N.
459
+ - **Anything else:** closed without merging, no pull request at all, or
460
+ merged with commits pushed since. The build stops before it starts, so
461
+ no work is lost:
462
+
463
+ ```text
464
+ Branch 12 is already on origin, with work no pull request merged. Open a pull request from it to keep that work, or delete it with: git push origin --delete 12
465
+ ```
466
+
467
+ A build that stopped partway pushes its branch so its work is kept. To
468
+ keep it, open a pull request from the branch on GitHub. Otherwise
469
+ delete the branch, and build the ticket again with `/factory-build 12`.
470
+
471
+ Once you change the pattern, run `factory config check`, then
472
+ `factory sync` (every setting needs it, as
473
+ [How the file works](#how-the-file-works) says), then see what the
474
+ pattern gives one ticket:
475
+
476
+ ```console
477
+ $ factory config check
478
+ ✓ The settings are valid.
479
+ $ factory ticket branch 12
480
+ feature/octocat/12
381
481
  ```
382
482
 
483
+ `factory config check` stops on a placeholder it doesn't know, a pattern
484
+ without `{ticket}`, and a pattern git can't use as a branch name. Git
485
+ refuses a name that:
486
+
487
+ - has a space, a control character, `..`, `//`, or `@{`
488
+ - has any of `~`, `^`, `:`, `?`, `*`, `[`, or `\`
489
+ - starts with `-` or `/`, or ends with `/`, `.`, or `.lock`
490
+ - has a part between slashes that starts with `.` or ends with `.lock`
491
+
492
+ Anything else is fine, `#` and `_` included. The check names the first
493
+ fault it finds:
494
+
495
+ ```text
496
+ .claude/factory.yaml: code-host.branch-name: feature//{ticket} can't be a git branch name: it has //
497
+ ```
498
+
499
+ Commit `.claude/factory.yaml` and `.claude/factory.lock`. The next build
500
+ uses the new pattern; branches already pushed keep their names.
501
+
383
502
  ### `builds`
384
503
 
385
504
  What starts a build when you approve a ticket, and where the build runs.
@@ -1101,6 +1220,17 @@ repository: harbor-goods/storefront
1101
1220
 
1102
1221
  tickets:
1103
1222
  board: 1
1223
+ columns:
1224
+ backlog: Backlog
1225
+ refining: In refinement
1226
+ ready: Ready
1227
+ building: In progress
1228
+ review: In review
1229
+ done: Done
1230
+
1231
+ code-host:
1232
+ type: github
1233
+ branch-name: "{ticket}"
1104
1234
 
1105
1235
  builds:
1106
1236
  trigger: own-server
@@ -1170,6 +1300,17 @@ repository: riverbend-studio/site
1170
1300
 
1171
1301
  tickets:
1172
1302
  board: 4
1303
+ columns:
1304
+ backlog: Backlog
1305
+ refining: In refinement
1306
+ ready: Ready
1307
+ building: In progress
1308
+ review: In review
1309
+ done: Done
1310
+
1311
+ code-host:
1312
+ type: github
1313
+ branch-name: "{ticket}"
1173
1314
 
1174
1315
  commands:
1175
1316
  before-commit:
@@ -1193,6 +1334,17 @@ repository: northwind-php/ledger
1193
1334
 
1194
1335
  tickets:
1195
1336
  board: 2
1337
+ columns:
1338
+ backlog: Backlog
1339
+ refining: In refinement
1340
+ ready: Ready
1341
+ building: In progress
1342
+ review: In review
1343
+ done: Done
1344
+
1345
+ code-host:
1346
+ type: github
1347
+ branch-name: "{ticket}"
1196
1348
 
1197
1349
  commands:
1198
1350
  build-setup: