ticket-runner 0.6.0 → 0.6.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ko.md +7 -4
- package/README.md +8 -4
- package/docs/templates/operator-skill.md +1 -1
- package/package.json +11 -4
- package/src/adapters/claude-agent-runner.ts +108 -15
- package/src/adapters/exec.ts +35 -6
- package/src/adapters/gh-tracker.ts +10 -46
- package/src/adapters/git-workspace.ts +23 -2
- package/src/adapters/process-tree.ts +227 -0
- package/src/branch.ts +8 -0
- package/src/cli.ts +0 -1
- package/src/config.ts +3 -3
- package/src/conventions.ts +2 -1
- package/src/failing-base.ts +132 -0
- package/src/guards.ts +1 -1
- package/src/host.ts +1 -1
- package/src/log-tail.ts +51 -0
- package/src/note-schema.ts +21 -0
- package/src/notes.ts +8 -4
- package/src/orchestrator.ts +378 -59
- package/src/ports/agent-runner.ts +11 -2
- package/src/ports/tracker.ts +5 -4
- package/src/ports/workspace.ts +24 -2
- package/src/prompts.ts +127 -21
- package/src/remove.ts +3 -8
- package/src/resume.ts +7 -5
- package/src/run.ts +77 -25
- package/src/staleness.ts +9 -2
- package/src/start.ts +5 -1
- package/src/templates.ts +94 -7
- package/src/title.ts +2 -2
|
@@ -25,11 +25,14 @@ export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
|
|
|
25
25
|
export type Effort = (typeof EFFORT_LEVELS)[number];
|
|
26
26
|
|
|
27
27
|
/**
|
|
28
|
-
* Why a Stage did not finish cleanly. `rate-limited`
|
|
29
|
-
* pipeline releases a claim rather than blaming the Ticket for
|
|
28
|
+
* Why a Stage did not finish cleanly. `rate-limited` and `api-error` are singled
|
|
29
|
+
* out because the pipeline releases a claim rather than blaming the Ticket for
|
|
30
|
+
* either: one is the subscription running out of room, the other the API failing
|
|
31
|
+
* on its side after the CLI had given up retrying it.
|
|
30
32
|
*/
|
|
31
33
|
export type StageFailure =
|
|
32
34
|
| "rate-limited"
|
|
35
|
+
| "api-error"
|
|
33
36
|
| "timed-out"
|
|
34
37
|
| "turn-capped"
|
|
35
38
|
| "nonzero-exit"
|
|
@@ -71,6 +74,12 @@ export interface StageResult {
|
|
|
71
74
|
transcriptPath: string;
|
|
72
75
|
turns?: number;
|
|
73
76
|
durationMs: number;
|
|
77
|
+
/**
|
|
78
|
+
* When the subscription rate limit resets, ISO-8601, as the event that
|
|
79
|
+
* rejected the request said. Present only on a `rate-limited` Stage, and only
|
|
80
|
+
* when the CLI said.
|
|
81
|
+
*/
|
|
82
|
+
limitResetsAt?: string;
|
|
74
83
|
}
|
|
75
84
|
|
|
76
85
|
/**
|
package/src/ports/tracker.ts
CHANGED
|
@@ -126,7 +126,7 @@ export interface CreatePullRequest {
|
|
|
126
126
|
|
|
127
127
|
/**
|
|
128
128
|
* The outcome of waiting for a pull request's CI checks. Distinct from a Check,
|
|
129
|
-
* which is a command the pipeline runs itself (
|
|
129
|
+
* which is a command the pipeline runs itself (GLOSSARY.md).
|
|
130
130
|
*
|
|
131
131
|
* `none` means the PR has no checks at all, which `gates.ci` treats as a
|
|
132
132
|
* failure rather than a silent bypass.
|
|
@@ -207,9 +207,10 @@ export interface Tracker {
|
|
|
207
207
|
* Release, named `owner/name`, or nothing where GitHub could not be asked.
|
|
208
208
|
*
|
|
209
209
|
* Named for the tag rather than for the Release, because a Release in this
|
|
210
|
-
* codebase is what a rate
|
|
211
|
-
* published GitHub Release is what makes a tag a
|
|
212
|
-
* which is why it is the question rather than
|
|
210
|
+
* codebase is what a Stage the rate limit or an API failure stopped does to
|
|
211
|
+
* a Ticket (GLOSSARY.md). A published GitHub Release is what makes a tag a
|
|
212
|
+
* Version anybody can install, which is why it is the question rather than
|
|
213
|
+
* the tag alone.
|
|
213
214
|
*
|
|
214
215
|
* The one method of this port that is not about the Target: it is asked about
|
|
215
216
|
* the pipeline's own repository, so a Run and `init` can say that a newer
|
package/src/ports/workspace.ts
CHANGED
|
@@ -45,7 +45,7 @@ export type RebaseState = { resolved: true } | { resolved: false; unresolved: st
|
|
|
45
45
|
* `implemented` one carrying that Stage's work on its branch with no merge
|
|
46
46
|
* behind it.
|
|
47
47
|
*
|
|
48
|
-
* A state of the lifecycle, not a Stage — a Stage is a session (
|
|
48
|
+
* A state of the lifecycle, not a Stage — a Stage is a session (GLOSSARY.md), and
|
|
49
49
|
* what the State records is what the Ticket has, not what was running. Only these
|
|
50
50
|
* two, because everything after the implement Stage — the Checks, the rebase,
|
|
51
51
|
* the pull request, CI and the merge — is re-run from the top by a Run that
|
|
@@ -82,6 +82,13 @@ export interface TicketState {
|
|
|
82
82
|
* when no Stage has answered one, and in State an earlier pipeline left.
|
|
83
83
|
*/
|
|
84
84
|
title?: string;
|
|
85
|
+
/**
|
|
86
|
+
* Whether the Run that takes the Ticket up rebases its branch onto the Base
|
|
87
|
+
* branch before its Checks. Set by a Release over a failing Base branch, so
|
|
88
|
+
* a fix a human has landed there meanwhile reaches the branch; absent
|
|
89
|
+
* otherwise, and in State an earlier pipeline left.
|
|
90
|
+
*/
|
|
91
|
+
rebaseFirst?: boolean;
|
|
85
92
|
/** The Run that last wrote the State, and when — both for a human reading it. */
|
|
86
93
|
runId: string;
|
|
87
94
|
/**
|
|
@@ -228,6 +235,12 @@ export interface Workspace {
|
|
|
228
235
|
* out at `path`. The checkout's own `base` is not moved.
|
|
229
236
|
*/
|
|
230
237
|
createWorktree(worktree: WorktreeRef, base: string): Promise<void>;
|
|
238
|
+
/**
|
|
239
|
+
* Check `commit` out, detached, in a fresh worktree at `path`, where a Check
|
|
240
|
+
* can be run against what a Ticket's branch inherited. A worktree a killed
|
|
241
|
+
* Run left at `path` is replaced: nothing in one is worth keeping.
|
|
242
|
+
*/
|
|
243
|
+
createDetachedWorktree(path: string, commit: string): Promise<void>;
|
|
231
244
|
/**
|
|
232
245
|
* Remove the worktree and delete its branch; a detached worktree, which has
|
|
233
246
|
* none, is only removed.
|
|
@@ -235,7 +248,9 @@ export interface Workspace {
|
|
|
235
248
|
removeWorktree(worktree: { path: string; branch?: string }): Promise<void>;
|
|
236
249
|
/**
|
|
237
250
|
* Every `ticket-<n>` worktree of this repo under the Target's `.worktrees/`,
|
|
238
|
-
* whatever Ticket or Run made it, with what each holds that GitHub lacks
|
|
251
|
+
* whatever Ticket or Run made it, with what each holds that GitHub lacks,
|
|
252
|
+
* and every `base-<commit>` worktree a Run killed mid-Check left there,
|
|
253
|
+
* which holds nothing worth keeping whatever the Check wrote into it.
|
|
239
254
|
*
|
|
240
255
|
* Asked by `ticket-runner remove` alone, which refuses to take out a
|
|
241
256
|
* worktree holding work nothing else has.
|
|
@@ -287,6 +302,13 @@ export interface Workspace {
|
|
|
287
302
|
* answers yes about.
|
|
288
303
|
*/
|
|
289
304
|
hasBranch(branch: string): Promise<boolean>;
|
|
305
|
+
/**
|
|
306
|
+
* The commit the branch checked out at `cwd` inherited from `base`: their
|
|
307
|
+
* merge-base, with `base` as the remote holds it now. The checkout's own
|
|
308
|
+
* `base` may be behind what the branch was made from, and the remote's ahead
|
|
309
|
+
* of it, and neither changes what the branch inherited.
|
|
310
|
+
*/
|
|
311
|
+
mergeBase(cwd: string, base: string): Promise<string>;
|
|
290
312
|
/**
|
|
291
313
|
* Subjects of the commits on `branch` that `base` does not have, oldest first.
|
|
292
314
|
*
|
package/src/prompts.ts
CHANGED
|
@@ -6,6 +6,7 @@
|
|
|
6
6
|
|
|
7
7
|
import { CONVENTIONS_PATH } from "./conventions.js";
|
|
8
8
|
import type { FailureKind } from "./lifecycle.js";
|
|
9
|
+
import { OWN_DEFECT } from "./note-schema.js";
|
|
9
10
|
import { STAGE_ENV_VAR } from "./stage-guard.js";
|
|
10
11
|
import { BRANCH_TITLE } from "./title.js";
|
|
11
12
|
|
|
@@ -47,10 +48,32 @@ function stageBoundary(selfHosted: boolean): string {
|
|
|
47
48
|
* a Stage told only to remove what no commit carries deletes the dependencies
|
|
48
49
|
* it installed for nothing.
|
|
49
50
|
*/
|
|
50
|
-
const FINISH_GUIDANCE = `- Never end your turn while uncommitted work waits on a background task: the session ends with your turn and stops that task, and the work is never committed.
|
|
51
|
+
const FINISH_GUIDANCE = `- Never end your turn while uncommitted work waits on a background task: the session ends with your turn and stops that task, and the work is never committed.
|
|
51
52
|
- Leave the worktree clean: commit your work and remove every untracked file that is not ignored and that no commit carries, test output included. The pipeline refuses a worktree holding changes no commit carries.
|
|
52
53
|
- Keep gitignored files, such as dependencies you installed. The pipeline does not count them against a clean worktree, and deleting them only leaves the next Stage to install them again.`;
|
|
53
54
|
|
|
55
|
+
/** The Check commands as a prompt names them. */
|
|
56
|
+
function checkList(checks: readonly string[]): string {
|
|
57
|
+
return checks.map((command) => `\`${command}\``).join(", ");
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* How the two Stages that write code are told about the Checks, where the
|
|
62
|
+
* config names any; nothing where it names none.
|
|
63
|
+
*
|
|
64
|
+
* The pipeline runs them as soon as the Stage finishes, so a Stage that runs the
|
|
65
|
+
* whole suite while it works, and again after each change, pays for runs the
|
|
66
|
+
* pipeline is about to make anyway: in the logged Runs that was half of an
|
|
67
|
+
* implement Stage's wall clock. One run after its last commit still catches a
|
|
68
|
+
* failure before it spends the Fix budget. implement's comes after the review,
|
|
69
|
+
* because the review changes code in nearly every Stage.
|
|
70
|
+
*/
|
|
71
|
+
function codeChecksLine(checks: readonly string[], afterReview: boolean): string {
|
|
72
|
+
if (checks.length === 0) return "";
|
|
73
|
+
const review = afterReview ? " That one run comes after the review's fixes are committed." : "";
|
|
74
|
+
return `\n- The pipeline runs its Checks as soon as you finish: ${checkList(checks)}. While you work, run only the tests your change touches. Commit, then run the full Checks once, in the foreground, and commit whatever that run makes you change.${review}`;
|
|
75
|
+
}
|
|
76
|
+
|
|
54
77
|
/**
|
|
55
78
|
* How the two Stages that write code are told to title the branch. The title is
|
|
56
79
|
* an answer rather than a commit subject because a commit subject describes its
|
|
@@ -64,15 +87,17 @@ const titleGuidance = (base: string) =>
|
|
|
64
87
|
* Guidance appended to every implement Stage, working around known defects of
|
|
65
88
|
* the `implement` skill in an unattended session.
|
|
66
89
|
*/
|
|
67
|
-
const implementGuidance = (
|
|
90
|
+
const implementGuidance = (
|
|
91
|
+
base: string,
|
|
92
|
+
checks: readonly string[],
|
|
93
|
+
) => `This session is unattended. Follow this guidance as well as the skill's own:
|
|
68
94
|
|
|
69
|
-
- Confirm the Ticket title matches what you are about to build before you start.
|
|
70
95
|
- Make an initial commit before running \`/mattpocock-skills:code-review\`, so the reviewed diff is not empty.
|
|
71
96
|
${titleGuidance(base)}
|
|
72
97
|
- The review the skill asks for is \`/mattpocock-skills:code-review\`. Invoke it by that full name: the short name also matches the CLI's own built-in review skill, which runs neither the Standards review nor the Spec review.
|
|
73
98
|
- Spawn its review sub-agents with \`run_in_background: false\` set explicitly, several in one message so they still run in parallel. Omitting \`run_in_background\` still runs them in the background, and you would then reach your answer before the review has come back.
|
|
74
99
|
- Do not answer the schema until the review has returned and the fixes you take from it are committed. An answer you have already given does not stop you committing: the pipeline waits for this session to exit before it reads the branch.
|
|
75
|
-
- A later answer replaces an earlier one, so if you answer again, repeat every Note you still stand by
|
|
100
|
+
- A later answer replaces an earlier one, so if you answer again, repeat every Note you still stand by.${codeChecksLine(checks, true)}
|
|
76
101
|
${FINISH_GUIDANCE}
|
|
77
102
|
- Do not spawn nested review agents beyond what the skill itself does.
|
|
78
103
|
- Do not open pull requests and do not close the issue; the pipeline does both.
|
|
@@ -83,10 +108,15 @@ ${FINISH_GUIDANCE}
|
|
|
83
108
|
* things this Ticket is not about. Nothing here changes what the Stage is for:
|
|
84
109
|
* it is the channel that stops a finding becoming either scope creep or a lost
|
|
85
110
|
* paragraph in a transcript.
|
|
111
|
+
*
|
|
112
|
+
* A defect the branch itself introduced is the exception, and is said first:
|
|
113
|
+
* "another Ticket" alone left it unowned, and such Notes became bug issues
|
|
114
|
+
* opened after the branch that caused them had merged.
|
|
86
115
|
*/
|
|
87
116
|
const notesGuidance = (standingNotes?: number) => `Notes for other Tickets: if you discover something that belongs to another Ticket, or to no Ticket yet, do not act on it here and do not widen this Ticket to cover it.
|
|
88
117
|
|
|
89
|
-
-
|
|
118
|
+
- ${OWN_DEFECT}: fix it, and do not record it as a Note.
|
|
119
|
+
- Record anything else as a Note instead. Your structured output carries a \`notes\` list, and the pipeline posts each entry where a human will meet it.
|
|
90
120
|
${noteEntryGuidance(standingNotes)}`;
|
|
91
121
|
|
|
92
122
|
/**
|
|
@@ -142,32 +172,87 @@ function standingLine(standingNotes?: number): string {
|
|
|
142
172
|
return `\n- Notes with no Ticket are gathered on #${standingNotes}. Read it first and take what it already records as recorded: write a second Note about a condition it names only when what you saw changes what a reader would do about it, and not when it is another instance of the same thing.`;
|
|
143
173
|
}
|
|
144
174
|
|
|
145
|
-
|
|
175
|
+
/**
|
|
176
|
+
* What makes an unmet criterion one only a human can settle, in the words both
|
|
177
|
+
* the verify and the fix Stage are given.
|
|
178
|
+
*/
|
|
179
|
+
const NEEDS_A_HUMAN =
|
|
180
|
+
"cannot be met without overturning a documented decision or another criterion";
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* The verify Stage's brief. It grades a commit the Checks have just passed, so
|
|
184
|
+
* where the config names any it is told so and told not to run them again: in
|
|
185
|
+
* the logged Runs re-running them was about two fifths of a verify Stage's wall
|
|
186
|
+
* clock, spent proving what the pipeline had already proved.
|
|
187
|
+
*
|
|
188
|
+
* A criterion that collides with a documented decision or another criterion is
|
|
189
|
+
* `unmet` with a human's decision as its evidence, rather than met on a
|
|
190
|
+
* workaround: the fix Stage it buys is told to commit nothing for it, which is
|
|
191
|
+
* what hands the question to a human.
|
|
192
|
+
*/
|
|
193
|
+
const verifyInstructions = (checks: readonly string[]) => `You are the verify Stage of an unattended pipeline. Your job is adversarial: try to prove each Acceptance Criterion is NOT met.
|
|
146
194
|
|
|
147
195
|
- Read the Ticket's Acceptance Criteria from its body and from its comments; the checkbox list may live in either.
|
|
148
196
|
- Work in the checked-out branch, which already contains the implementation.
|
|
149
|
-
- Attempt to falsify every criterion: run the code, run the tests, and write throwaway tests where that is the only way to tell
|
|
197
|
+
- Attempt to falsify every criterion: run the code, run the tests that bear on it, and write throwaway tests where that is the only way to tell.${verifyChecksLine(checks)}
|
|
150
198
|
- Judge the code as it is. Do not fix anything, and never commit, stage or push. Scratch files are fine; the pipeline discards them.
|
|
151
199
|
- Mark a criterion \`unverifiable\` only when no evidence can be gathered, never as a substitute for looking.
|
|
200
|
+
- When a criterion ${NEEDS_A_HUMAN}, mark it \`unmet\` and say in its evidence that a human decision is needed, naming what it collides with. A workaround that sidesteps the collision does not meet it.
|
|
152
201
|
- End by emitting the Verdict: one entry per criterion with its status and the evidence you actually gathered.`;
|
|
153
202
|
|
|
154
|
-
|
|
203
|
+
/** The Checks as the verify Stage is told about them: passed, and not its to run. */
|
|
204
|
+
function verifyChecksLine(checks: readonly string[]): string {
|
|
205
|
+
if (checks.length === 0) return "";
|
|
206
|
+
return `\n- The pipeline's Checks passed on this commit: ${checkList(checks)}. Do not re-run them: grade a criterion that asks only for them from that fact, and spend your turns on targeted tests and probes.`;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* The fix Stage's brief. Sent in for unmet criteria, it is told what to do when
|
|
211
|
+
* one of them needs a human decision: commit nothing, which hands the Ticket to
|
|
212
|
+
* a human with the criteria and their evidence. Left to itself it worked around
|
|
213
|
+
* every such criterion it met, and the verify behind it passed the workaround.
|
|
214
|
+
*/
|
|
215
|
+
const fixInstructions = (
|
|
216
|
+
base: string,
|
|
217
|
+
kind: FailureKind,
|
|
218
|
+
checks: readonly string[],
|
|
219
|
+
) => `You are the fix Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and one gate failed. You are what its fix budget bought, and the budget is spent: a second failure of any kind hands the Ticket to a human.
|
|
155
220
|
|
|
156
221
|
- Commit your fix on the branch you are on, in this worktree. Do not create a branch, do not open pull requests, and do not close the Ticket.
|
|
157
222
|
- Start from the evidence: reproduce the failure, find what actually causes it, and fix that rather than the symptom.
|
|
158
|
-
- Where the failure is an unmet Acceptance Criterion, add the regression test that would have caught it and commit it with the fix
|
|
159
|
-
- Stay inside this Ticket's Acceptance Criteria. Anything else you find belongs to another Ticket, not to this session; record it as a Note rather than mending it
|
|
223
|
+
- Where the failure is an unmet Acceptance Criterion, add the regression test that would have caught it and commit it with the fix.${kind === "unmet-criteria" ? HUMAN_DECISION_LINE : ""}
|
|
224
|
+
- Stay inside this Ticket's Acceptance Criteria and the defects this branch introduced. Anything else you find belongs to another Ticket, not to this session; record it as a Note rather than mending it.${codeChecksLine(checks, false)}
|
|
160
225
|
${FINISH_GUIDANCE}
|
|
161
226
|
- Write commit subjects in the convention \`${CONVENTIONS_PATH}\` states. The pipeline re-runs the Checks and the verify Stage as soon as you finish.
|
|
162
227
|
${titleGuidance(base)}`;
|
|
163
228
|
|
|
164
|
-
|
|
229
|
+
/** What the fix Stage sent in for unmet criteria does with one only a human can settle. */
|
|
230
|
+
const HUMAN_DECISION_LINE = `
|
|
231
|
+
- When any unmet criterion ${NEEDS_A_HUMAN}, as the verify Stage's evidence may already say, commit nothing and say why in your last message. Do not work around it: a fix Stage that commits nothing hands the Ticket to a human, with the unmet criteria and their evidence.`;
|
|
165
232
|
|
|
166
|
-
|
|
233
|
+
/**
|
|
234
|
+
* The conflict Stage's brief. It may reach past the conflicted files only to
|
|
235
|
+
* repair what the merge broke there, such as a name the Base branch renamed:
|
|
236
|
+
* a Stage that left those red would spend the Fix budget on them. Nothing it
|
|
237
|
+
* does may change behaviour the criteria cover, because verify does not run
|
|
238
|
+
* again after it.
|
|
239
|
+
*/
|
|
240
|
+
const conflictInstructions = (
|
|
241
|
+
base: string,
|
|
242
|
+
checks: readonly string[],
|
|
243
|
+
) => `You are the conflict Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and rebasing it onto \`${base}\` stopped on a conflict. That rebase is still in progress in this worktree, and finishing it is the whole of your job.
|
|
244
|
+
|
|
245
|
+
- Resolve every hunk and carry the rebase through to the end; never \`git rebase --abort\`, and never rewind the branch to escape the conflict.
|
|
167
246
|
- Where the two sides are compatible, keep both intents. Where they are not, keep the behaviour this Ticket's Acceptance Criteria ask for, and keep \`${base}\`'s everywhere the Ticket is silent.
|
|
168
|
-
- Resolve, do not redesign. Implement nothing new, and
|
|
247
|
+
- Resolve, do not redesign. Change a file the conflict did not touch only to repair what the merge itself broke, such as a renamed name or a moved field. Implement nothing new, and change no behaviour this Ticket's Acceptance Criteria cover: verify does not grade the branch again after you.
|
|
169
248
|
- Leave no conflict marker behind in any file, committed or not.
|
|
170
|
-
- Do not push, do not open pull requests, and do not close the Ticket
|
|
249
|
+
- Do not push, do not open pull requests, and do not close the Ticket.${conflictChecksLine(checks)}`;
|
|
250
|
+
|
|
251
|
+
/** The Checks as the conflict Stage is told about them: the pipeline's to run in full. */
|
|
252
|
+
function conflictChecksLine(checks: readonly string[]): string {
|
|
253
|
+
if (checks.length === 0) return "";
|
|
254
|
+
return `\n- The pipeline runs its Checks as soon as you finish, and a failure there spends this Ticket's fix budget: ${checkList(checks)}. Run the type checker and the tests covering the files you resolved, not the whole suite.`;
|
|
255
|
+
}
|
|
171
256
|
|
|
172
257
|
/** How the fix prompt announces each kind of failure. */
|
|
173
258
|
const failureSentences = (base: string): Record<FailureKind, string> => ({
|
|
@@ -194,45 +279,56 @@ export function implementPrompt(
|
|
|
194
279
|
base: string,
|
|
195
280
|
extraPrompt: string,
|
|
196
281
|
selfHosted: boolean,
|
|
282
|
+
checks: readonly string[],
|
|
197
283
|
standingNotes?: number,
|
|
198
284
|
): string {
|
|
199
285
|
return sections([
|
|
200
286
|
`/mattpocock-skills:implement ${issueUrl}`,
|
|
201
|
-
implementGuidance(base),
|
|
287
|
+
implementGuidance(base, checks),
|
|
202
288
|
stageBoundary(selfHosted),
|
|
203
289
|
notesGuidance(standingNotes),
|
|
204
290
|
extraPrompt,
|
|
205
291
|
]);
|
|
206
292
|
}
|
|
207
293
|
|
|
208
|
-
/**
|
|
294
|
+
/**
|
|
295
|
+
* A fresh session with no plugin skill, graded against the Verdict schema.
|
|
296
|
+
*
|
|
297
|
+
* `unmetBefore` is the evidence of the Verdict a fix Stage was sent in for, in
|
|
298
|
+
* the same Run; a first verify has none. Without it the verify behind a fix
|
|
299
|
+
* graded the fix on its own terms, and passed a caveat the first one had
|
|
300
|
+
* counted as unmet.
|
|
301
|
+
*/
|
|
209
302
|
export function verifyPrompt(
|
|
210
303
|
issueUrl: string,
|
|
211
304
|
extraPrompt: string,
|
|
212
305
|
selfHosted: boolean,
|
|
306
|
+
checks: readonly string[],
|
|
213
307
|
standingNotes?: number,
|
|
308
|
+
unmetBefore?: string,
|
|
214
309
|
): string {
|
|
215
310
|
return sections([
|
|
216
311
|
`Ticket: ${issueUrl}`,
|
|
217
|
-
|
|
312
|
+
verifyInstructions(checks),
|
|
313
|
+
unmetBefore === undefined ? "" : unmetBeforeSection(unmetBefore),
|
|
218
314
|
stageBoundary(selfHosted),
|
|
219
315
|
verifyNotesGuidance(standingNotes),
|
|
220
316
|
extraPrompt,
|
|
221
317
|
]);
|
|
222
318
|
}
|
|
223
319
|
|
|
224
|
-
/**
|
|
320
|
+
/** A fresh session with no plugin skill, given the conflict git reported. */
|
|
225
321
|
export function conflictPrompt(
|
|
226
322
|
issueUrl: string,
|
|
227
323
|
conflict: string,
|
|
228
324
|
base: string,
|
|
229
325
|
extraPrompt: string,
|
|
230
326
|
selfHosted: boolean,
|
|
327
|
+
checks: readonly string[],
|
|
231
328
|
): string {
|
|
232
329
|
return sections([
|
|
233
|
-
"/mattpocock-skills:resolving-merge-conflicts",
|
|
234
330
|
`Ticket: ${issueUrl}`,
|
|
235
|
-
conflictInstructions(base),
|
|
331
|
+
conflictInstructions(base, checks),
|
|
236
332
|
outputSection("## Where the rebase stopped", conflict),
|
|
237
333
|
stageBoundary(selfHosted),
|
|
238
334
|
extraPrompt,
|
|
@@ -246,11 +342,12 @@ export function fixPrompt(
|
|
|
246
342
|
base: string,
|
|
247
343
|
extraPrompt: string,
|
|
248
344
|
selfHosted: boolean,
|
|
345
|
+
checks: readonly string[],
|
|
249
346
|
standingNotes?: number,
|
|
250
347
|
): string {
|
|
251
348
|
return sections([
|
|
252
349
|
`Ticket: ${issueUrl}`,
|
|
253
|
-
fixInstructions(base),
|
|
350
|
+
fixInstructions(base, failure.kind, checks),
|
|
254
351
|
failureSection(failure, base),
|
|
255
352
|
stageBoundary(selfHosted),
|
|
256
353
|
notesGuidance(standingNotes),
|
|
@@ -267,6 +364,15 @@ function failureSection({ kind, summary, evidence }: FixFailure, base: string):
|
|
|
267
364
|
);
|
|
268
365
|
}
|
|
269
366
|
|
|
367
|
+
/** The unmet criteria a fix Stage was sent in for, and what meeting them now takes. */
|
|
368
|
+
function unmetBeforeSection(evidence: string): string {
|
|
369
|
+
return outputSection(
|
|
370
|
+
"## Judged unmet before the fix",
|
|
371
|
+
evidence,
|
|
372
|
+
"The verify Stage before you judged these criteria unmet, with this evidence, and a fix Stage has worked on the branch since. Such a criterion is met only when that counterexample is gone and the whole criterion holds: a fix that answers the evidence but not the rest of the criterion, or a caveat in place of the behaviour, leaves it `unmet`.",
|
|
373
|
+
);
|
|
374
|
+
}
|
|
375
|
+
|
|
270
376
|
/**
|
|
271
377
|
* A heading, an optional line of prose, and raw command output. The output is
|
|
272
378
|
* fenced because it would otherwise be read as Markdown.
|
package/src/remove.ts
CHANGED
|
@@ -22,6 +22,7 @@ import {
|
|
|
22
22
|
} from "./readiness.js";
|
|
23
23
|
import { STATE_BRANCH } from "./resume.js";
|
|
24
24
|
import { nestedRunRefusal } from "./stage-guard.js";
|
|
25
|
+
import { UPGRADE_COMMAND } from "./staleness.js";
|
|
25
26
|
import { describeHolder } from "./stop.js";
|
|
26
27
|
|
|
27
28
|
/**
|
|
@@ -66,8 +67,6 @@ export interface RemoveOptions {
|
|
|
66
67
|
repoRoot: string;
|
|
67
68
|
/** The Version doing the removing, which the report's first line names (ADR-0007). */
|
|
68
69
|
version: string;
|
|
69
|
-
/** The pipeline's own repository, as `owner/name`, which the upgrade is named from. */
|
|
70
|
-
repository?: string | undefined;
|
|
71
70
|
/** Read before anything is removed, because it names the in-progress label. */
|
|
72
71
|
config: Config;
|
|
73
72
|
tracker: Tracker;
|
|
@@ -151,14 +150,10 @@ export async function removeTarget(options: RemoveOptions): Promise<number> {
|
|
|
151
150
|
// emptied as done.
|
|
152
151
|
const newer = newerSetUp(repoRoot, options.version);
|
|
153
152
|
if (newer !== undefined) {
|
|
154
|
-
const upgrade =
|
|
155
|
-
options.repository === undefined
|
|
156
|
-
? "Upgrade `ticket-runner`"
|
|
157
|
-
: `Upgrade with \`npm install -g "github:${options.repository}#semver:*"\``;
|
|
158
153
|
return refuse(
|
|
159
154
|
`Refusing to remove: ${newer.mark} set this Target up and this is ${newer.own}, so it may` +
|
|
160
|
-
` have left things this Version does not know to remove.
|
|
161
|
-
" `ticket-runner remove` again.",
|
|
155
|
+
` have left things this Version does not know to remove. Upgrade with \`${UPGRADE_COMMAND}\`,` +
|
|
156
|
+
" then run `ticket-runner remove` again.",
|
|
162
157
|
);
|
|
163
158
|
}
|
|
164
159
|
|
package/src/resume.ts
CHANGED
|
@@ -11,10 +11,10 @@ import { REACHED_STATES, type StateFile, type TicketState } from "./ports/worksp
|
|
|
11
11
|
* resuming, so it is written as part of the Claim and rewritten whenever the
|
|
12
12
|
* Ticket reaches something a later Run should not pay for again. Three Runs read
|
|
13
13
|
* it, and what the board says decides which. One finds a Ticket the subscription
|
|
14
|
-
* rate limit released: nothing was wrong with it, so
|
|
15
|
-
* file says where to carry on from. One finds a
|
|
16
|
-
* that claimed it was killed and never released
|
|
17
|
-
* place. One finds a Ticket a human was handed and has relabelled
|
|
14
|
+
* rate limit or a transient API failure released: nothing was wrong with it, so
|
|
15
|
+
* the Claim came off and this file says where to carry on from. One finds a
|
|
16
|
+
* Ticket still claimed — the Run that claimed it was killed and never released
|
|
17
|
+
* anything — and resumes it in place. One finds a Ticket a human was handed and has relabelled
|
|
18
18
|
* `ready-for-agent`, which is the human handing it back. A Ticket still sitting
|
|
19
19
|
* in `ready-for-human` is none of them: its file is inert until a human moves
|
|
20
20
|
* the label or the issue closes.
|
|
@@ -35,6 +35,7 @@ const stateSchema = z.object({
|
|
|
35
35
|
fixUsed: z.boolean(),
|
|
36
36
|
pullRequest: z.number().int().positive().optional(),
|
|
37
37
|
title: z.string().optional(),
|
|
38
|
+
rebaseFirst: z.boolean().optional(),
|
|
38
39
|
runId: z.string(),
|
|
39
40
|
version: z.string().optional(),
|
|
40
41
|
updatedAt: z.string(),
|
|
@@ -79,13 +80,14 @@ export function readStateFile(contents: string, ticket: number): StateFile {
|
|
|
79
80
|
// older pipeline never wrote, are keys that are not there rather than keys
|
|
80
81
|
// holding nothing: the rest of the pipeline reads these with the same
|
|
81
82
|
// distinction.
|
|
82
|
-
const { pullRequest, title, version, ...state } = parsed.data;
|
|
83
|
+
const { pullRequest, title, rebaseFirst, version, ...state } = parsed.data;
|
|
83
84
|
return {
|
|
84
85
|
readable: true,
|
|
85
86
|
state: {
|
|
86
87
|
...state,
|
|
87
88
|
...(pullRequest === undefined ? {} : { pullRequest }),
|
|
88
89
|
...(title === undefined ? {} : { title }),
|
|
90
|
+
...(rebaseFirst === undefined ? {} : { rebaseFirst }),
|
|
89
91
|
...(version === undefined ? {} : { version }),
|
|
90
92
|
},
|
|
91
93
|
};
|
package/src/run.ts
CHANGED
|
@@ -5,6 +5,7 @@ import type { RoutedNote } from "./notes.js";
|
|
|
5
5
|
import { type Pipeline, type TicketOutcome, processTicket } from "./orchestrator.js";
|
|
6
6
|
import { StopSignal, stopLine } from "./stop.js";
|
|
7
7
|
import { holdsClaim, strandedTickets } from "./stranded.js";
|
|
8
|
+
import { RELEASE_WORDS } from "./templates.js";
|
|
8
9
|
|
|
9
10
|
/**
|
|
10
11
|
* What a Run has to show for itself: every Ticket it took, in the order they
|
|
@@ -22,11 +23,13 @@ export interface RunResult {
|
|
|
22
23
|
/**
|
|
23
24
|
* Why a Run ended.
|
|
24
25
|
*
|
|
25
|
-
* A Run that drained the Frontier carries what was left held back; one
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
* was
|
|
29
|
-
*
|
|
26
|
+
* A Run that drained the Frontier carries what was left held back; one a
|
|
27
|
+
* Release stopped carries no candidates, because it ended before it could say
|
|
28
|
+
* one was held back all Run, and the rate limit carries when it resets, where a
|
|
29
|
+
* Stage was told, and a failing Base branch the Check it fails and where; one
|
|
30
|
+
* a human stopped carries the moment it was asked and what it still had in
|
|
31
|
+
* hand. That is why this is a choice rather than a flag beside
|
|
32
|
+
* the list: the stops do not report the same things.
|
|
30
33
|
*/
|
|
31
34
|
export type RunStop =
|
|
32
35
|
| {
|
|
@@ -37,7 +40,20 @@ export type RunStop =
|
|
|
37
40
|
*/
|
|
38
41
|
blocked: number[];
|
|
39
42
|
}
|
|
40
|
-
| {
|
|
43
|
+
| {
|
|
44
|
+
reason: "rate-limited";
|
|
45
|
+
/** When the limit resets, ISO-8601, absent where no Stage was told. */
|
|
46
|
+
resetsAt?: string;
|
|
47
|
+
}
|
|
48
|
+
| { reason: "api-error" }
|
|
49
|
+
| {
|
|
50
|
+
reason: "failing-base";
|
|
51
|
+
baseBranch: string;
|
|
52
|
+
/** The merge-base the Check failed at, in full. */
|
|
53
|
+
commit: string;
|
|
54
|
+
/** The Check command it failed. */
|
|
55
|
+
command: string;
|
|
56
|
+
}
|
|
41
57
|
| {
|
|
42
58
|
reason: "stopped";
|
|
43
59
|
/** When the Stop reached the Run, ISO-8601. */
|
|
@@ -60,11 +76,13 @@ export type RunStop =
|
|
|
60
76
|
* not cost the rest of the night.
|
|
61
77
|
*
|
|
62
78
|
* A Release stops the Run filling Lanes and nothing more. Nothing was wrong with
|
|
63
|
-
* the Ticket — the subscription ran out of room
|
|
64
|
-
*
|
|
65
|
-
*
|
|
66
|
-
*
|
|
67
|
-
*
|
|
79
|
+
* the Ticket — the subscription ran out of room, or the API failed on its own
|
|
80
|
+
* side after the CLI had given up retrying it — so the next one would be stopped
|
|
81
|
+
* the same way, and claiming it would spend a Claim, a worktree and a doomed
|
|
82
|
+
* Stage to learn what the first one already said. The Lanes still busy finish
|
|
83
|
+
* what they hold, and the Run reports what stopped it once the last of them
|
|
84
|
+
* comes back. It does not wait for the limit to reset: a human or an Operator
|
|
85
|
+
* starts the next Run, and the summary says when the limit resets.
|
|
68
86
|
*
|
|
69
87
|
* A Stop is the same shape with a different reason: a human asked for no more
|
|
70
88
|
* Tickets rather than the subscription, so the Lanes busy at that moment finish
|
|
@@ -107,10 +125,11 @@ export async function processRun(
|
|
|
107
125
|
// Lane unblocked on the way is not one the Run was still held up by.
|
|
108
126
|
let blocked: number[] = [];
|
|
109
127
|
// Why this Run stopped, which is also what it reports. Set by whichever of
|
|
110
|
-
// the Release and the Stop came first
|
|
111
|
-
//
|
|
112
|
-
//
|
|
113
|
-
//
|
|
128
|
+
// the Release and the Stop came first: a Stop that arrives after a Release
|
|
129
|
+
// asked for what was already happening, and a Release afterwards stopped
|
|
130
|
+
// nothing that was not stopped already. Only a later rate limit overwrites
|
|
131
|
+
// it, and only where limitOutranks says so. Undefined is a Run still taking
|
|
132
|
+
// Tickets, which is why it doubles as the guard at every refill.
|
|
114
133
|
let runStop: RunStop | undefined;
|
|
115
134
|
// A Frontier the tracker refused to list, kept until the Lanes still busy are
|
|
116
135
|
// back. A Run must not walk away from a Ticket mid-Stage to report that `gh`
|
|
@@ -147,13 +166,14 @@ export async function processRun(
|
|
|
147
166
|
* Put a Ticket in a Lane, and record what came back when it ends.
|
|
148
167
|
*
|
|
149
168
|
* The line about the Run stopping is logged by the Release that stopped it and
|
|
150
|
-
* by no other
|
|
151
|
-
*
|
|
152
|
-
*
|
|
153
|
-
*
|
|
154
|
-
*
|
|
155
|
-
*
|
|
156
|
-
*
|
|
169
|
+
* by no other, even where a later rate limit replaces the API failure it
|
|
170
|
+
* stopped the Run with. The Ticket's own release is already logged where it
|
|
171
|
+
* happened; this says the Run goes no further, so a transcript shows the
|
|
172
|
+
* Frontier was left alone rather than found empty, and a Release into a Run
|
|
173
|
+
* that an earlier Release or a Stop had stopped already claims to have
|
|
174
|
+
* stopped nothing. It leads with the Ticket's number all the same: a
|
|
175
|
+
* transcript of interleaved Lanes must not lose the line that explains why
|
|
176
|
+
* one Lane was the last to be filled.
|
|
157
177
|
*/
|
|
158
178
|
function fillLane(ticket: Taken): void {
|
|
159
179
|
taken.add(ticket.number);
|
|
@@ -162,9 +182,12 @@ export async function processRun(
|
|
|
162
182
|
take(pipeline, ticket).then((outcome) => {
|
|
163
183
|
busy.delete(ticket.number);
|
|
164
184
|
outcomes.push(outcome);
|
|
165
|
-
if (outcome.outcome
|
|
166
|
-
|
|
167
|
-
|
|
185
|
+
if (outcome.outcome !== "released") return;
|
|
186
|
+
if (runStop === undefined) {
|
|
187
|
+
runStop = releaseStop(outcome, pipeline.baseBranch);
|
|
188
|
+
pipeline.log?.(`#${outcome.ticket} stopped the Run · ${RELEASE_WORDS[outcome.cause]}`);
|
|
189
|
+
} else if (outcome.cause === "rate-limited" && limitOutranks(runStop)) {
|
|
190
|
+
runStop = releaseStop(outcome, pipeline.baseBranch);
|
|
168
191
|
}
|
|
169
192
|
}),
|
|
170
193
|
);
|
|
@@ -230,6 +253,35 @@ export async function processRun(
|
|
|
230
253
|
return { outcomes, stop };
|
|
231
254
|
}
|
|
232
255
|
|
|
256
|
+
/**
|
|
257
|
+
* The stop a Release puts on the Run: what released it, when a limit resets,
|
|
258
|
+
* and which Check the Base branch fails.
|
|
259
|
+
*/
|
|
260
|
+
function releaseStop(
|
|
261
|
+
outcome: Extract<TicketOutcome, { outcome: "released" }>,
|
|
262
|
+
baseBranch: string,
|
|
263
|
+
): RunStop {
|
|
264
|
+
if (outcome.cause === "api-error") return { reason: "api-error" };
|
|
265
|
+
if (outcome.failingBase !== undefined) {
|
|
266
|
+
return { reason: "failing-base", baseBranch, ...outcome.failingBase };
|
|
267
|
+
}
|
|
268
|
+
return {
|
|
269
|
+
reason: "rate-limited",
|
|
270
|
+
...(outcome.limitResetsAt === undefined ? {} : { resetsAt: outcome.limitResetsAt }),
|
|
271
|
+
};
|
|
272
|
+
}
|
|
273
|
+
|
|
274
|
+
/**
|
|
275
|
+
* Whether a Ticket the rate limit released after `stop` puts the limit in its
|
|
276
|
+
* place. An API failure says nothing of when the next Run can start, so the
|
|
277
|
+
* limit outranks it; a limit nobody was told the end of is outranked by one a
|
|
278
|
+
* Stage was told. A failing Base branch and a Stop stay whatever comes after
|
|
279
|
+
* them, and so does a limit already told when it resets.
|
|
280
|
+
*/
|
|
281
|
+
function limitOutranks(stop: RunStop): boolean {
|
|
282
|
+
return stop.reason === "api-error" || (stop.reason === "rate-limited" && stop.resetsAt === undefined);
|
|
283
|
+
}
|
|
284
|
+
|
|
233
285
|
/**
|
|
234
286
|
* A Ticket a narrowed Run was given and never met, as the row that says why.
|
|
235
287
|
*
|
package/src/staleness.ts
CHANGED
|
@@ -21,6 +21,12 @@ import type { Tracker } from "./ports/tracker.js";
|
|
|
21
21
|
import { readTargetFile } from "./readiness.js";
|
|
22
22
|
import { isHigher, tagNumber, versionNumber } from "./version-number.js";
|
|
23
23
|
|
|
24
|
+
/**
|
|
25
|
+
* How any copy is upgraded, whatever repository it asks about: every Version
|
|
26
|
+
* is on npm before it has a GitHub Release (ADR-0007).
|
|
27
|
+
*/
|
|
28
|
+
export const UPGRADE_COMMAND = "npm install -g ticket-runner";
|
|
29
|
+
|
|
24
30
|
export interface StalenessQuestion {
|
|
25
31
|
tracker: Tracker;
|
|
26
32
|
/** The Version this copy is, as the CLI resolved it once and handed it down. */
|
|
@@ -39,7 +45,8 @@ export interface StalenessQuestion {
|
|
|
39
45
|
*
|
|
40
46
|
* What has been published as a GitHub Release is the question rather than the
|
|
41
47
|
* highest tag, because a tag a workflow has not finished publishing is not a
|
|
42
|
-
* Version anybody can install yet.
|
|
48
|
+
* Version anybody can install yet. The tag workflow makes the GitHub Release
|
|
49
|
+
* only once npm has the Version, so the answer names one the upgrade finds.
|
|
43
50
|
*/
|
|
44
51
|
export async function newerVersionLine({
|
|
45
52
|
tracker,
|
|
@@ -53,7 +60,7 @@ export async function newerVersionLine({
|
|
|
53
60
|
const published = latest === undefined ? undefined : tagNumber(latest);
|
|
54
61
|
if (published === undefined || !isHigher(published, own)) return undefined;
|
|
55
62
|
|
|
56
|
-
return `A newer Version is out: ${published}, and this is ${own} — upgrade with
|
|
63
|
+
return `A newer Version is out: ${published}, and this is ${own} — upgrade with \`${UPGRADE_COMMAND}\`.`;
|
|
57
64
|
}
|
|
58
65
|
|
|
59
66
|
/**
|