@davidbyoung/software-factory 0.1.11 → 0.1.12

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 (56) hide show
  1. package/agents/factory-e2e-reviewer.md +1 -1
  2. package/agents/factory-test-reviewer.md +1 -1
  3. package/agents/factory-ui-reviewer.md +2 -2
  4. package/dist/board.d.mts +7 -7
  5. package/dist/board.mjs +50 -33
  6. package/dist/build.d.mts +4 -0
  7. package/dist/build.mjs +9 -4
  8. package/dist/cli.mjs +8 -1
  9. package/dist/code-host/github.mjs +9 -4
  10. package/dist/code-host/types.d.mts +4 -2
  11. package/dist/commands.d.mts +1 -1
  12. package/dist/commands.mjs +15 -6
  13. package/dist/lib/clock.d.mts +3 -1
  14. package/dist/lib/clock.mjs +12 -6
  15. package/dist/lib/pull-tickets.d.mts +15 -0
  16. package/dist/lib/pull-tickets.mjs +12 -0
  17. package/dist/lib/usage.d.mts +3 -1
  18. package/dist/lib/usage.mjs +4 -2
  19. package/dist/lib/work-status.d.mts +23 -19
  20. package/dist/lib/work-status.mjs +14 -27
  21. package/dist/poller.d.mts +3 -3
  22. package/dist/poller.mjs +18 -14
  23. package/dist/pr.d.mts +18 -0
  24. package/dist/pr.mjs +54 -7
  25. package/dist/review-tickets.d.mts +12 -0
  26. package/dist/review-tickets.mjs +59 -0
  27. package/dist/reviewers.d.mts +7 -4
  28. package/dist/reviewers.mjs +19 -12
  29. package/dist/runner/github-actions.mjs +6 -7
  30. package/dist/runner/types.d.mts +7 -6
  31. package/dist/status.d.mts +17 -7
  32. package/dist/status.mjs +35 -23
  33. package/dist/sync.d.mts +4 -0
  34. package/dist/sync.mjs +14 -1
  35. package/dist/ticket.d.mts +13 -7
  36. package/dist/ticket.mjs +94 -60
  37. package/dist/tickets/github.d.mts +10 -2
  38. package/dist/tickets/github.mjs +74 -20
  39. package/dist/tickets/index.d.mts +7 -1
  40. package/dist/tickets/index.mjs +15 -1
  41. package/dist/tickets/types.d.mts +59 -30
  42. package/dist/tickets/types.mjs +13 -3
  43. package/docs/cli.md +11 -7
  44. package/docs/configuration.md +1 -1
  45. package/docs/developing.md +16 -8
  46. package/docs/github/reference.md +1 -1
  47. package/docs/plugins.md +6 -6
  48. package/package.json +1 -1
  49. package/review.md +11 -11
  50. package/rules.md +18 -14
  51. package/skills/factory-address-review/SKILL.md +4 -3
  52. package/skills/factory-build/SKILL.md +25 -19
  53. package/skills/factory-refine/SKILL.md +1 -1
  54. package/skills/factory-resolve-conflicts/SKILL.md +4 -3
  55. package/workflows/factory-build.yml +6 -5
  56. package/workflows/factory-claude-review.yml +38 -1
@@ -3,7 +3,7 @@
3
3
  // value before this runs (`config.mts`).
4
4
  import { gh } from "../lib/gh.mjs";
5
5
  import { fieldNamesOf } from "../config.mjs";
6
- import { githubTickets } from "./github.mjs";
6
+ import { githubKey, githubRef, githubTickets } from "./github.mjs";
7
7
  import { ghTransport } from "./transport.mjs";
8
8
  import { need } from "./types.mjs";
9
9
  import { join, split } from "../ticket-fields.mjs";
@@ -11,6 +11,20 @@ import { BUILT, unsupported } from "../tool-names.mjs";
11
11
  export * from "./types.mjs";
12
12
  /** The ticket system's message for a type that is not built. */
13
13
  export const unsupportedType = (type) => unsupported("tickets.type", type, "ticket system", Object.keys(BUILT.tickets));
14
+ /** How a ticket system of this type writes a ticket, without opening its
15
+ * adapter, for text written ahead of time, such as a workflow's run name. */
16
+ export function refOf(type) {
17
+ if (type !== "github")
18
+ throw new Error(unsupportedType(type));
19
+ return githubRef;
20
+ }
21
+ /** How a ticket system of this type reads a typed key, as `Tickets.key`
22
+ * does, without opening its adapter. */
23
+ export function keyOf(type) {
24
+ if (type !== "github")
25
+ throw new Error(unsupportedType(type));
26
+ return githubKey;
27
+ }
14
28
  /** The settings' adapter, reaching its system through the GitHub CLI. The
15
29
  * repository and board are the caller's, since a workflow can name its own. */
16
30
  export async function openTickets(settings, target, run = gh) {
@@ -1,5 +1,9 @@
1
+ /** A ticket's identity: the key its ticket system gives it, as text, such
2
+ * as `12` on GitHub or `PROJ-12` in Jira. */
3
+ export type Key = string;
1
4
  export type TicketComment = {
2
- id: number;
5
+ /** Opaque: never compared as a number. */
6
+ id: string;
3
7
  author: string;
4
8
  createdAt: string;
5
9
  body: string;
@@ -8,7 +12,7 @@ export type TicketComment = {
8
12
  export type BoardItem = {
9
13
  /** The system's own ID for the card, for the adapter's writes. */
10
14
  itemId: string;
11
- number: number;
15
+ key: Key;
12
16
  status: string | null;
13
17
  /** When Status last changed. */
14
18
  updatedAt: string | null;
@@ -18,19 +22,20 @@ export type BoardItem = {
18
22
  cost?: number | null;
19
23
  };
20
24
  export type Ticket = {
21
- number: number;
25
+ key: Key;
22
26
  title: string;
23
27
  state: "open" | "closed";
24
28
  closedAt: string | null;
25
29
  labels: string[];
26
30
  body: string;
31
+ /** Oldest first, in the order the ticket system keeps them. */
27
32
  comments: TicketComment[];
28
33
  /** The ticket's card, when "Read everything at once" was asked for the
29
34
  * board and the adapter has one; null when it is not on the board. */
30
35
  card?: BoardItem | null;
31
36
  };
32
37
  export type TicketSummary = {
33
- number: number;
38
+ key: Key;
34
39
  title: string;
35
40
  labels: string[];
36
41
  };
@@ -50,8 +55,8 @@ export type Board = {
50
55
  /** The board's own title, for the report `factory board check` prints. */
51
56
  title?: string;
52
57
  fields: BoardField[];
53
- /** This repository's tickets on the board, by number. */
54
- items: Map<number, BoardItem>;
58
+ /** This repository's tickets on the board, by key. */
59
+ items: Map<Key, BoardItem>;
55
60
  };
56
61
  /** One write to a card's field. */
57
62
  export type Write = {
@@ -71,7 +76,7 @@ export type BoardOps = {
71
76
  /** Every card and the board's fields. */
72
77
  read(): Promise<Board>;
73
78
  /** Puts the ticket on the board, and returns its card's ID. */
74
- add(ticket: number): Promise<string>;
79
+ add(ticket: Key): Promise<string>;
75
80
  /** Writes the fields of a card already on the board. */
76
81
  set(itemId: string, writes: Write[]): Promise<void>;
77
82
  /** The open boards the repository's owner has. */
@@ -102,26 +107,28 @@ export type NewField = {
102
107
  type: "select";
103
108
  options: string[];
104
109
  };
110
+ /** A ticket another waits on. Its key can name a ticket `key` would refuse,
111
+ * such as one in another repository. */
105
112
  export type Blocker = {
106
- number: number;
113
+ key: Key;
107
114
  state: "open" | "closed";
108
115
  };
109
116
  export type BlockerOps = {
110
117
  /** What a ticket waits on, open or closed. */
111
- list(ticket: number): Promise<Blocker[]>;
118
+ list(ticket: Key): Promise<Blocker[]>;
112
119
  /** Records that `ticket` waits on `by`. */
113
- add(ticket: number, by: number): Promise<void>;
114
- remove(ticket: number, by: number): Promise<void>;
120
+ add(ticket: Key, by: Key): Promise<void>;
121
+ remove(ticket: Key, by: Key): Promise<void>;
115
122
  };
116
123
  export type LabelHistoryOps = {
117
124
  /** Whether the label was ever removed from the ticket. */
118
- wasRemoved(ticket: number, label: string): Promise<boolean>;
125
+ wasRemoved(ticket: Key, label: string): Promise<boolean>;
119
126
  };
120
127
  export type AttachmentOps = {
121
128
  /** Comments with the images attached; returns the comment's ID. */
122
- comment(ticket: number, body: string, files: string[]): Promise<number>;
129
+ comment(ticket: Key, body: string, files: string[]): Promise<string>;
123
130
  /** Replaces the body with the images attached. */
124
- writeBody(ticket: number, body: string, files: string[]): Promise<void>;
131
+ writeBody(ticket: Key, body: string, files: string[]): Promise<void>;
125
132
  };
126
133
  /** A field tickets can have, set on the ticket itself. */
127
134
  export type TicketField = {
@@ -137,15 +144,15 @@ export type FieldOps = {
137
144
  /** The fields tickets can have, in the system's order. */
138
145
  list(): Promise<TicketField[]>;
139
146
  /** Whether the ticket can hold the field, and how many characters. */
140
- holds(ticket: number, field: string): Promise<{
147
+ holds(ticket: Key, field: string): Promise<{
141
148
  max: number | null;
142
149
  } | {
143
150
  reason: string;
144
151
  }>;
145
152
  /** The ticket's text field values, by field name. */
146
- read(ticket: number): Promise<Record<string, string>>;
153
+ read(ticket: Key): Promise<Record<string, string>>;
147
154
  /** Sets each field by name; null clears it. */
148
- write(ticket: number, values: Record<string, string | null>): Promise<void>;
155
+ write(ticket: Key, values: Record<string, string | null>): Promise<void>;
149
156
  };
150
157
  export declare const GROUPS: readonly ["board", "blockers", "label-history", "attachments", "fields"];
151
158
  export type Group = (typeof GROUPS)[number];
@@ -155,8 +162,14 @@ export type NewTicket = {
155
162
  labels: string[];
156
163
  };
157
164
  export type Tickets = {
165
+ /** The key a person typed, or KeyError saying what a key looks like in
166
+ * this system. It checks only typed input: keys the adapter returned, such
167
+ * as a blocker's, are used as they are. */
168
+ key(typed: string): Key;
169
+ /** How the ticket is written in prose and output, such as `#12`. */
170
+ ref(ticket: Key): string;
158
171
  /** The ticket, or NotFoundError when there is none. */
159
- read(ticket: number): Promise<Ticket>;
172
+ read(ticket: Key): Promise<Ticket>;
160
173
  /** Every open ticket, however many there are. */
161
174
  listOpen(): Promise<TicketSummary[]>;
162
175
  /** Every open ticket and the 30 closed ones most recently updated, as
@@ -166,32 +179,48 @@ export type Tickets = {
166
179
  readAll?(options?: {
167
180
  board?: boolean;
168
181
  }): Promise<Ticket[]>;
169
- writeBody(ticket: number, body: string): Promise<void>;
170
- writeTitle(ticket: number, title: string): Promise<void>;
182
+ writeBody(ticket: Key, body: string): Promise<void>;
183
+ writeTitle(ticket: Key, title: string): Promise<void>;
171
184
  /** Returns the comment's ID. The body is posted as given. */
172
- comment(ticket: number, body: string): Promise<number>;
185
+ comment(ticket: Key, body: string): Promise<string>;
173
186
  /** NotFoundError when the comment is gone. */
174
- editComment(id: number, body: string): Promise<void>;
187
+ editComment(id: string, body: string): Promise<void>;
175
188
  /** NotFoundError when the comment is gone. */
176
- deleteComment(id: number): Promise<void>;
177
- /** Returns the new ticket's number. */
178
- open(ticket: NewTicket): Promise<number>;
179
- addLabel(ticket: number, label: string): Promise<void>;
180
- removeLabel(ticket: number, label: string): Promise<void>;
189
+ deleteComment(id: string): Promise<void>;
190
+ /** Returns the new ticket's key. */
191
+ open(ticket: NewTicket): Promise<Key>;
192
+ addLabel(ticket: Key, label: string): Promise<void>;
193
+ removeLabel(ticket: Key, label: string): Promise<void>;
181
194
  /** Whether a comment by `author` may decide on a ticket: an answer to a
182
195
  * question, taken as an instruction. Rejects when the system cannot
183
196
  * say. */
184
197
  mayDecide(author: string): Promise<boolean>;
185
- /** What makes a merged pull request close the ticket. */
186
- linkText(ticket: number): string;
198
+ /** The line in a pull request's body that closes the ticket when it
199
+ * merges, or that says it builds part of it. */
200
+ linkText(ticket: Key, kind: LinkKind): string;
201
+ /** The tickets a pull request's body closes and builds part of, each in
202
+ * the order the body links them, once. */
203
+ linksIn(body: string): Links;
187
204
  /** The address of the ticket's page. */
188
- address(ticket: number): string;
205
+ address(ticket: Key): string;
189
206
  board?: BoardOps;
190
207
  blockers?: BlockerOps;
191
208
  labelHistory?: LabelHistoryOps;
192
209
  attachments?: AttachmentOps;
193
210
  fields?: FieldOps;
194
211
  };
212
+ export type LinkKind = "closes" | "part";
213
+ export type Links = {
214
+ closes: Key[];
215
+ partOf: Key[];
216
+ };
217
+ /** Typed text that is not a key this ticket system uses. */
218
+ export declare class KeyError extends Error {
219
+ constructor(message: string);
220
+ }
221
+ /** The order tickets are listed in: by key, letters first, then the number
222
+ * as a number, so PROJ-9 comes before PROJ-12. */
223
+ export declare const compareKeys: (a: Key, b: Key) => number;
195
224
  /** A ticket or comment that does not exist, told apart from any other
196
225
  * failure. Every adapter throws this one. */
197
226
  export declare class NotFoundError extends Error {
@@ -10,6 +10,16 @@ export const GROUPS = [
10
10
  "attachments",
11
11
  "fields",
12
12
  ];
13
+ /** Typed text that is not a key this ticket system uses. */
14
+ export class KeyError extends Error {
15
+ constructor(message) {
16
+ super(message);
17
+ this.name = "KeyError";
18
+ }
19
+ }
20
+ /** The order tickets are listed in: by key, letters first, then the number
21
+ * as a number, so PROJ-9 comes before PROJ-12. */
22
+ export const compareKeys = (a, b) => a.localeCompare(b, "en", { numeric: true });
13
23
  /** A ticket or comment that does not exist, told apart from any other
14
24
  * failure. Every adapter throws this one. */
15
25
  export class NotFoundError extends Error {
@@ -62,17 +72,17 @@ export async function readAll(tickets, options = {}) {
62
72
  if (tickets.readAll)
63
73
  return tickets.readAll(options);
64
74
  const open = await tickets.listOpen();
65
- const read = await Promise.all(open.map((t) => tickets.read(t.number)));
75
+ const read = await Promise.all(open.map((t) => tickets.read(t.key)));
66
76
  if (!options.board || !tickets.board)
67
77
  return read;
68
78
  const board = await tickets.board.read();
69
- return read.map((t) => ({ ...t, card: board.items.get(t.number) ?? null }));
79
+ return read.map((t) => ({ ...t, card: board.items.get(t.key) ?? null }));
70
80
  }
71
81
  /** The cards `readAll` carried, as a Board, for the code that reads one. */
72
82
  export function boardOf(tickets) {
73
83
  const items = new Map();
74
84
  for (const t of tickets)
75
85
  if (t.card)
76
- items.set(t.number, t.card);
86
+ items.set(t.key, t.card);
77
87
  return { projectId: "", fields: [], items };
78
88
  }
package/docs/cli.md CHANGED
@@ -137,21 +137,23 @@ prints what the ticket system returned as one JSON value. `edit`,
137
137
  `comment`, and `open` refuse a body with a bare tag-like `<word>` the
138
138
  ticket system would swallow, name it, and post nothing.
139
139
 
140
+ N is the ticket's key as your ticket system writes it: `12` on GitHub.
141
+
140
142
  | Command | What it does |
141
143
  | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
142
144
  | `factory ticket view N` | Prints ticket N: its title, state, labels, body, and comments with their IDs and authors |
143
145
  | `factory ticket answers N` | Prints each comment on N that counts as an answer: its author can write to the repository, and it is not the factory's own. Says so when there is none |
144
- | `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), or `body`, and nothing else |
145
- | `factory ticket list` | Lists the open tickets: number, title, and labels, separated by tabs |
146
+ | `factory ticket view N --field NAME` | Prints one of `title`, `state`, `labels` (one per line), `body`, or `ref`, how the ticket system writes N in prose, such as `#12`, and nothing else |
147
+ | `factory ticket list` | Lists the open tickets: key, title, and labels, separated by tabs |
146
148
  | `factory ticket list --label LABEL` | Only those with the label. `--title "TITLE"` keeps those whose title is exactly that |
147
149
  | `factory ticket edit N [--title TITLE] [--body-file FILE]` | Replaces N's title, its body, or both. `--attach FILE` adds an image to a body |
148
150
  | `factory ticket comment N --body-file FILE` | Comments on N and prints the comment's ID. `--attach FILE` adds an image |
149
- | `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its number. `--label LABEL` adds a label |
151
+ | `factory ticket open --title TITLE --body-file FILE` | Opens a ticket and prints its key. `--label LABEL` adds a label |
150
152
  | `factory ticket label N --add LABEL` | Adds a label to N. `--remove LABEL` takes one off |
151
153
  | `factory ticket label N --was-removed LABEL` | Prints `yes` if the label was ever removed from N, otherwise `no` |
152
- | `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12" |
154
+ | `factory ticket link N` | Prints the text that makes a merged pull request close N, such as "Closes #12". `--part` prints the text that says it builds part of N, such as "Part of #4" |
153
155
  | `factory ticket branch N` | Prints the branch a build of N pushes, from [`code-host.branch-name`](configuration.md#code-host), such as `12` or `feature/octocat/12`. Exits 1 when N does not exist, or the pattern has `{user}` and `gh` is not signed in |
154
- | `factory ticket blockers N` | One line per ticket N waits on: its number and whether it is open |
156
+ | `factory ticket blockers N` | One line per ticket N waits on: the ticket, as its system writes it, and whether it is open |
155
157
  | `factory ticket block N --by M` | Records that N waits on M |
156
158
  | `factory ticket unblock N --by M` | Removes that record |
157
159
  | `factory ticket supports GROUP` | Prints `yes` or `no` for `board`, `blockers`, `label-history`, or `attachments` |
@@ -163,7 +165,7 @@ ticket system would swallow, name it, and post nothing.
163
165
  | `factory ticket waiting N` | Marks N as waiting on your reply to a round of questions |
164
166
  | `factory ticket refined N` | Marks N as refined, unless its body lacks what a build reads. `--check` makes that check alone and posts nothing |
165
167
  | `factory ticket ready N` | Moves N to Ready. Only when you ask a session to |
166
- | `factory ticket cost N` | Notes what this session spent on N since it started |
168
+ | `factory ticket cost N` | Notes what this session spent on ticket N since it started |
167
169
  | `factory follow-up FILE "what is wrong"` | Adds a line about that file to the follow-ups ticket, opening the ticket if none is open |
168
170
 
169
171
  `factory ticket refined N` posts nothing and exits 1 when N's body lacks a
@@ -183,7 +185,8 @@ ticket system.
183
185
  | `factory pr threads N` | The unresolved review threads, each with its comments. `--all` lists the resolved ones too |
184
186
  | `factory pr reply N COMMENT --body-file FILE` | Replies on a thread |
185
187
  | `factory pr resolve N COMMENT` | Resolves a thread |
186
- | `factory pr closes N` | The tickets N closes |
188
+ | `factory pr closes N` | The tickets N closes, by key |
189
+ | `factory pr cost N` | Notes what this session spent on pull request N since it started |
187
190
  | `factory pr for-branch BRANCH` | The newest pull request from BRANCH, open or not: `#N open`, `#N merged`, or `#N closed`, or `none` when there has been none |
188
191
  | `factory pr wait-checks N` | Waits for every CI run on the pushed commit. Prints `success`, `failure:` with the failed checks, or `no checks` |
189
192
  | `factory pr ready N` | Marks a draft ready for review. When `commit.gpgsign` is `true`, refuses while the code host shows a commit as not verified |
@@ -263,6 +266,7 @@ the commit hook blocks a session's git command with it.
263
266
  | `factory review verdict` | The review-verdict workflow | Posts the "Review verdict" status for a commit | Built |
264
267
  | `factory review cost` | The review workflow | Adds what the CI review cost to its summary | Built |
265
268
  | `factory review tools` | The review workflow | Prints the tools the CI review may use, from [`pr-review.commands`](configuration.md#pr-review) | Built |
269
+ | `factory review tickets N` | The review workflow | Each ticket pull request N closes or builds part of, headed by its name and title, with its body | Built |
266
270
  | `factory poller` | Your server | Starts a build for each Ready ticket. See [Builds](builds.md) | Built |
267
271
  | `factory poller --once` | The scheduled poller's workflow | One pass of the poller, with the board and Ready column from your settings | Built |
268
272
  | `factory guard` | A hook, before each command | Runs both guards below on one Bash call | Built |
@@ -430,7 +430,7 @@ it out:
430
430
 
431
431
  | Placeholder | What it becomes | For ticket 12 |
432
432
  | ----------- | ------------------------------------ | ------------- |
433
- | `{ticket}` | The ticket's number, without `#` | `12` |
433
+ | `{ticket}` | The ticket's key, without `#` | `12` |
434
434
  | `{user}` | The GitHub account the build runs as | `octocat` |
435
435
 
436
436
  In a session, `{user}` is the account the GitHub CLI, `gh`, is signed in
@@ -226,19 +226,22 @@ the work to that type's adapter.** An adapter is one module in
226
226
 
227
227
  | Operation | In `Tickets` | What it returns or does |
228
228
  | ----------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
229
- | Read a ticket | `read` | Its number, title, state (`open` or `closed`), when it closed, labels, body, and comments, each with its ID, author, time, and body |
230
- | List open tickets | `listOpen` | Number, title, and labels, for every open ticket however many there are |
229
+ | Parse a key | `key` | The key a person typed, or `KeyError` saying what a key looks like in this system. GitHub's are numbers, such as `12` |
230
+ | Write a ticket | `ref` | How the ticket is written in prose and output, such as `#12` |
231
+ | Read a ticket | `read` | Its key, title, state (`open` or `closed`), when it closed, labels, body, and comments, each with its ID, author, time, and body |
232
+ | List open tickets | `listOpen` | Key, title, and labels, for every open ticket however many there are |
231
233
  | Read everything at once | `readAll` | Every open ticket and the 30 closed ones most recently updated, as `read` returns each; with the board group, each carries its card. Optional: see below |
232
234
  | Write a ticket's body | `writeBody` | |
233
235
  | Comment | `comment` | Returns the comment's ID. Hidden markers pass through unchanged |
234
236
  | Edit a comment | `editComment` | By its ID |
235
237
  | Delete a comment | `deleteComment` | By its ID |
236
238
  | Not found | `NotFoundError` | Reading a ticket that does not exist, or editing or deleting a comment that is gone, throws this, so a caller can tell it from any other failure |
237
- | Open a ticket | `open` | With a title, a body, and labels. Returns its number |
239
+ | Open a ticket | `open` | With a title, a body, and labels. Returns its key |
238
240
  | Add or remove a label | `addLabel`, `removeLabel` | |
239
241
  | Who may decide | `mayDecide` | Whether a comment's author may decide on a ticket, so `factory ticket answers` takes their comment as an answer. GitHub's asks whether they can write to the repository. Rejects when it cannot say |
240
- | Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12" |
241
- | The address of a ticket | `address` | Its page, which the views link a ticket's number to |
242
+ | Link text | `linkText` | What makes a merged pull request close the ticket, such as "Closes #12", and what says it builds part of one, "Part of #4" |
243
+ | Links in a body | `linksIn` | The tickets a pull request's body closes, and those it builds part of, each in the body's order |
244
+ | The address of a ticket | `address` | Its page, which the views link a ticket to |
242
245
 
243
246
  "Read everything at once" has a default, `readAll` in
244
247
  `src/tickets/types.mts`, built from `listOpen` and `read`, so a new adapter
@@ -281,13 +284,18 @@ package.
281
284
  What stays above the interface: working out a ticket's state from its
282
285
  marker comments, costs, and the formatting of every view, in
283
286
  `src/lib/work-status.mts` and the commands. They are the factory's own
284
- logic, the same for any system.
287
+ logic, the same for any system. Nothing there writes `#` or reads a link
288
+ from a pull request's body itself: it asks the adapter. The code host's
289
+ own links, such as GitHub's closing references, count only when the
290
+ tickets are the code host's own (`src/lib/pull-tickets.mts`).
285
291
 
286
292
  A second adapter exists from the start: an in-memory one,
287
293
  `tests/memory-tickets.ts`, that every command's tests run against. It
288
294
  keeps the interface honest, since anything the tests need has to go
289
- through it. The GitHub adapter has its own tests against recorded
290
- responses.
295
+ through it. Its keys are numbers, as GitHub's are; with `strict` they are
296
+ keys like `PROJ-12`, and comment IDs and authors are opaque text, as Jira
297
+ and Linear give them, so a command that treats either as a number fails
298
+ there. The GitHub adapter has its own tests against recorded responses.
291
299
 
292
300
  What an adapter does not cover: pull requests, reviews, and checks, which
293
301
  are the code host's, and where an unattended build runs, which is the
@@ -87,7 +87,7 @@ anything to do, and stops there when there is not.
87
87
  | `factory-poller.yml` | Every `builds.poll-minutes` minutes, or by hand | Runs one pass of the poller, starting a build for each Ready ticket. Written once `builds.trigger` is `github-action` |
88
88
 
89
89
  **Starting a build by hand.** The Actions tab, "Factory build", "Run
90
- workflow", and the ticket's number. The board's "Runs in" field then shows
90
+ workflow", and the ticket's key, such as `12`. The board's "Runs in" field then shows
91
91
  "Actions", and "Session" the run's link. The run's log also shows each
92
92
  tool call the session was denied, with the reason.
93
93
 
package/docs/plugins.md CHANGED
@@ -74,12 +74,12 @@ plugins:
74
74
  skill: acme-refine
75
75
  ```
76
76
 
77
- | Step | What happens |
78
- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
- | **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
80
- | **Handed** | The ticket's number. From `factory-build`, for a round of questions you approved while it waited on your answers, also the words "approved while waiting: fold the owner's replies into the body, post no marker". They tell the refiner to write your replies into the ticket's body and to post no [marker](glossary.md), the hidden comment line the board reads |
81
- | **Returns** | A ticket a build can start from: everything in the list below |
82
- | **Then** | The ticket waits for your approval, and the build reads what the refiner left |
77
+ | Step | What happens |
78
+ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
+ | **Called** | When you run `/factory-refine N` in a session: `factory-refine` hands over to it before doing anything. By `factory-build`, on a ticket that has no criteria yet, or one you approved while its questions waited |
80
+ | **Handed** | The ticket's key. From `factory-build`, for a round of questions you approved while it waited on your answers, also the words "approved while waiting: fold the owner's replies into the body, post no marker". They tell the refiner to write your replies into the ticket's body and to post no [marker](glossary.md), the hidden comment line the board reads |
81
+ | **Returns** | A ticket a build can start from: everything in the list below |
82
+ | **Then** | The ticket waits for your approval, and the build reads what the refiner left |
83
83
 
84
84
  **What a refiner must deliver.** The board and the build read these, so a
85
85
  refiner that leaves one out leaves a ticket that cannot be built.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@davidbyoung/software-factory",
3
- "version": "0.1.11",
3
+ "version": "0.1.12",
4
4
  "description": "Refines, builds, and reviews tickets with Claude Code sessions, from a board to a merged pull request.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/review.md CHANGED
@@ -56,21 +56,21 @@ defend.
56
56
  the facts; if you still disagree, say so once in the summary, with your
57
57
  evidence, rather than opening a new thread.
58
58
 
59
- 4. Read what the pull request was asked to do. Its body, and the issues it
60
- closes:
59
+ 4. Read what the pull request was asked to do: its body, and the tickets it
60
+ builds, which the workflow has read for you into the file TICKETS names.
61
+ Read that file with the Read tool. Each ticket there starts with a `## `
62
+ line naming it and its title. When the file says the tickets could not be
63
+ read, say so in the summary and go by the body.
61
64
 
62
65
  ```bash
63
- gh pr view PR_NUMBER --json body,closingIssuesReferences
64
- gh api graphql -F n=ISSUE_NUMBER -f query='query($n: Int!) { repository(owner: "OWNER", name: "NAME") { issue(number: $n) { body } } }' --jq .data.repository.issue.body
66
+ gh pr view PR_NUMBER --json body
65
67
  ```
66
68
 
67
- OWNER and NAME are the two halves of REPO.
68
-
69
- The issue's "Spec" and "Acceptance criteria" sections are what the
70
- change must do, and its "Decisions" are settled. An issue with neither
69
+ The ticket's "Spec" and "Acceptance criteria" sections are what the
70
+ change must do, and its "Decisions" are settled. A ticket with neither
71
71
  is held only to what it plainly asks for: a fix it suggests is not a
72
- criterion. The follow-ups issue, closed or only linked, is held to the lines the
73
- body says this pull request built. A pull request that closes no issue,
72
+ criterion. The follow-ups ticket is held to the lines the
73
+ body says this pull request built. A pull request that builds no ticket,
74
74
  such as a source audit, has only its body to go by.
75
75
 
76
76
  ## What to look for
@@ -79,7 +79,7 @@ defend.
79
79
  that is silently dropped.
80
80
  - **What it was asked to do.** A Spec line or criterion from step 4 that
81
81
  the whole pull request, `git diff origin/DEFAULT...HEAD`, does not meet, or
82
- meets only in part, is a finding, since the merge closes the issue as
82
+ meets only in part, is a finding, since the merge closes the ticket as
83
83
  done: High when a user would see the gap, Medium otherwise. Behavior
84
84
  no line asked for is Medium, unless the body or the owner's comments on
85
85
  the pull request explain it. Quote the line either way.
package/rules.md CHANGED
@@ -109,8 +109,9 @@ discovering it at push time.
109
109
  `npx --no-install factory pr state N --wait`, and does not run it, since
110
110
  nothing can wake it once it stops.
111
111
  - **A pull request that resolves an issue closes it.** When asked to open
112
- one, start the body with `Closes #N` for each issue the branch resolves,
113
- so the merge closes them. Check that GitHub registered the link.
112
+ one, start the body with the line `npx --no-install factory ticket link N`
113
+ prints for each issue the branch resolves, so the merge closes them. Check that `npx --no-install factory pr closes PR`
114
+ prints each one.
114
115
  - **After pushing, check for review automatically.** The `Claude review`
115
116
  workflow reviews every push to a PR. If an open PR exists for the branch,
116
117
  wait for the review of that push, then work it with the `factory-address-review` skill
@@ -167,7 +168,7 @@ always the owner's.
167
168
 
168
169
  ## Spec track
169
170
 
170
- The GitHub issue is the spec: `factory-refine` writes it, the owner
171
+ The ticket is the spec: `factory-refine` writes it, the owner
171
172
  approves it by moving its card to Ready or telling a session to build
172
173
  it, and `factory-build` builds it. A change that adds or alters behavior
173
174
  a user can see carries the `spec` label, which `factory-refine` adds,
@@ -217,8 +218,8 @@ npx --no-install factory ticket blockers N
217
218
  npx --no-install factory ticket unblock N --by M
218
219
  ```
219
220
 
220
- `blockers` prints one line per ticket N waits on, its number and whether
221
- it is open. A ticket system without blockers says so: check with
221
+ `blockers` prints one line per ticket N waits on, as the ticket system
222
+ writes it, and whether it is open. A ticket system without blockers says so: check with
222
223
  `npx --no-install factory ticket supports blockers`.
223
224
 
224
225
  ## Follow-ups
@@ -235,18 +236,20 @@ labeled `follow-up`, holding a checklist. A line leads with the file or
235
236
  page it is about:
236
237
 
237
238
  ```
238
- - [ ] <file or page>: <what is wrong, as a user or a maintainer sees it>. Found by <who> while building #N. <The rule it breaks, by its section in the guide that states it (an area's guide under "Rules by area" in CLAUDE.md, CLAUDE.md, or this file), or "Needs a decision: <the question>".>
239
+ - [ ] <file or page>: <what is wrong, as a user or a maintainer sees it>. Found by <who> while building <ticket>. <The rule it breaks, by its section in the guide that states it (an area's guide under "Rules by area" in CLAUDE.md, CLAUDE.md, or this file), or "Needs a decision: <the question>".>
239
240
  ```
240
241
 
241
242
  It is added with the file and the rest of the line as two arguments, and
242
243
  the script opens the issue when none is open:
243
244
 
244
245
  ```bash
245
- npx --no-install factory follow-up FILE "What is wrong. Found by WHO while building #N. The rule it breaks."
246
+ npx --no-install factory follow-up FILE "What is wrong. Found by WHO while building TICKET. The rule it breaks."
246
247
  ```
247
248
 
248
- A reviewer that does not know the issue or pull request number writes
249
- `#N` as it stands, and whoever appends the line fills it in.
249
+ TICKET is the ticket as its system writes it, which
250
+ `npx --no-install factory ticket view N --field ref` prints, such as `#12`.
251
+ A reviewer that does not know the ticket writes `TICKET` as it stands, and
252
+ whoever appends the line fills it in.
250
253
 
251
254
  A placeholder or tag name in issue or comment text, such as `<slug>` or
252
255
  `<code>`, goes in backticks: GitHub drops an unknown tag and renders a
@@ -271,11 +274,12 @@ hook refuses the same in text sent to GitHub directly, as the
271
274
 
272
275
  The follow-ups issue builds as one branch and one pull request, one commit
273
276
  per line, once the owner approves it, by moving its card to Ready or
274
- telling a session to build it. The pull request closes it with `Closes #N`
275
- only when every line is checked; otherwise it starts with `Part of #N`,
276
- and the unchecked lines wait there. The sync reads `Part of #N` as a
277
- partial build, so any other link to the follow-ups issue words it
278
- differently. It has no spec tool change. `factory-build` appends a line and
277
+ telling a session to build it. The pull request closes it with the line
278
+ `npx --no-install factory ticket link N` prints only when every line is
279
+ checked; otherwise it starts with the line
280
+ `npx --no-install factory ticket link N --part` prints, and the unchecked
281
+ lines wait there. The sync reads that line as a partial build, so any
282
+ other link to the follow-ups issue words it differently. It has no spec tool change. `factory-build` appends a line and
279
283
  builds the issue; `factory-refine` refines it per line. Its lines can be
280
284
  about anything, so the one pull request waits for the owner when any line
281
285
  touches a file that does, and gets the fresh-agent trace ("Changing the
@@ -393,8 +393,9 @@ Never accept or reject from reading alone. Each finding gets evidence:
393
393
  there, say so rather than reasoning from memory.
394
394
  - **A claim about the codebase** gets a grep or a file read at the cited line.
395
395
  - **A finding that would reverse a choice** also gets the recorded reason:
396
- read the commit message, the pull request's body, and the issue's Decisions
397
- before accepting it. A session without the build context has only these. If
396
+ read the commit message, the pull request's body, and the Decisions of
397
+ each ticket `npx --no-install factory pr closes PR` prints, with
398
+ `npx --no-install factory ticket view N`, before accepting it. A session without the build context has only these. If
398
399
  the finding conflicts with a recorded decision and the evidence does not
399
400
  settle it, reply with both and leave the thread open for the owner.
400
401
 
@@ -551,7 +552,7 @@ again. Add whether the tests are good enough to make a swap verifiable.
551
552
  First, note what this round of work cost, on the pull request:
552
553
 
553
554
  ```bash
554
- npx --no-install factory ticket cost PR
555
+ npx --no-install factory pr cost PR
555
556
  ```
556
557
 
557
558
  It posts what the session spent at API list prices since its last note, or