@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.
- package/dist/board.d.mts +3 -1
- package/dist/board.mjs +12 -6
- package/dist/commands.mjs +1 -1
- 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/refined-check.d.mts +1 -1
- package/dist/lib/refined-check.mjs +3 -5
- package/dist/lib/work-status.d.mts +6 -4
- package/dist/lib/work-status.mjs +17 -7
- package/dist/merge-policy.d.mts +9 -7
- package/dist/merge-policy.mjs +13 -11
- package/dist/poller.d.mts +3 -1
- package/dist/poller.mjs +10 -4
- package/dist/pr.d.mts +4 -0
- package/dist/pr.mjs +6 -3
- package/dist/remove.mjs +16 -9
- package/dist/review-verdict.d.mts +6 -1
- package/dist/review-verdict.mjs +15 -9
- package/dist/status.d.mts +2 -0
- package/dist/status.mjs +6 -3
- package/dist/sync.d.mts +4 -0
- package/dist/sync.mjs +17 -1
- package/dist/ticket-fields.d.mts +4 -2
- package/dist/ticket-fields.mjs +10 -3
- package/dist/ticket.d.mts +2 -1
- package/dist/ticket.mjs +30 -15
- package/dist/tickets/index.d.mts +2 -1
- package/dist/tickets/index.mjs +5 -4
- 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 +1 -1
- package/docs/configuration.md +178 -8
- package/docs/developing.md +1 -1
- package/docs/github/by-hand.md +2 -2
- package/docs/github/reference.md +21 -21
- package/docs/workflow.md +8 -6
- package/package.json +1 -1
- package/rules.md +7 -2
- package/settings.schema.json +45 -0
- package/skills/factory-address-review/SKILL.md +3 -3
- package/skills/factory-build/SKILL.md +3 -3
- package/skills/factory-resolve-conflicts/SKILL.md +1 -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/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
|
|
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: [
|
|
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
|
|
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({
|
|
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);
|
package/dist/tickets/index.d.mts
CHANGED
|
@@ -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;
|
package/dist/tickets/index.mjs
CHANGED
|
@@ -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) {
|
package/dist/tool-names.d.mts
CHANGED
|
@@ -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
|
package/dist/tool-names.mjs
CHANGED
|
@@ -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 |
|
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
|
|
|
@@ -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 |
|
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,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
|
|
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
|
|
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/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