@davidbyoung/software-factory 0.1.12 → 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 (55) hide show
  1. package/dist/board.d.mts +3 -1
  2. package/dist/board.mjs +12 -6
  3. package/dist/commands.mjs +1 -1
  4. package/dist/config.d.mts +7 -0
  5. package/dist/config.mjs +68 -5
  6. package/dist/explain.mjs +6 -0
  7. package/dist/guard-commit.d.mts +3 -3
  8. package/dist/guard-commit.mjs +31 -6
  9. package/dist/guard-ticket-text.d.mts +3 -2
  10. package/dist/guard-ticket-text.mjs +7 -4
  11. package/dist/labels.d.mts +28 -0
  12. package/dist/labels.mjs +36 -0
  13. package/dist/lib/refined-check.d.mts +1 -1
  14. package/dist/lib/refined-check.mjs +3 -5
  15. package/dist/lib/work-status.d.mts +6 -4
  16. package/dist/lib/work-status.mjs +17 -7
  17. package/dist/merge-policy.d.mts +9 -7
  18. package/dist/merge-policy.mjs +13 -11
  19. package/dist/poller.d.mts +3 -1
  20. package/dist/poller.mjs +10 -4
  21. package/dist/pr.d.mts +4 -0
  22. package/dist/pr.mjs +6 -3
  23. package/dist/remove.mjs +16 -9
  24. package/dist/review-verdict.d.mts +6 -1
  25. package/dist/review-verdict.mjs +15 -9
  26. package/dist/status.d.mts +2 -0
  27. package/dist/status.mjs +6 -3
  28. package/dist/sync.d.mts +4 -0
  29. package/dist/sync.mjs +17 -1
  30. package/dist/ticket-fields.d.mts +4 -2
  31. package/dist/ticket-fields.mjs +10 -3
  32. package/dist/ticket.d.mts +2 -1
  33. package/dist/ticket.mjs +30 -15
  34. package/dist/tickets/index.d.mts +2 -1
  35. package/dist/tickets/index.mjs +5 -4
  36. package/dist/tool-names.d.mts +7 -0
  37. package/dist/tool-names.mjs +1 -0
  38. package/dist/tools.d.mts +4 -1
  39. package/dist/tools.mjs +5 -0
  40. package/docs/cli.md +1 -1
  41. package/docs/configuration.md +178 -8
  42. package/docs/developing.md +1 -1
  43. package/docs/github/by-hand.md +2 -2
  44. package/docs/github/reference.md +21 -21
  45. package/docs/workflow.md +8 -6
  46. package/package.json +1 -1
  47. package/rules.md +7 -2
  48. package/settings.schema.json +45 -0
  49. package/skills/factory-address-review/SKILL.md +3 -3
  50. package/skills/factory-build/SKILL.md +3 -3
  51. package/skills/factory-resolve-conflicts/SKILL.md +1 -1
  52. package/workflows/factory-conflicts.yml +1 -1
  53. package/workflows/factory-merge-policy.yml +8 -7
  54. package/workflows/factory-review-verdict.yml +1 -1
  55. package/workflows/factory-review.yml +1 -1
package/dist/ticket.mjs CHANGED
@@ -63,6 +63,7 @@ import { openRunner } from "./runner/index.mjs";
63
63
  import { loadSettings, targetOf } from "./config.mjs";
64
64
  import { AGENT_MARK, commentBody, sameName, reviewingPulls, workState, } from "./lib/work-status.mjs";
65
65
  import { missingParts } from "./lib/refined-check.mjs";
66
+ import { labelOf, shownLabels } from "./labels.mjs";
66
67
  import { commonDir, readClock, writeClock } from "./lib/clock.mjs";
67
68
  import { costNote, measureSession, projectsDir } from "./lib/usage.mjs";
68
69
  import { boardConfigOf, checkFields } from "./board.mjs";
@@ -198,7 +199,7 @@ async function end(issue, who, d) {
198
199
  if (!mine)
199
200
  return "not live";
200
201
  const pulls = linkPulls(await d.openPulls(d.repository, d.codeHost), d.tickets, d.own);
201
- if (reviewingPulls(ticket, pulls).length > 0)
202
+ if (reviewingPulls(ticket, pulls, d.labels.tickets["follow-up"]).length > 0)
202
203
  return "kept";
203
204
  await post(d, issue, { kind: "ended", issue: named(d, issue) });
204
205
  return "released";
@@ -210,7 +211,8 @@ export function withLine(body, line) {
210
211
  * is open. The file leads the line, so each one names what it is about. */
211
212
  async function followUp(file, text, d) {
212
213
  const line = `- [ ] ${file}: ${text}`;
213
- const open = (await d.tickets.listOpen()).filter((t) => t.labels.includes("follow-up"));
214
+ const label = d.labels.tickets["follow-up"];
215
+ const open = (await d.tickets.listOpen()).filter((t) => t.labels.includes(label));
214
216
  const [first] = open.sort((a, b) => compareKeys(a.key, b.key));
215
217
  if (first) {
216
218
  const issue = await d.tickets.read(first.key);
@@ -220,7 +222,7 @@ async function followUp(file, text, d) {
220
222
  const body = withLine('Small problems noticed while doing other work, one line each, built together once the owner approves this issue. See "Follow-ups" in `.claude/factory/rules.md`.\n', line);
221
223
  const made = await d.tickets.open({
222
224
  title: "Follow-ups",
223
- labels: ["follow-up"],
225
+ labels: [label],
224
226
  body,
225
227
  });
226
228
  return `opened ${d.tickets.ref(made)}`;
@@ -282,11 +284,11 @@ function options(args, name) {
282
284
  }
283
285
  /** A ticket for a reader: title, state, labels, body, and each comment with
284
286
  * its ID and author. */
285
- export function formatTicket(t, ref) {
287
+ export function formatTicket(t, ref, names) {
286
288
  const lines = [
287
289
  `${ref} ${t.title}`,
288
290
  `state: ${t.state}`,
289
- `labels: ${t.labels.join(", ") || "(none)"}`,
291
+ `labels: ${shownLabels(t.labels, names).join(", ") || "(none)"}`,
290
292
  "",
291
293
  t.body.trimEnd() || "(no body)",
292
294
  ];
@@ -358,6 +360,10 @@ async function ticketCommand(command, args, d) {
358
360
  return t.key(args[0]);
359
361
  };
360
362
  const json = args.includes("--json");
363
+ const names = d.labels.tickets;
364
+ /** A ticket label's key as its name, and the override's too, which a
365
+ * session may ask about or remove but never add. */
366
+ const named = (word) => labelOf({ ...names, "verdict-override": d.labels.codeHost["verdict-override"] }, word);
361
367
  switch (command) {
362
368
  case "view": {
363
369
  const ticket = await t.read(keyed());
@@ -365,11 +371,11 @@ async function ticketCommand(command, args, d) {
365
371
  if (json)
366
372
  d.out(JSON.stringify(withRef(ticket, t), null, 2));
367
373
  else if (field === undefined)
368
- formatTicket(ticket, t.ref(ticket.key)).forEach(d.out);
374
+ formatTicket(ticket, t.ref(ticket.key), names).forEach(d.out);
369
375
  else if (!FIELDS.includes(field))
370
376
  throw new Error(`--field is one of ${FIELDS.join(", ")}.`);
371
377
  else if (field === "labels")
372
- ticket.labels.forEach(d.out);
378
+ shownLabels(ticket.labels, names).forEach(d.out);
373
379
  else if (field === "ref")
374
380
  d.out(t.ref(ticket.key));
375
381
  else
@@ -389,7 +395,8 @@ async function ticketCommand(command, args, d) {
389
395
  return 0;
390
396
  }
391
397
  case "list": {
392
- const label = option(args, "--label");
398
+ const given = option(args, "--label");
399
+ const label = given === undefined ? undefined : labelOf(names, given);
393
400
  const title = option(args, "--title");
394
401
  const kept = (await t.listOpen())
395
402
  .filter((x) => label === undefined || x.labels.includes(label))
@@ -399,7 +406,7 @@ async function ticketCommand(command, args, d) {
399
406
  d.out(JSON.stringify(kept.map((x) => withRef(x, t)), null, 2));
400
407
  else
401
408
  for (const x of kept)
402
- d.out(`${x.key}\t${x.title}\t${x.labels.join(", ")}`);
409
+ d.out(`${x.key}\t${x.title}\t${shownLabels(x.labels, names).join(", ")}`);
403
410
  return 0;
404
411
  }
405
412
  case "edit":
@@ -447,7 +454,11 @@ async function ticketCommand(command, args, d) {
447
454
  const body = d.readFile(file);
448
455
  refuseBareTags(title);
449
456
  refuseBareTags(body);
450
- d.out(String(await t.open({ title, body, labels: options(args, "--label") })));
457
+ d.out(String(await t.open({
458
+ title,
459
+ body,
460
+ labels: options(args, "--label").map((l) => labelOf(names, l)),
461
+ })));
451
462
  return 0;
452
463
  }
453
464
  case "label": {
@@ -460,15 +471,15 @@ async function ticketCommand(command, args, d) {
460
471
  throw new Error(USAGE);
461
472
  if (was !== undefined) {
462
473
  const history = need(t, "label-history");
463
- d.out((await history.wasRemoved(ticket, was)) ? "yes" : "no");
474
+ d.out((await history.wasRemoved(ticket, named(was))) ? "yes" : "no");
464
475
  }
465
476
  else if (add !== undefined) {
466
- refuseOverride(add);
467
- await t.addLabel(ticket, add);
477
+ refuseOverride(add, d.labels.codeHost["verdict-override"]);
478
+ await t.addLabel(ticket, labelOf(names, add));
468
479
  d.out("added");
469
480
  }
470
481
  else {
471
- await t.removeLabel(ticket, removed);
482
+ await t.removeLabel(ticket, named(removed));
472
483
  d.out("removed");
473
484
  }
474
485
  return 0;
@@ -536,6 +547,10 @@ export async function main(argv, deps) {
536
547
  board,
537
548
  ...opened,
538
549
  own: ownLinks(settings),
550
+ labels: {
551
+ tickets: settings.tickets.labels,
552
+ codeHost: settings.codeHost.labels,
553
+ },
539
554
  };
540
555
  if (command === "supports") {
541
556
  if (!first || !GROUPS.includes(first))
@@ -610,7 +625,7 @@ export async function main(argv, deps) {
610
625
  case "refined": {
611
626
  // A body the build could not read gets no marker, whoever wrote it.
612
627
  const ticket = await d.tickets.read(issue);
613
- const missing = missingParts(ticket.body, ticket.labels);
628
+ const missing = missingParts(ticket.body, ticket.labels, d.labels.tickets);
614
629
  if (missing.length > 0) {
615
630
  for (const line of missing)
616
631
  console.error(line);
@@ -1,3 +1,4 @@
1
+ import { type Labels } from "../labels.mts";
1
2
  import { type Gh } from "../lib/gh.mts";
2
3
  import { type Settings } from "../config.mts";
3
4
  import { type Key, type Tickets } from "./types.mts";
@@ -25,4 +26,4 @@ export declare function openTickets(settings: Settings, target: {
25
26
  * The follow-ups ticket stays whole. `readAll` is the adapter's, since its
26
27
  * callers read comments, labels, and cards, never a refined ticket's
27
28
  * sections. */
28
- export declare function withTicketFields(inner: Tickets, mapping: FieldMapping, repository: string): Tickets;
29
+ export declare function withTicketFields(inner: Tickets, mapping: FieldMapping, repository: string, names?: Labels["tickets"]): Tickets;
@@ -1,6 +1,7 @@
1
1
  // Which adapter the settings' `tickets.type` picks, built for a command in a
2
2
  // session or CI. `github` is the only one; the settings refuse any other
3
3
  // value before this runs (`config.mts`).
4
+ import { TICKET_LABELS } from "../labels.mjs";
4
5
  import { gh } from "../lib/gh.mjs";
5
6
  import { fieldNamesOf } from "../config.mjs";
6
7
  import { githubKey, githubRef, githubTickets } from "./github.mjs";
@@ -42,7 +43,7 @@ export async function openTickets(settings, target, run = gh) {
42
43
  const mapping = settings.tickets.ticketFields;
43
44
  return {
44
45
  tickets: Object.values(mapping).some((v) => v !== null)
45
- ? withTicketFields(tickets, mapping, target.repository)
46
+ ? withTicketFields(tickets, mapping, target.repository, settings.tickets.labels)
46
47
  : tickets,
47
48
  };
48
49
  }
@@ -51,9 +52,9 @@ export async function openTickets(settings, target, run = gh) {
51
52
  * The follow-ups ticket stays whole. `readAll` is the adapter's, since its
52
53
  * callers read comments, labels, and cards, never a refined ticket's
53
54
  * sections. */
54
- export function withTicketFields(inner, mapping, repository) {
55
+ export function withTicketFields(inner, mapping, repository, names = TICKET_LABELS) {
55
56
  const fields = () => need(inner, "fields");
56
- const whole = (labels) => labels.includes("follow-up");
57
+ const whole = (labels) => labels.includes(names["follow-up"]);
57
58
  /** The description to write, once every named field is checked and
58
59
  * written. */
59
60
  const written = async (n, body) => {
@@ -86,7 +87,7 @@ export function withTicketFields(inner, mapping, repository) {
86
87
  const values = await fields().read(n);
87
88
  return {
88
89
  ...ticket,
89
- body: join(ticket.body, values, mapping, ticket.labels),
90
+ body: join(ticket.body, values, mapping, ticket.labels, names.spec),
90
91
  };
91
92
  },
92
93
  async writeBody(n, body) {
@@ -5,7 +5,14 @@ export type Built = {
5
5
  runner: readonly string[];
6
6
  /** Each spec tool, with the check \`specs.check\` defaults to. */
7
7
  specs: Readonly<Record<string, string>>;
8
+ /** Why a ticket system or code host refuses a label name, or null, for
9
+ * each that limits names beyond their not being empty. */
10
+ labelFaults: {
11
+ tickets: Readonly<Record<string, LabelFault>>;
12
+ codeHost: Readonly<Record<string, LabelFault>>;
13
+ };
8
14
  };
15
+ export type LabelFault = (name: string) => string | null;
9
16
  export declare const BUILT: Built;
10
17
  /** The words every command fails with for a name that is not built, such
11
18
  * as `tickets.type "jira" is not supported. "github" is the only ticket
@@ -11,6 +11,7 @@ export const BUILT = {
11
11
  specs: {
12
12
  openspec: "npx --no-install openspec validate --all --strict --no-interactive",
13
13
  },
14
+ labelFaults: { tickets: {}, codeHost: {} },
14
15
  };
15
16
  /** The words every command fails with for a name that is not built, such
16
17
  * as `tickets.type "jira" is not supported. "github" is the only ticket
package/dist/tools.d.mts CHANGED
@@ -6,10 +6,13 @@ import { type Runner } from "./runner/index.mts";
6
6
  import type { Chosen, SecretStep, SetupContext, SetupStep, ToolSetup } from "./setup.mts";
7
7
  import { type Tickets } from "./tickets/index.mts";
8
8
  import { type SpecTools } from "./specs/index.mts";
9
- import { type Built } from "./tool-names.mts";
9
+ import { type Built, type LabelFault } from "./tool-names.mts";
10
10
  export type Tool = {
11
11
  label: string;
12
12
  setup: ToolSetup;
13
+ /** Why it refuses a label name, where it limits names beyond their not
14
+ * being empty. */
15
+ labelFault?: LabelFault;
13
16
  };
14
17
  export type Registry = {
15
18
  codeHost: Record<string, Tool & {
package/dist/tools.mjs CHANGED
@@ -53,6 +53,7 @@ export const TOOLS = {
53
53
  },
54
54
  specs: specTools(),
55
55
  };
56
+ const faultsOf = (tools) => Object.fromEntries(Object.entries(tools).flatMap(([name, t]) => t.labelFault ? [[name, t.labelFault]] : []));
56
57
  /** The names and keys the settings accept, as `config.mts` checks them. */
57
58
  export function builtOf(r) {
58
59
  return {
@@ -60,6 +61,10 @@ export function builtOf(r) {
60
61
  tickets: Object.fromEntries(Object.entries(r.tickets).map(([name, t]) => [name, t.keys])),
61
62
  runner: Object.keys(r.runner),
62
63
  specs: Object.fromEntries(Object.entries(r.specs).map(([name, t]) => [name, t.defaultCheck])),
64
+ labelFaults: {
65
+ tickets: faultsOf(r.tickets),
66
+ codeHost: faultsOf(r.codeHost),
67
+ },
63
68
  };
64
69
  }
65
70
  /** The tools in use, in the order setup asks for them. */
package/docs/cli.md CHANGED
@@ -141,7 +141,7 @@ N is the ticket's key as your ticket system writes it: `12` on GitHub.
141
141
 
142
142
  | Command | What it does |
143
143
  | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
144
- | `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 |
145
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 |
146
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
147
  | `factory ticket list` | Lists the open tickets: key, title, and labels, separated by tabs |
@@ -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
 
@@ -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 |
@@ -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,7 +81,7 @@ 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` |
@@ -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/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.12",
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": {