ticket-runner 0.6.4 → 0.6.5

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 (48) hide show
  1. package/README.ko.md +4 -4
  2. package/README.md +3 -3
  3. package/docs/templates/operator-skill.md +7 -7
  4. package/package.json +1 -1
  5. package/src/acceptance-criteria.ts +2 -2
  6. package/src/adapters/claude-agent-runner.ts +3 -3
  7. package/src/adapters/exec.ts +19 -4
  8. package/src/adapters/gh-tracker.ts +17 -17
  9. package/src/adapters/git-workspace.ts +12 -8
  10. package/src/adapters/liveness.ts +77 -0
  11. package/src/adapters/process-tree.ts +4 -7
  12. package/src/adapters/version.ts +5 -5
  13. package/src/branch.ts +1 -1
  14. package/src/cli.ts +2 -2
  15. package/src/config.ts +4 -4
  16. package/src/conventions.ts +21 -18
  17. package/src/credential.ts +14 -13
  18. package/src/criteria.ts +107 -15
  19. package/src/failing-base.ts +7 -7
  20. package/src/failure-message.ts +72 -0
  21. package/src/guards.ts +2 -2
  22. package/src/handoff.ts +2 -2
  23. package/src/init.ts +8 -8
  24. package/src/landing.ts +1 -1
  25. package/src/lifecycle.ts +2 -2
  26. package/src/lock.ts +10 -2
  27. package/src/note-schema.ts +3 -3
  28. package/src/notes.ts +8 -6
  29. package/src/operator-skill.ts +2 -2
  30. package/src/orchestrator.ts +168 -128
  31. package/src/ports/agent-runner.ts +1 -1
  32. package/src/ports/tracker.ts +14 -13
  33. package/src/ports/workspace.ts +23 -22
  34. package/src/progress.ts +2 -2
  35. package/src/prompts.ts +67 -24
  36. package/src/readiness.ts +11 -11
  37. package/src/remove.ts +7 -7
  38. package/src/resume.ts +12 -12
  39. package/src/run-log.ts +5 -5
  40. package/src/run.ts +7 -7
  41. package/src/staleness.ts +14 -14
  42. package/src/start.ts +17 -12
  43. package/src/stranded.ts +19 -19
  44. package/src/templates.ts +147 -66
  45. package/src/title.ts +44 -8
  46. package/src/verdict.ts +7 -7
  47. package/src/version-number.ts +13 -13
  48. package/src/version-pr.ts +12 -12
@@ -11,7 +11,13 @@
11
11
  * vocabulary, the review rules, the test policy are the Target's business, and a
12
12
  * document that took them over would be rewritten out from under it.
13
13
  *
14
- * The one thing it says about Versions is the mark it bears: which pipeline
14
+ * It is for the readers the pipeline does not brief: humans, attended Claude
15
+ * sessions in a Target, and the Planning skills that write Tickets. It leaves
16
+ * out what the Stage prompts already say, such as how a Stage titles its branch
17
+ * and that it opens no pull request: a Stage hears those from its own prompt,
18
+ * and a second copy here would only drift from it.
19
+ *
20
+ * The one thing it says about versions is the mark it bears: which pipeline
15
21
  * wrote the copy a Target carries, hidden on the first line so no reader of the
16
22
  * document meets it. That is a direction comparing text never gives — `init`
17
23
  * leaves a document a newer pipeline wrote alone, and a Run behind one warns
@@ -37,7 +43,7 @@ export const CLAUDE_SECTION = `## Pipeline conventions
37
43
  `;
38
44
 
39
45
  /**
40
- * The marker carrying the Version, as the first line of the document ends.
46
+ * The marker carrying the version, as the first line of the document ends.
41
47
  *
42
48
  * An HTML comment, like every other marker the pipeline finds its own writing
43
49
  * by, so it is on the line a reader sees and in none of the text they read.
@@ -46,10 +52,10 @@ const MARKER = /<!-- ticket-runner:version ([^\s>]+) -->/;
46
52
 
47
53
  /**
48
54
  * The document itself, as {@link CONVENTIONS_PATH} must contain it, marked with
49
- * the Version writing it.
55
+ * the version writing it.
50
56
  *
51
57
  * The number alone, never the commit a development checkout adds: two checkouts
52
- * of one Version write one document, and a Target whose copy was rewritten by
58
+ * of one version write one document, and a Target whose copy was rewritten by
53
59
  * every commit would say nothing by having been.
54
60
  *
55
61
  * A copy with no number to stamp carries no marker rather than a marker saying
@@ -63,7 +69,7 @@ export function conventionsDoc(version: string): string {
63
69
  }
64
70
 
65
71
  /**
66
- * The Version number a Target's copy was written by, and undefined for a copy
72
+ * The version number a Target's copy was written by, and undefined for a copy
67
73
  * carrying no mark at all — every copy an older pipeline wrote, which is read
68
74
  * as being behind rather than as being wrong.
69
75
  */
@@ -73,25 +79,22 @@ export function conventionsMark(document: string | undefined): string | undefine
73
79
  return marked === undefined ? undefined : versionNumber(marked);
74
80
  }
75
81
 
76
- /** Everything under the marked first line, which no Version changes. */
82
+ /** Everything under the marked first line, which no version changes. */
77
83
  const BODY = `
78
84
  What \`ticket-runner\` requires of this repository, and nothing else. \`ticket-runner init\` writes this file and rewrites it whenever those requirements change, so an edit made here does not survive the next \`init\`. Everything the pipeline leaves to this repository — which commit types and scopes it uses, how it reviews, what it tests — belongs in the repository's own contributing guide.
79
85
 
86
+ Besides names such as GitHub and Claude Code, a capitalised word below is one of the pipeline's own terms, said in a few words where it first appears; every other word means what it ordinarily does. To the pipeline this repository is a Target, the repository a Run takes its work from and merges into. A Run is one invocation of the pipeline on a Host, the machine it executes on, and works through Tickets, GitHub issues each sized for one session of work, until it has none left to take or is told to take no more. Each Ticket is worked by Stages, each one Claude Code session with a single purpose: implement, verify, fix, or resolve a rebase conflict. A Stage may answer Notes beside its work: defects it met that belong to another Ticket or to none yet, recorded where a human will find them instead of being fixed there.
87
+
80
88
  ## Commits
81
89
 
82
90
  - Subject: \`<type>(<scope>): <summary>\`.
83
91
  - The type and scope vocabulary is this repository's own. The pipeline reads the shape, never the words.
84
- - A commit subject describes its own commit. The whole branch is summarised by the \`title\` the implement and fix Stages each answer beside their Notes: one line in the same shape. The latest one becomes the pull request title, and the pull request title becomes the subject of the squash commit that lands.
92
+ - This repository's own commit conventions must fit this shape: the pipeline titles its pull requests in it where it can, and so the squash commits they land as. Where it cannot, a pull request takes the Ticket's title.
85
93
 
86
94
  ## Branches
87
95
 
88
96
  - \`agent/<n>-<slug>\` belongs to the pipeline. A Run creates one per Ticket, works in a worktree of it, and pushes it after every Stage that commits. The repository deletes it when the pull request merges, a setting \`ticket-runner init\` switches on. Nothing else branches there.
89
- - \`ticket-runner/lock\` and \`ticket-runner/state\` belong to the pipeline too. The first says which Run holds this repository, and the second keeps the State of every Ticket a Run can resume, and the transcripts of a handed-off Ticket's Stages. Nothing else commits to either, except a human, or an Operator a human asked, releasing a lock a vanished Host left behind.
90
- - A Stage commits only to the branch already checked out in the worktree it was started in. It creates no branch and switches to none.
91
-
92
- ## What a Stage does not do
93
-
94
- - A Stage opens no pull request and closes no issue. The pipeline opens the pull request when the Stage finishes, waits for CI, merges it, and lets the merge close the Ticket.
97
+ - \`ticket-runner/lock\` and \`ticket-runner/state\` belong to the pipeline too. The first says which Run holds this repository, and the second keeps the state file of every Ticket a Run can resume, and the transcripts of the Stages of a handed-off Ticket. A Hand-off gives a Ticket to a human rather than merging it, and leaves its work where they can carry on from it. Nothing else commits to either, except a human, or an Operator a human asked, the Claude session a human opens on a cloud Host from the Claude app to start a Run, watch it and stop it, releasing a lock a vanished Host left behind.
95
98
 
96
99
  ## What a Ticket needs
97
100
 
@@ -103,17 +106,17 @@ A Ticket is one issue the pipeline can implement in a single session. It is refu
103
106
 
104
107
  ## Checks
105
108
 
106
- - The Checks of different Tickets may run at the same time, each in its own worktree, because a Run has as many Lanes as \`lanes\` says. A Target whose Checks need a port, a database or anything else they would have to share keeps \`lanes\` at one, or makes them independent of each other.
107
- - A Check that fails on a Ticket's branch, or CI that fails on its pull request, is graded again at what the branch inherited: the pipeline runs the Check commands in a clean worktree at the branch's merge-base with the Base branch. One that fails there too is the Base branch's, not the Ticket's, so the Ticket is released without spending its Fix budget, the Run claims no more Tickets, and the pipeline posts a Note on the standing Notes issue naming the Check. The next Run rebases the Ticket onto the Base branch before its Checks, so mending the Base branch is what frees it. Nothing is installed in the worktree at the merge-base: its Checks find their dependencies in the main checkout, as a Ticket's worktree does, so Checks that need an install or a build step of their own fail there and release the Ticket, and the Note's output shows it.
109
+ - A Check is a command the pipeline runs itself on a Ticket's code to gate it, such as its tests or its typecheck, and never the CI on a pull request, which the pipeline only waits for. The Checks of different Tickets may run at the same time, each in its own worktree, because a Run has as many Lanes as \`lanes\` says, and each Lane holds one Ticket in progress. A Target whose Checks need a port, a database or anything else they would have to share keeps \`lanes\` at one, or makes them independent of each other.
110
+ - A Check that fails on a Ticket's branch, or CI that fails on its pull request, is graded again at what the branch inherited: the pipeline runs the Check commands in a clean worktree at the branch's merge-base with the base branch. One that fails there too is the base branch's, not the Ticket's, so the Ticket is released, given back to the pipeline for a later Run to take up again, as something outside the Ticket stopped its work. That Release spends none of its fix budget (the fix Stages it is allowed), the Run claims no more Tickets, and the pipeline posts a Note on the standing Notes issue naming the Check. The next Run rebases the Ticket onto the base branch before its Checks, so mending the base branch is what frees it. Nothing is installed in the worktree at the merge-base: its Checks find their dependencies in the main checkout, as a Ticket's worktree does, so Checks that need an install or a build step of their own fail there and release the Ticket, and the Note's output shows it.
108
111
 
109
112
  ## The Operator's skill
110
113
 
111
- - \`.claude/skills/ticket-runner/\` belongs to the pipeline. It tells an Operator, the Claude session a human opens on this repository from the Claude app, how to start a Run, report on it and stop it. \`ticket-runner init\` writes it and rewrites it like this file, so an edit made there does not survive the next \`init\` either.
114
+ - \`.claude/skills/ticket-runner/\` belongs to the pipeline. It tells an Operator how to start a Run, report on it and pass on a Stop, a human's request that the Run finish the Tickets its Lanes hold and take no more. \`ticket-runner init\` writes it and rewrites it like this file, so an edit made there does not survive the next \`init\` either.
112
115
 
113
116
  ## Local directories
114
117
 
115
118
  Both are \`ticket-runner\`'s own, both are gitignored by \`ticket-runner init\`, and neither is ever committed.
116
119
 
117
- - \`.worktrees/ticket-<n>/\` — one git worktree per claimed Ticket, where its Stages run. Beside them, \`.worktrees/base-<commit>/\` is a clean worktree at a merge-base with the Base branch, made to run a failing Check there once and removed when it has run.
118
- - \`.ticket-runner/\` — the Run's logs and Stage transcripts. The Run lock and the State a Ticket keeps while its branch has work worth resuming are not here but on the Target's remote, so that a Run on any Host sees which Run holds the Target, and carries on from where a killed Run, or a handed-off Ticket relabelled \`ready-for-agent\`, stopped.
120
+ - \`.worktrees/ticket-<n>/\` — one git worktree per claimed Ticket, where its Stages run. Beside them, \`.worktrees/base-<commit>/\` is a clean worktree at a merge-base with the base branch, made to run a failing Check there once and removed when it has run.
121
+ - \`.ticket-runner/\` — the Run's logs and Stage transcripts. The Run lock and the state file a Ticket keeps while its branch has work worth resuming are not here but on the Target's remote, so that a Run on any Host sees which Run holds the Target, and carries on from where a killed Run, or a handed-off Ticket relabelled \`ready-for-agent\`, stopped.
119
122
  `;
package/src/credential.ts CHANGED
@@ -16,25 +16,26 @@ export type Credential = "subscription" | "api-key";
16
16
  */
17
17
  export const API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
18
18
 
19
- /** The credential, as the Run summary's header and the log name it. */
19
+ /** What the Stages are billed to, as the Run summary's header and the log name it. */
20
20
  export const CREDENTIAL_WORDS: Record<Credential, string> = {
21
21
  subscription: "subscription",
22
22
  "api-key": "API key",
23
23
  };
24
24
 
25
25
  /**
26
- * The `apiKeySource` a Stage's `system/init` event reports when it ran on the
27
- * Run's credential. Any other is a Stage billed somewhere the Run did not
28
- * choose: a key an `apiKeyHelper` in the Host's settings supplied, say, which
29
- * no environment variable removes.
26
+ * The `apiKeySource` a Stage's `system/init` event reports when it was billed
27
+ * to the subscription or API key its Run started with. Any other is a Stage
28
+ * billed somewhere the Run did not choose: a key an `apiKeyHelper` in the
29
+ * Host's settings supplied, say, which no environment variable removes.
30
30
  */
31
31
  export function expectedKeySource(credential: Credential): string {
32
32
  return credential === "api-key" ? API_KEY_ENV_VAR : "none";
33
33
  }
34
34
 
35
35
  /**
36
- * A Stage that reported another `apiKeySource` than its Run's credential
37
- * expects, which the Run's log and its summary each name.
36
+ * A Stage that reported another `apiKeySource` than the one
37
+ * {@link expectedKeySource} gives its Run, which the Run's log and its
38
+ * summary each name.
38
39
  */
39
40
  export interface StrayStage {
40
41
  ticket: number;
@@ -49,14 +50,14 @@ export interface StrayStage {
49
50
 
50
51
  /**
51
52
  * What a Run's Stages were billed, gathered as each comes back and shared by
52
- * every Ticket, for the Run summary and nothing else: the log and the Progress
53
+ * every Ticket, for the Run summary and nothing else: the log and the progress
53
54
  * comment carry no amount.
54
55
  */
55
56
  export interface Billing {
56
- /** Every Stage that ran on something other than the Run's credential, in order. */
57
+ /** Every Stage billed to something other than its Run's subscription or API key, in order. */
57
58
  strays: StrayStage[];
58
59
  /**
59
- * The Spend, in dollars: the CLI's figures for the Stages of an `--api-key`
60
+ * The spend, in dollars: the CLI's figures for the Stages of an `--api-key`
60
61
  * Run that ran on the Run's own key, added up, which is the amount that key's
61
62
  * Console can be checked against. Always zero on a subscription Run, whose
62
63
  * figure is an estimate at API prices and not money spent.
@@ -65,7 +66,7 @@ export interface Billing {
65
66
  /**
66
67
  * Whether a Stage that ran on the Run's own key reported no figure, or only
67
68
  * part of its session's — one the wall-clock limit stopped or that crashed —
68
- * so the Spend is at least {@link spendUsd}.
69
+ * so the spend is at least {@link spendUsd}.
69
70
  */
70
71
  spendUnreported: boolean;
71
72
  /** Whether any Stage said it ran on the subscription's extra usage. */
@@ -94,8 +95,8 @@ export interface StageBilling {
94
95
  * a stray where it ran on something else.
95
96
  *
96
97
  * A Stage that reported no `apiKeySource` printed no `system/init` event and so
97
- * made no request: it is no stray, adds no Spend and leaves the Spend exact. A
98
- * stray's figure stays on its own row and out of the Spend, which is the Run's
98
+ * made no request: it is no stray, adds no spend and leaves the spend exact. A
99
+ * stray's figure stays on its own row and out of the spend, which is the Run's
99
100
  * own key's alone.
100
101
  */
101
102
  export function recordStage(
package/src/criteria.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /**
2
- * Ticking the Acceptance Criteria a Verdict proved.
2
+ * Ticking the Acceptance Criteria a verdict proved.
3
3
  *
4
4
  * A merged Ticket whose checkboxes are all still empty reads as unfinished
5
5
  * work, so the criteria verify marked `met` are ticked where they live — the
@@ -19,45 +19,134 @@ import type { Verdict } from "./verdict.js";
19
19
  /** {@link UNCHECKED_BOX}, extended to capture the criterion text after the box. */
20
20
  const CHECKBOX_LINE = new RegExp(`${UNCHECKED_BOX}( .*)$`, "gm");
21
21
 
22
+ /** {@link TICKED_BOX}, likewise: a line whose criterion is written, though not open. */
23
+ const TICKED_CHECKBOX_LINE = new RegExp(`${TICKED_BOX}( .*)$`, "gm");
24
+
22
25
  /** {@link TICKED_BOX}, over every line of a text rather than the first. */
23
26
  const TICKED_LINE = new RegExp(TICKED_BOX, "gm");
24
27
 
28
+ /** One parenthetical closing a criterion, with the space before it. */
29
+ const TRAILING_PARENTHETICAL = /\s*\([^()]*\)$/;
30
+
31
+ /**
32
+ * Where the verify Stage cut a passage, with the spaces it set the cut off by:
33
+ * a cut takes a comma or a space beside it as often as not, so `reads ... order`
34
+ * stands for `reads, in order`.
35
+ */
36
+ const ELLIPSIS = /\s*(?:\.\.\.|…)\s*/;
37
+
25
38
  /**
26
39
  * The same criterion as the verify Stage reported it.
27
40
  *
28
41
  * The Stage is asked for the criterion verbatim and mostly obliges, but it
29
42
  * reflows and recases often enough that an exact match would leave half a
30
- * Ticket unticked. Whitespace and case are the differences worth forgiving;
31
- * anything more and the risk is ticking a box nobody graded.
43
+ * Ticket unticked. Whitespace and case are the differences worth forgiving on
44
+ * every criterion; anything more and the risk is ticking a box nobody graded.
45
+ *
46
+ * A criterion that matches no checkbox even so gets {@link secondChancePattern},
47
+ * and the reasons for its two forgivenesses are given there.
32
48
  */
33
49
  function normalise(text: string): string {
34
50
  return text.trim().replaceAll(/\s+/g, " ").toLowerCase();
35
51
  }
36
52
 
37
53
  /**
38
- * `text` with every unticked box whose criterion is in `met` ticked.
54
+ * The pattern a {@link normalise}d criterion that matched no line exactly is
55
+ * matched again with: one trailing parenthetical dropped, and each `...` or `…`
56
+ * read as any run of characters.
57
+ *
58
+ * The verify Stage appends a note such as `(table)` to a criterion that ends in
59
+ * a colon and puts its content in a block below it, and cuts passages of a long
60
+ * criterion to an ellipsis. Both are seen in the Stage's own output, and nothing
61
+ * else is forgiven here. Either makes a criterion looser than its whole text,
62
+ * so the pattern ticks a line only when it picks out one.
63
+ *
64
+ * `undefined` when nothing but dots is left, which would match any line.
65
+ */
66
+ function secondChancePattern(criterion: string): RegExp | undefined {
67
+ const passages = criterion.replace(TRAILING_PARENTHETICAL, "").split(ELLIPSIS);
68
+ if (passages.every((passage) => passage.trim() === "")) return undefined;
69
+ return new RegExp(`^${passages.map(escapeRegExp).join(".*")}$`);
70
+ }
71
+
72
+ function escapeRegExp(text: string): string {
73
+ return text.replaceAll(/[.*+?^${}()|[\]\\]/g, String.raw`\$&`);
74
+ }
75
+
76
+ /**
77
+ * `texts` with every unticked box whose criterion is in `met` ticked, the texts
78
+ * being every place one Ticket writes its criteria: its body and its comments.
39
79
  *
40
- * Returns the text unchanged when nothing matched, which is how the caller
41
- * knows there is nothing to write back.
80
+ * A criterion ticks every line it matches exactly, after {@link normalise}. One
81
+ * that matches no checkbox line in any of the texts, ticked or not, is then
82
+ * offered its {@link secondChancePattern} against the lines still unticked, all the
83
+ * texts' together, and ticks a line only when exactly one matches. Two lines
84
+ * that fit equally well are a guess, and a wrong tick claims a criterion was
85
+ * graded that never was; an unticked one only says the match failed.
86
+ *
87
+ * Returns each text unchanged when nothing in it matched, which is how the
88
+ * caller knows there is nothing to write back.
42
89
  */
43
- export function tickCriteria(text: string, met: string[]): string {
90
+ export function tickCriteria(texts: readonly string[], met: readonly string[]): string[] {
44
91
  const wanted = new Set(met.map(normalise));
45
- if (wanted.size === 0) return text;
92
+ if (wanted.size === 0) return [...texts];
93
+
94
+ const exact = texts.map((text) => tickLines(text, (rest) => wanted.has(normalise(rest))));
95
+
96
+ const written = new Set(
97
+ texts.flatMap((text) =>
98
+ [CHECKBOX_LINE, TICKED_CHECKBOX_LINE].flatMap((pattern) =>
99
+ [...text.matchAll(pattern)].map(([, , rest = ""]) => normalise(rest)),
100
+ ),
101
+ ),
102
+ );
103
+ const missed = [...wanted].filter((criterion) => !written.has(criterion));
104
+ if (missed.length === 0) return exact;
105
+
106
+ const open = exact.flatMap((text, place) =>
107
+ [...text.matchAll(CHECKBOX_LINE)].map(({ index, 2: rest = "" }) => ({
108
+ key: lineKey(place, index),
109
+ text: normalise(rest),
110
+ })),
111
+ );
112
+ const chosen = new Set<string>();
113
+ for (const criterion of missed) {
114
+ const pattern = secondChancePattern(criterion);
115
+ if (pattern === undefined) continue;
116
+ const matches = open.filter((line) => pattern.test(line.text));
117
+ if (matches.length === 1 && matches[0] !== undefined) chosen.add(matches[0].key);
118
+ }
119
+ if (chosen.size === 0) return exact;
46
120
 
47
- return text.replaceAll(CHECKBOX_LINE, (line, bullet: string, rest: string) =>
48
- wanted.has(normalise(rest)) ? `${bullet}[x]${rest}` : line,
121
+ return exact.map((text, place) =>
122
+ tickLines(text, (_rest, index) => chosen.has(lineKey(place, index))),
49
123
  );
50
124
  }
51
125
 
126
+ /** `text` with each unticked box ticked whose line `tick` picks, by its criterion or offset. */
127
+ function tickLines(text: string, tick: (rest: string, index: number) => boolean): string {
128
+ return text.replaceAll(CHECKBOX_LINE, (line, bullet: string, rest: string, index: number) =>
129
+ tick(rest, index) ? `${bullet}[x]${rest}` : line,
130
+ );
131
+ }
132
+
133
+ /** One checkbox line on the whole Ticket: which text it is in, and where in it. */
134
+ function lineKey(place: number, index: number): string {
135
+ return `${place}:${index}`;
136
+ }
137
+
52
138
  /**
53
- * Tick every criterion the Verdict proved, wherever the Ticket writes it.
139
+ * Tick every criterion the verdict proved, wherever the Ticket writes it.
54
140
  *
55
141
  * The issue is read again rather than reusing the copy it was claimed with: a
56
142
  * whole Run has happened since, and both the body and any comment are written
57
143
  * back whole. Triage posts its brief as a comment, and nothing says all the
58
144
  * criteria are in one place, so every comment is offered the same edit.
59
145
  *
60
- * A criterion the Stage reworded past {@link normalise} matches nothing and is
146
+ * The body and the comments are matched together, because a criterion's second
147
+ * chance must pick out one line on the whole Ticket, not one in each place.
148
+ *
149
+ * A criterion the Stage reworded past both chances matches nothing and is
61
150
  * left as it was, which is said out loud rather than passed over in silence: a
62
151
  * merged Ticket with an unticked criterion is otherwise a mystery.
63
152
  */
@@ -73,16 +162,19 @@ export async function tickMetCriteria(
73
162
  if (met.length === 0) return;
74
163
 
75
164
  const issue = await tracker.getIssue(ticket);
165
+ const [body = issue.body, ...comments] = tickCriteria(
166
+ [issue.body, ...issue.comments.map((comment) => comment.body)],
167
+ met,
168
+ );
76
169
  let ticked = 0;
77
170
 
78
- const body = tickCriteria(issue.body, met);
79
171
  if (body !== issue.body) {
80
172
  await tracker.updateIssueBody(ticket, body);
81
173
  ticked += ticks(issue.body, body);
82
174
  }
83
175
 
84
- for (const comment of issue.comments) {
85
- const edited = tickCriteria(comment.body, met);
176
+ for (const [place, comment] of issue.comments.entries()) {
177
+ const edited = comments[place] ?? comment.body;
86
178
  if (edited === comment.body || comment.id === undefined) continue;
87
179
  await tracker.updateComment(comment.id, edited);
88
180
  ticked += ticks(comment.body, edited);
@@ -2,20 +2,20 @@
2
2
  * Whether a Check a Ticket's branch failed is one it inherited.
3
3
  *
4
4
  * The Checks run on the Ticket's branch, and CI on its pull request, so a
5
- * failure alone cannot say whether the branch brought it or the Base branch
6
- * did. A test that starts failing on the Base branch fails on every branch at
5
+ * failure alone cannot say whether the branch brought it or the base branch
6
+ * did. A test that starts failing on the base branch fails on every branch at
7
7
  * once, and a fix Stage per Ticket then mends it differently in each pull
8
- * request, at the cost of every Ticket's Fix budget. So a failure is graded
9
- * once more, at what the branch inherited: its merge-base with the Base branch,
8
+ * request, at the cost of every Ticket's fix budget. So a failure is graded
9
+ * once more, at what the branch inherited: its merge-base with the base branch,
10
10
  * checked out clean in a worktree of its own. One that fails there too is the
11
- * Base branch's, and the Ticket is released rather than charged for it.
11
+ * base branch's, and the Ticket is released rather than charged for it.
12
12
  */
13
13
 
14
14
  import { baseWorktreePath } from "./branch.js";
15
15
  import type { RoutedNote } from "./notes.js";
16
16
  import type { CheckOutcome, Workspace } from "./ports/workspace.js";
17
17
 
18
- /** A Check command the Base branch fails, and how. */
18
+ /** A Check command the base branch fails, and how. */
19
19
  export interface FailingBase {
20
20
  /** The merge-base it fails at, in full. */
21
21
  commit: string;
@@ -38,7 +38,7 @@ export interface BaseCheckRun {
38
38
  * posted about the ones that failed there.
39
39
  *
40
40
  * A Run has one and every Lane shares it, so the Tickets that fail together
41
- * over one broken Base branch cost one run of the Check between them, and one
41
+ * over one broken base branch cost one run of the Check between them, and one
42
42
  * Note. Runs at the same commit take turns, because they share its worktree.
43
43
  * A run that could not be made — no worktree, no git — is forgotten rather
44
44
  * than kept, as a standing Notes lookup that failed is: the Ticket that asked
@@ -0,0 +1,72 @@
1
+ /**
2
+ * An error message as the pipeline shows it.
3
+ *
4
+ * A failure the pipeline did not expect reaches it as an error whose message
5
+ * is a command and how it exited, on its first line, and then whatever the
6
+ * command printed: `throwOnFailure` in `adapters/exec.ts` builds it so, giving
7
+ * an argument with a newline in it by its first line alone. Wherever one line
8
+ * is expected — a hand-off's `Failure:` line, a draft pull request's opening,
9
+ * a Run summary's row, a console log line — the first line goes, and the
10
+ * output goes where the whole of it can be read. No line of the output is
11
+ * picked as the reason: a rule that picked one would name the wrong cause on
12
+ * an output nobody has seen yet, and the output is never dropped.
13
+ */
14
+
15
+ /** A message's one line, and the output that followed it. */
16
+ export interface SplitMessage {
17
+ /** The first line that says anything: the command and how it exited. */
18
+ line: string;
19
+ /** Everything after it, trimmed; empty when the message is one line. */
20
+ output: string;
21
+ }
22
+
23
+ export function splitMessage(message: string): SplitMessage {
24
+ const lines = message.split("\n");
25
+ const first = lines.findIndex((line) => line.trim() !== "");
26
+ if (first === -1) return { line: "", output: "" };
27
+ return {
28
+ line: lines[first]!.trim(),
29
+ output: lines
30
+ .slice(first + 1)
31
+ .join("\n")
32
+ .trim(),
33
+ };
34
+ }
35
+
36
+ /**
37
+ * What a log line whose output was already printed in this Run says in place
38
+ * of printing it again.
39
+ */
40
+ const SAME_OUTPUT = "the same output as above";
41
+
42
+ /**
43
+ * The Run's console log, printing each failure's output once.
44
+ *
45
+ * One cause tends to fail several steps of a Ticket in turn — a remote that
46
+ * refuses SSH fails the push, the draft pull request, the transcripts and the
47
+ * pull the rebase starts with — and each event logs the same output. Printed
48
+ * nine times it buries the lines that matter, so a line whose output this log
49
+ * has already printed gives its one line and says the output is the same.
50
+ * A line with no output passes as it is.
51
+ */
52
+ export function printEachOutputOnce(print: (line: string) => void): (line: string) => void {
53
+ const printed = new Set<string>();
54
+ return (text) => {
55
+ const { line, output } = splitMessage(text);
56
+ if (output === "") return print(text);
57
+ if (printed.has(output)) return print(`${line} · ${SAME_OUTPUT}`);
58
+ printed.add(output);
59
+ print(text);
60
+ };
61
+ }
62
+
63
+ /**
64
+ * A quoted message ended as a sentence, so that a sentence can follow it.
65
+ *
66
+ * A command's output often ends with its own full stop, and one appended after
67
+ * it reads as a typo: "…and the repository exists.. It still names this Run".
68
+ */
69
+ export function endSentence(message: string): string {
70
+ const trimmed = message.trimEnd();
71
+ return /[.!?]$/.test(trimmed) ? trimmed : `${trimmed}.`;
72
+ }
package/src/guards.ts CHANGED
@@ -54,8 +54,8 @@ export function skipReason(
54
54
  /**
55
55
  * Whether this is a **Stranded Ticket**: one this checkout already holds, left
56
56
  * claimed by a Run that never came back (GLOSSARY.md). Both refusals read the
57
- * Claim as somebody else's work, and a stranded Ticket wears it itself — the
58
- * assignee is this very user and `ready-for-agent` came off when the Claim was
57
+ * claim as somebody else's work, and a stranded Ticket wears it itself — the
58
+ * assignee is this very user and `ready-for-agent` came off when the claim was
59
59
  * made — so it passes them and is resumed rather than refused. The Planning
60
60
  * guards below still grade it: they are about the issue, not about who has it.
61
61
  *
package/src/handoff.ts CHANGED
@@ -5,7 +5,7 @@
5
5
  * the Ticket is relabelled and a Run takes it again, the comment still reads as
6
6
  * the last word on it — and on a Ticket that then merges it is the last thing
7
7
  * on a closed issue, because the progress comment is edited in place above it
8
- * and the merge writes nothing below. So the Claim marks every hand-off comment
8
+ * and the merge writes nothing below. So the claim marks every hand-off comment
9
9
  * on the Ticket as history on its way past.
10
10
  *
11
11
  * Marked, not removed: the failure, the location and the evidence are worth
@@ -21,7 +21,7 @@ import { HANDOFF_MARKER, findMarkedComments, handoffTakenComment } from "./templ
21
21
  * Every hand-off comment the Ticket is still carrying as current, each with the
22
22
  * body that would mark it as history.
23
23
  *
24
- * One question, asked twice: it is what the Claim edits, and it is also what
24
+ * One question, asked twice: it is what the claim edits, and it is also what
25
25
  * says a human has been holding the Ticket since the last Run put it down.
26
26
  */
27
27
  function unmarkedHandoffs(
package/src/init.ts CHANGED
@@ -63,12 +63,12 @@ const FAIL = "✗";
63
63
  export interface InitOptions {
64
64
  repoRoot: string;
65
65
  /**
66
- * The Version doing the setting up, which the report's first line names. A
66
+ * The version doing the setting up, which the report's first line names. A
67
67
  * string the CLI resolved, never something read from here (ADR-0007).
68
68
  */
69
69
  version: string;
70
70
  /**
71
- * The pipeline's own repository, as `owner/name`, which the newer-Version
71
+ * The pipeline's own repository, as `owner/name`, which the newer-version
72
72
  * notice is looked up against; see {@link import("./staleness.js")}.
73
73
  */
74
74
  repository?: string | undefined;
@@ -170,7 +170,7 @@ function writeTargetFiles(repoRoot: string, version: string): string[] {
170
170
  }
171
171
 
172
172
  /**
173
- * The Version that set this Target up, where it is newer than the one setting
173
+ * The version that set this Target up, where it is newer than the one setting
174
174
  * it up now, and nothing otherwise.
175
175
  *
176
176
  * Read off the conventions document's mark, which is the only thing in a
@@ -184,7 +184,7 @@ export function newerSetUp(repoRoot: string, version: string): NewerSetUp | unde
184
184
  : undefined;
185
185
  }
186
186
 
187
- /** Which newer Version set a Target up, and which one found it. */
187
+ /** Which newer version set a Target up, and which one found it. */
188
188
  export interface NewerSetUp {
189
189
  mark: string;
190
190
  own: string;
@@ -229,7 +229,7 @@ function ensureConfigFile(repoRoot: string): string | undefined {
229
229
  *
230
230
  * The mark is read before the text, because it is the only thing that says
231
231
  * which way round the two copies are. Nothing is refused either way: a Target
232
- * is not worse for carrying a document from another Version.
232
+ * is not worse for carrying a document from another version.
233
233
  */
234
234
  function ensureConventionsDoc(
235
235
  repoRoot: string,
@@ -254,9 +254,9 @@ function ensureConventionsDoc(
254
254
  /**
255
255
  * Which of the four ways a copy came to be rewritten this one was.
256
256
  *
257
- * A copy marked with this very Version is the odd one: nothing about the
257
+ * A copy marked with this very version is the odd one: nothing about the
258
258
  * pipeline moved, so the difference is something the Target did to the file,
259
- * and saying it was left by the Version now writing it would read as nonsense.
259
+ * and saying it was left by the version now writing it would read as nonsense.
260
260
  */
261
261
  function rewritten(
262
262
  existing: string | undefined,
@@ -264,7 +264,7 @@ function rewritten(
264
264
  own: string | undefined,
265
265
  ): string {
266
266
  if (existing === undefined) return "written";
267
- if (mark === undefined) return "overwritten, because the copy here carried no Version";
267
+ if (mark === undefined) return "overwritten, because the copy here carried no version";
268
268
  if (mark === own) return "overwritten, because the copy here said something else";
269
269
  return `overwritten, because the copy here was left by ${mark}`;
270
270
  }
package/src/landing.ts CHANGED
@@ -17,7 +17,7 @@ export interface LandingTurn {
17
17
  * The Landing: the stretch of a Ticket from its rebase to the pull of the Base
18
18
  * branch after its merge, which one Ticket is in at a time (ADR-0005).
19
19
  *
20
- * A Run has one and every Ticket it drives shares it, so the Base branch cannot
20
+ * A Run has one and every Ticket it drives shares it, so the base branch cannot
21
21
  * move between a Ticket's rebase and its merge: what CI graded is what lands.
22
22
  * Turns are taken in arrival order — the Ticket that reaches the rebase first
23
23
  * lands first, whatever its number — and a Ticket that leaves the stretch for a
package/src/lifecycle.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * Where a Ticket was when it failed. Named after the lifecycle step, not the
3
- * Stage, because Checks, rebase, PR and CI are not agent sessions.
3
+ * Stage, because Checks, rebase, pull request and CI are not agent sessions.
4
4
  */
5
5
  export type FailurePoint =
6
6
  | "setup"
@@ -19,7 +19,7 @@ export type FailurePoint =
19
19
  *
20
20
  * Every other failure ends the Ticket where it stands, because none of them is
21
21
  * a defect in the code a fresh session could go and mend: a Stage that never
22
- * came back, a Verdict with no evidence in it, a pull request whose checks
22
+ * came back, a verdict with no evidence in it, a pull request whose checks
23
23
  * timed out or never ran. A rebase conflict is on this list only once the
24
24
  * conflict Stage has failed to resolve it, which is what makes it a defect in
25
25
  * the branch rather than a state nobody has tried to mend yet. Uncommitted work
package/src/lock.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { execFileSync } from "node:child_process";
2
2
  import { readFileSync } from "node:fs";
3
+ import { endSentence } from "./failure-message.js";
3
4
  import { type Host, describeHost, sameHost } from "./host.js";
4
5
  import type { HeldLock, LockHolder } from "./ports/workspace.js";
5
6
 
@@ -57,10 +58,17 @@ export function lockFileContents(holder: LockHolder | undefined): string {
57
58
  /**
58
59
  * The commit message a lock change carries, which is what GitHub shows beside
59
60
  * the branch: who holds the Target, or that nobody does.
61
+ *
62
+ * A command that named a Ticket as `#<n>`, as `ticket-runner run #12` may, is
63
+ * written here without the `#`: GitHub links a pushed commit that mentions
64
+ * `#<n>` to issue `<n>`, on whatever branch the commit is, so every take would
65
+ * leave a line on that Ticket's timeline. The lock file keeps the command as it
66
+ * was typed.
60
67
  */
61
68
  export function lockCommitMessage(holder: LockHolder | undefined): string {
62
69
  if (holder === undefined) return "Free";
63
- return `Held by run ${holder.runId} on ${describeHost(holder.host)}: ${holder.command}`;
70
+ const command = holder.command.replace(/#+(?=\d)/g, "");
71
+ return `Held by run ${holder.runId} on ${describeHost(holder.host)}: ${command}`;
64
72
  }
65
73
 
66
74
  /**
@@ -121,7 +129,7 @@ export function lockHeldMessage({ holder, onAnotherHost }: HeldLock): string {
121
129
  */
122
130
  export function unreleasedLockMessage(reason: string): string {
123
131
  return (
124
- `Could not release the Run lock: ${reason}. It still names this Run on the ` +
132
+ `Could not release the Run lock: ${endSentence(reason)} It still names this Run on the ` +
125
133
  `\`${LOCK_BRANCH}\` branch. The next Run on this Host takes it over by itself; for a ` +
126
134
  `Run on any other Host, commit a \`${LOCK_FILE}\` that reads \`${FREE_LOCK}\` to that ` +
127
135
  "branch on GitHub, or ask an Operator to."
@@ -6,9 +6,9 @@
6
6
  * a Stage actually reads: two copies would drift, and the Stage reading the
7
7
  * stale one would be the only place it showed.
8
8
  *
9
- * A module of its own rather than a corner of `notes.ts`, because the Verdict's
9
+ * A module of its own rather than a corner of `notes.ts`, because the verdict's
10
10
  * schema carries this list too and `notes.ts` reaches the templates a Note is
11
- * posted with, which read a Verdict. Only the shape a Stage is asked for lives
11
+ * posted with, which read a verdict. Only the shape a Stage is asked for lives
12
12
  * here, so both schemas can share it without that cycle.
13
13
  *
14
14
  * `ticket` is optional on purpose: a Stage that guesses a number puts the Note
@@ -65,7 +65,7 @@ export const NOTES_LIST_SCHEMA = {
65
65
  * Stages' schema and their prompts use: one declaration, so the two cannot drift.
66
66
  */
67
67
  export const OWN_DEFECT =
68
- "A defect this branch introduced, one that behaves correctly on the Base branch and wrongly here, or one in code this branch added, belongs to this Ticket";
68
+ "A defect this branch introduced, one that behaves correctly on the base branch and wrongly here, or one in code this branch added, belongs to this Ticket";
69
69
 
70
70
  /**
71
71
  * The list as the implement and fix Stages read it: a defect their own branch