ticket-runner 0.6.0

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/LICENSE +21 -0
  2. package/README.ko.md +97 -0
  3. package/README.md +98 -0
  4. package/bin/ticket-runner.js +6 -0
  5. package/docs/templates/operator-skill.md +87 -0
  6. package/package.json +42 -0
  7. package/src/acceptance-criteria.ts +44 -0
  8. package/src/adapters/claude-agent-runner.ts +389 -0
  9. package/src/adapters/exec.ts +169 -0
  10. package/src/adapters/gh-tracker.ts +955 -0
  11. package/src/adapters/git-workspace.ts +951 -0
  12. package/src/adapters/repo-root.ts +20 -0
  13. package/src/adapters/version.ts +118 -0
  14. package/src/base-branch.ts +21 -0
  15. package/src/branch.ts +33 -0
  16. package/src/cli.ts +135 -0
  17. package/src/command-line.ts +190 -0
  18. package/src/config.ts +277 -0
  19. package/src/conventions.ts +118 -0
  20. package/src/criteria.ts +106 -0
  21. package/src/frontier.ts +36 -0
  22. package/src/guards.ts +143 -0
  23. package/src/handoff.ts +82 -0
  24. package/src/host.ts +116 -0
  25. package/src/init.ts +405 -0
  26. package/src/labels.ts +42 -0
  27. package/src/landing.ts +75 -0
  28. package/src/lifecycle.ts +34 -0
  29. package/src/lock.ts +215 -0
  30. package/src/note-schema.ts +58 -0
  31. package/src/notes.ts +433 -0
  32. package/src/operator-skill.ts +24 -0
  33. package/src/orchestrator.ts +1816 -0
  34. package/src/ports/agent-runner.ts +105 -0
  35. package/src/ports/tracker.ts +334 -0
  36. package/src/ports/workspace.ts +422 -0
  37. package/src/progress.ts +231 -0
  38. package/src/prompts.ts +288 -0
  39. package/src/readiness.ts +256 -0
  40. package/src/remove.ts +732 -0
  41. package/src/resume.ts +145 -0
  42. package/src/run-log.ts +85 -0
  43. package/src/run.ts +331 -0
  44. package/src/self-hosting.ts +33 -0
  45. package/src/stage-guard.ts +32 -0
  46. package/src/staleness.ts +101 -0
  47. package/src/start.ts +284 -0
  48. package/src/startup.ts +34 -0
  49. package/src/stop.ts +178 -0
  50. package/src/stranded.ts +136 -0
  51. package/src/templates.ts +596 -0
  52. package/src/title.ts +97 -0
  53. package/src/verdict.ts +88 -0
  54. package/src/version-number.ts +67 -0
  55. package/src/version-pr.ts +103 -0
package/src/notes.ts ADDED
@@ -0,0 +1,433 @@
1
+ /**
2
+ * What a Stage does with a finding that is not this Ticket's business.
3
+ *
4
+ * A Stage that meets a defect in code it was not sent to touch has three bad
5
+ * options and one good one. Fixing it widens the Ticket past the Acceptance
6
+ * Criteria the Verdict grades. Ignoring it loses it. Writing it into the
7
+ * Ticket's own comments buries it under a Ticket that is about to close. So it
8
+ * records a **Note** instead, and the pipeline puts the Note where somebody
9
+ * will meet it: the comments of the Ticket it belongs to, or the standing
10
+ * Notes issue when it belongs to none yet.
11
+ *
12
+ * Notes ride along with the structured output of the implement, verify and fix
13
+ * Stages: the two that write code, which meet what they were not sent to touch,
14
+ * and the one that grades, whose Verdict has a slot per Acceptance Criterion and
15
+ * none for anything else it found. A Stage with nothing to report emits an empty
16
+ * list and is not treated differently for it.
17
+ */
18
+
19
+ import type { Tracker } from "./ports/tracker.js";
20
+ import {
21
+ NOTES_ISSUE_TITLE,
22
+ type NoteSubject,
23
+ isNotesIssue,
24
+ noteComment,
25
+ notesIssue,
26
+ } from "./templates.js";
27
+ import { z } from "zod";
28
+
29
+ /**
30
+ * A Stage that ends with Notes.
31
+ *
32
+ * Narrower than a Stage name on purpose: the conflict Stage is given no Notes
33
+ * channel — it finishes a rebase and touches no file the conflict did not — so
34
+ * a Note that claimed to come from one would be a Note nothing could have made.
35
+ */
36
+ export type NotingStage = "implement" | "verify" | "fix";
37
+
38
+ /**
39
+ * What a Note says, part by part. `summary` is the one part a Note cannot do
40
+ * without; the others are posted when the Stage wrote them.
41
+ */
42
+ export interface NoteText {
43
+ /** One short sentence naming the defect. */
44
+ summary: string;
45
+ /** Where the defect is and what shows it is real. */
46
+ evidence?: string;
47
+ /** What breaks, and for whom. */
48
+ impact?: string;
49
+ /** The fix, or the decision a human has to take before anyone can fix it. */
50
+ next?: string;
51
+ }
52
+
53
+ /** One finding, and the Ticket it belongs to when the Stage knew of one. */
54
+ export interface Note extends NoteText {
55
+ ticket?: number;
56
+ }
57
+
58
+ /** A Note that reached GitHub, which is what a Run summary reports. */
59
+ export interface RoutedNote {
60
+ /** The Ticket whose Stage made the finding. */
61
+ origin: number;
62
+ stage: NotingStage;
63
+ /** The issue the Note reached: the Ticket it named, or the standing Notes issue. */
64
+ issue: number;
65
+ /**
66
+ * Whether the pipeline opened that issue for it, which is true of one Note at
67
+ * most: the one that found no standing Notes issue open and needed one.
68
+ */
69
+ opened: boolean;
70
+ /** The Note's summary: the part a Run summary has room for. */
71
+ summary: string;
72
+ }
73
+
74
+ /** A part of a Note beside its summary, which costs only itself when it is malformed. */
75
+ const forgivenPart = z.string().optional().catch(undefined);
76
+
77
+ /**
78
+ * One entry of a Stage's `notes` list.
79
+ *
80
+ * `ticket` is read separately from the words and forgiven separately: a number
81
+ * the Stage wrote as a string, a float or a zero is no number, but the words
82
+ * beside it are still a finding. Dropping the entry over its label would lose
83
+ * exactly what this whole module exists to keep. The parts beside the summary
84
+ * are forgiven the same way, for the same reason: a Note without its impact is
85
+ * still a defect somebody should hear about.
86
+ */
87
+ const noteSchema = z.object({
88
+ ticket: z.number().int().positive().optional().catch(undefined),
89
+ summary: z.string(),
90
+ evidence: forgivenPart,
91
+ impact: forgivenPart,
92
+ next: forgivenPart,
93
+ });
94
+
95
+ /** The parts of a Note beside its summary. */
96
+ const NOTE_PARTS = ["evidence", "impact", "next"] as const;
97
+
98
+ /**
99
+ * The Notes in a Stage's structured output, and nothing else from it.
100
+ *
101
+ * Forgiving at every level, because a Stage that reported its work badly has
102
+ * still done the work: output that is not an object, a missing list, an entry
103
+ * the schema rejects and an entry with no summary each cost that one entry and
104
+ * leave the rest. A part beside the summary that is missing, malformed or blank
105
+ * costs that part, and the Note is posted with the ones it has. The alternative
106
+ * is a Ticket that fails over a malformed aside.
107
+ */
108
+ export function parseNotes(result: unknown): Note[] {
109
+ if (typeof result !== "object" || result === null) return [];
110
+ const raw = (result as { notes?: unknown }).notes;
111
+ if (!Array.isArray(raw)) return [];
112
+
113
+ return raw.flatMap((item) => {
114
+ const parsed = noteSchema.safeParse(item);
115
+ if (!parsed.success || parsed.data.summary.trim() === "") return [];
116
+ const { ticket, summary } = parsed.data;
117
+ const note: Note = ticket === undefined ? { summary } : { ticket, summary };
118
+ for (const part of NOTE_PARTS) {
119
+ const text = parsed.data[part];
120
+ if (text !== undefined && text.trim() !== "") note[part] = text;
121
+ }
122
+ return [note];
123
+ });
124
+ }
125
+
126
+ /** The standing Notes issue a Run resolved, and whether resolving it opened it. */
127
+ interface Standing {
128
+ number: number;
129
+ /** True for the one Note that needed the issue opened, and false after it. */
130
+ opened: boolean;
131
+ }
132
+
133
+ /** What it takes to find the standing Notes issue, or to open one. */
134
+ export interface StandingNotesLookup {
135
+ tracker: Tracker;
136
+ /** The label the standing Notes issue wears, and the one it is looked for under. */
137
+ needsTriage: string;
138
+ log?: (line: string) => void;
139
+ }
140
+
141
+ /**
142
+ * The standing Notes issue of a Run: the one issue every triage-bound Note
143
+ * becomes a comment on.
144
+ *
145
+ * A Run has one of these and every Ticket it drives shares it, so the lookup
146
+ * happens once however many Notes the night makes, and two Lanes writing Notes
147
+ * at the same time cannot open two issues: the first call starts the resolution
148
+ * and the second waits on the same promise. The Run lock already makes two Runs
149
+ * on one Target impossible, so single-flight in one process is the whole of
150
+ * what a race needs.
151
+ *
152
+ * A failed resolution is forgotten rather than remembered: the Note that asked
153
+ * for it is lost, as any Note a tracker refuses is, and the next one asks
154
+ * again rather than inheriting an outage that may be over.
155
+ */
156
+ /**
157
+ * One answer a Run works out at most once.
158
+ *
159
+ * The first caller starts the work and every caller after it waits on the same
160
+ * promise, which is what stops two Lanes asking GitHub the same question twice.
161
+ * A failure is forgotten rather than remembered: the caller that asked is told,
162
+ * and the next one may try again rather than inheriting an outage that may be
163
+ * over.
164
+ */
165
+ class Once<T> {
166
+ #attempt: Promise<T> | undefined;
167
+
168
+ /** The answer, worked out by this caller if nobody has asked yet. */
169
+ run(make: () => Promise<T>): Promise<T> {
170
+ const attempt = (this.#attempt ??= make());
171
+ return attempt.catch((error: unknown) => {
172
+ // Only this attempt is forgotten: one started while it was failing is
173
+ // somebody's live answer, not a stale one.
174
+ if (this.#attempt === attempt) this.#attempt = undefined;
175
+ throw error;
176
+ });
177
+ }
178
+
179
+ /** The answer somebody has already asked for, and nothing when nobody has. */
180
+ taken(): Promise<T> | undefined {
181
+ return this.#attempt;
182
+ }
183
+
184
+ /** Forget it, so the next caller works it out again. */
185
+ forget(): void {
186
+ this.#attempt = undefined;
187
+ }
188
+ }
189
+
190
+ export class StandingNotes {
191
+ /** The search for an issue already open, which a Run runs at most once. */
192
+ readonly #found = new Once<number | undefined>();
193
+
194
+ /** The issue this Run resolved, found or opened. */
195
+ readonly #standing = new Once<number>();
196
+
197
+ /**
198
+ * The issue this Run opened, until the Note that opened it has said so.
199
+ *
200
+ * One Note reports `opened`, and it is the one that needed the issue put on
201
+ * GitHub: taken rather than read, so the Notes after it report the comment
202
+ * they are.
203
+ */
204
+ #unreported: number | undefined;
205
+
206
+ /**
207
+ * The standing Notes issue's number when one is open, and nothing when none
208
+ * is. Opens none: this is what a Stage prompt is told, and a prompt is no
209
+ * reason to put an issue on GitHub.
210
+ *
211
+ * A lookup that fails answers with nothing rather than throwing. A Stage that
212
+ * is not told the number writes its Notes anyway, where a Stage that never
213
+ * ran writes none at all.
214
+ */
215
+ async current(lookup: StandingNotesLookup): Promise<number | undefined> {
216
+ try {
217
+ return await (this.#standing.taken() ?? this.#search(lookup));
218
+ } catch (error) {
219
+ lookup.log?.(
220
+ `could not look up the standing Notes issue: ${(error as Error).message}`,
221
+ );
222
+ return undefined;
223
+ }
224
+ }
225
+
226
+ /**
227
+ * The standing Notes issue's number, opening one when none is open.
228
+ *
229
+ * `opened` is true for the one Note that needed the issue opened and false
230
+ * for every Note after it, which is what a Run summary reports.
231
+ */
232
+ async resolve(lookup: StandingNotesLookup): Promise<Standing> {
233
+ const number = await this.#standing.run(async () => await this.#findOrOpen(lookup));
234
+ const opened = this.#unreported === number;
235
+ if (opened) this.#unreported = undefined;
236
+ return { number, opened };
237
+ }
238
+
239
+ async #findOrOpen(lookup: StandingNotesLookup): Promise<number> {
240
+ const found = await this.#search(lookup);
241
+ if (found !== undefined) return found;
242
+
243
+ try {
244
+ const issue = await lookup.tracker.createIssue({
245
+ ...notesIssue(),
246
+ labels: [lookup.needsTriage],
247
+ });
248
+ this.#unreported = issue.number;
249
+ lookup.log?.(`opened #${issue.number} to gather Notes for triage`);
250
+ return issue.number;
251
+ } catch (error) {
252
+ // The issue may be on GitHub and only the answer lost. The search that
253
+ // found nothing is forgotten with it, so the next Note looks again
254
+ // instead of opening a second standing issue over the same outage.
255
+ this.#found.forget();
256
+ throw error;
257
+ }
258
+ }
259
+
260
+ async #search(lookup: StandingNotesLookup): Promise<number | undefined> {
261
+ return await this.#found.run(async () => await findStandingNotes(lookup));
262
+ }
263
+ }
264
+
265
+ /**
266
+ * The open issue carrying the standing Notes marker, or nothing.
267
+ *
268
+ * The title is a fast path and never a proof: the candidates that carry it are
269
+ * read first, and an issue that carries it without the marker is somebody
270
+ * else's and is never written to. Where none of them confirms — there is no
271
+ * standing issue yet, or a human renamed the one there is — the rest of the
272
+ * open `needs-triage` issues are read for the marker. That is a read per
273
+ * candidate, paid once per Run, and only until a marked issue exists to be
274
+ * found by its title.
275
+ *
276
+ * Lowest number first, so two marked issues a human left open resolve to the
277
+ * same one every time rather than to whichever the tracker listed first.
278
+ */
279
+ export async function findStandingNotes({
280
+ tracker,
281
+ needsTriage,
282
+ }: StandingNotesLookup): Promise<number | undefined> {
283
+ const candidates = [...(await tracker.listCandidates(needsTriage))].sort(
284
+ (a, b) => a.number - b.number,
285
+ );
286
+ const named = (title: string) => title.trim() === NOTES_ISSUE_TITLE;
287
+ const ordered = [
288
+ ...candidates.filter((candidate) => named(candidate.title)),
289
+ ...candidates.filter((candidate) => !named(candidate.title)),
290
+ ];
291
+
292
+ for (const candidate of ordered) {
293
+ const issue = await tracker.getIssue(candidate.number);
294
+ if (isNotesIssue(issue.body)) return candidate.number;
295
+ }
296
+ return undefined;
297
+ }
298
+
299
+ export interface NoteRouting extends StandingNotesLookup {
300
+ /** The Ticket whose Stage made the findings. */
301
+ origin: number;
302
+ stage: NotingStage;
303
+ /** The label a claimed Ticket wears, which a Note reads as "do not comment here". */
304
+ inProgress: string;
305
+ /** The Run's standing Notes issue, which every triage-bound Note goes to. */
306
+ standing: StandingNotes;
307
+ }
308
+
309
+ /**
310
+ * Put every Note in a Stage's output where somebody will meet it.
311
+ *
312
+ * One Note that cannot be posted — a Ticket number the Stage invented, a
313
+ * tracker that refused the write — costs that Note and no more. Nothing here
314
+ * may end a Ticket: the Stage's own work is already committed, and a Ticket
315
+ * handed to a human over a failed aside would be a worse outcome than the aside
316
+ * being lost. So the failure is logged and the next Note is tried.
317
+ */
318
+ export async function routeNotes(
319
+ routing: NoteRouting,
320
+ result: unknown,
321
+ ): Promise<RoutedNote[]> {
322
+ const routed: RoutedNote[] = [];
323
+
324
+ for (const note of parseNotes(result)) {
325
+ try {
326
+ routed.push(await route(routing, note));
327
+ } catch (error) {
328
+ routing.log?.(
329
+ `#${routing.origin} could not route a Note: ${(error as Error).message}`,
330
+ );
331
+ }
332
+ }
333
+
334
+ return routed;
335
+ }
336
+
337
+ /**
338
+ * Where one Note goes: the Ticket it names, and otherwise the standing Notes
339
+ * issue.
340
+ *
341
+ * A Note that names the Ticket its own Stage is working on names no Ticket, as
342
+ * far as this is concerned. A Stage says that when it has found something the
343
+ * Acceptance Criteria do not cover, and commenting on that Ticket would file
344
+ * the finding under an issue that is about to be closed by the very Run that
345
+ * made it. The standing Notes issue outlives the Run; the Ticket does not.
346
+ *
347
+ * The same holds for any Ticket nobody will read again. A closed Ticket is
348
+ * finished. A claimed one has a Stage on it already — this Run's other Lane,
349
+ * another Run, a human — that read the Ticket when it started and will close it
350
+ * when it lands, so a comment posted meanwhile is read by nobody. A Spec is
351
+ * never implemented at all; only its Tickets are. Each of these takes the
352
+ * comment without complaint, which is exactly the problem: the write succeeds
353
+ * and the finding is buried. So they go to the standing Notes issue with the
354
+ * number they were meant for, and the comment says why.
355
+ *
356
+ * A Ticket that will not take the comment — a number the Stage invented, an
357
+ * issue somebody locked — falls to the standing Notes issue as well, carrying
358
+ * the number it was meant for. That issue is the fallback for everything,
359
+ * because the one outcome this module exists to prevent is a finding going
360
+ * nowhere.
361
+ */
362
+ async function route(routing: NoteRouting, note: Note): Promise<RoutedNote> {
363
+ const { tracker, origin, stage } = routing;
364
+ const { ticket, ...text } = note;
365
+ const from = { origin, stage, note: text };
366
+
367
+ if (ticket !== undefined && ticket !== origin) {
368
+ let buried: string | undefined;
369
+ try {
370
+ buried = await buriedOn(routing, ticket);
371
+ if (buried === undefined) {
372
+ await tracker.comment(ticket, noteComment(from));
373
+ routing.log?.(`#${origin} noted on #${ticket}`);
374
+ return { origin, stage, issue: ticket, opened: false, summary: text.summary };
375
+ }
376
+ } catch (error) {
377
+ routing.log?.(
378
+ `#${origin} could not comment its Note on #${ticket} ` +
379
+ `(${(error as Error).message}); sending it to triage instead`,
380
+ );
381
+ return await sendToTriage(routing, { ...from, intended: ticket });
382
+ }
383
+ routing.log?.(
384
+ `#${origin} will not comment its Note on #${ticket}, which ${buried}; ` +
385
+ "sending it to triage instead",
386
+ );
387
+ return await sendToTriage(routing, { ...from, intended: ticket, because: buried });
388
+ }
389
+
390
+ return await sendToTriage(routing, from);
391
+ }
392
+
393
+ /**
394
+ * Why a comment on this Ticket would be read by nobody, or nothing when it
395
+ * would be read. The words are the ones the Note comment's provenance line
396
+ * finishes with, after `which`.
397
+ *
398
+ * Claimed is the label alone, not the assignee with it: the pipeline's own
399
+ * Claim writes both, but a human who took a Ticket may have written only the
400
+ * label, and either way there is somebody on it.
401
+ */
402
+ async function buriedOn(routing: NoteRouting, ticket: number): Promise<string | undefined> {
403
+ const issue = await routing.tracker.getIssue(ticket);
404
+ if (issue.closed) return "is closed";
405
+ if (issue.subIssues > 0) return "is a Spec";
406
+ if (issue.labels.includes(routing.inProgress)) return "is claimed";
407
+ return undefined;
408
+ }
409
+
410
+ /**
411
+ * One Note, as a comment on the standing Notes issue — opening that issue first
412
+ * where this Run is the one that needed it.
413
+ *
414
+ * A comment rather than an issue of its own because the same condition is met
415
+ * by Stage after Stage, and a Target that opens an issue every time makes
416
+ * triage a job of gathering duplicates rather than reading findings. The facets
417
+ * are all kept; only the artifact they arrive in is one.
418
+ */
419
+ async function sendToTriage(
420
+ routing: NoteRouting,
421
+ subject: NoteSubject,
422
+ ): Promise<RoutedNote> {
423
+ const { number, opened } = await routing.standing.resolve(routing);
424
+ await routing.tracker.comment(number, noteComment(subject));
425
+ routing.log?.(`#${routing.origin} noted on #${number} for triage`);
426
+ return {
427
+ origin: routing.origin,
428
+ stage: routing.stage,
429
+ issue: number,
430
+ opened,
431
+ summary: subject.note.summary,
432
+ };
433
+ }
@@ -0,0 +1,24 @@
1
+ import { readFileSync } from "node:fs";
2
+
3
+ /**
4
+ * The Operator's instructions, as a project skill a Target carries (ADR-0008).
5
+ *
6
+ * A cloud session carries nothing over from the human's account, only the
7
+ * repository it was opened on, so the one place an Operator can learn what to
8
+ * do is the Target itself: `init` writes the skill there, and Target readiness
9
+ * asks for it on every Host.
10
+ *
11
+ * Its text is a shape like every other the pipeline writes, so it lives with
12
+ * them in `docs/templates/`, and it is read from there rather than copied into
13
+ * this module: the package carries that one file for this. The text names no
14
+ * Version. The Operator reads the one to install off the conventions document's
15
+ * mark, so a Target is never rewritten for a Version that changed nothing here.
16
+ */
17
+
18
+ /** Where the skill goes in a Target, relative to the Target's root. */
19
+ export const OPERATOR_SKILL_PATH = ".claude/skills/ticket-runner/SKILL.md";
20
+
21
+ /** The skill as {@link OPERATOR_SKILL_PATH} must contain it. */
22
+ export function operatorSkill(): string {
23
+ return readFileSync(new URL("../docs/templates/operator-skill.md", import.meta.url), "utf8");
24
+ }