ticket-runner 0.6.1 → 0.6.3
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 +21 -15
- package/README.md +14 -7
- package/docs/templates/operator-skill.md +1 -0
- package/package.json +3 -3
- package/src/adapters/claude-agent-runner.ts +210 -26
- package/src/adapters/exec.ts +52 -6
- package/src/adapters/gh-tracker.ts +10 -46
- package/src/adapters/git-workspace.ts +33 -3
- package/src/adapters/process-tree.ts +227 -0
- package/src/branch.ts +8 -0
- package/src/command-line.ts +18 -1
- package/src/config.ts +3 -3
- package/src/conventions.ts +2 -1
- package/src/credential.ts +75 -0
- 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 +460 -68
- package/src/ports/agent-runner.ts +27 -2
- package/src/ports/tracker.ts +5 -4
- package/src/ports/workspace.ts +38 -2
- package/src/prompts.ts +125 -18
- package/src/readiness.ts +67 -11
- package/src/resume.ts +7 -5
- package/src/run.ts +96 -25
- package/src/start.ts +57 -14
- package/src/templates.ts +134 -15
- package/src/title.ts +2 -2
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
import type { Credential } from "../credential.js";
|
|
2
|
+
|
|
1
3
|
/**
|
|
2
4
|
* One Claude Code session per Stage (ADR-0002).
|
|
3
5
|
*
|
|
@@ -25,11 +27,16 @@ export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
|
|
|
25
27
|
export type Effort = (typeof EFFORT_LEVELS)[number];
|
|
26
28
|
|
|
27
29
|
/**
|
|
28
|
-
* Why a Stage did not finish cleanly. `rate-limited`
|
|
29
|
-
*
|
|
30
|
+
* Why a Stage did not finish cleanly. `rate-limited`, `api-error` and
|
|
31
|
+
* `out-of-budget` are singled out because the pipeline releases a claim rather
|
|
32
|
+
* than blaming the Ticket for any of them: the rate limit, the API failing on
|
|
33
|
+
* its side after the CLI had given up retrying it, and the API key's
|
|
34
|
+
* organization out of credit or its workspace past its spend limit.
|
|
30
35
|
*/
|
|
31
36
|
export type StageFailure =
|
|
32
37
|
| "rate-limited"
|
|
38
|
+
| "api-error"
|
|
39
|
+
| "out-of-budget"
|
|
33
40
|
| "timed-out"
|
|
34
41
|
| "turn-capped"
|
|
35
42
|
| "nonzero-exit"
|
|
@@ -45,6 +52,11 @@ export interface StageRequest {
|
|
|
45
52
|
maxTurns: number;
|
|
46
53
|
maxMinutes: number;
|
|
47
54
|
permissionMode: PermissionMode;
|
|
55
|
+
/**
|
|
56
|
+
* What the session is billed to: the subscription, with the Host's API key
|
|
57
|
+
* kept out of its environment, or that key.
|
|
58
|
+
*/
|
|
59
|
+
credential: Credential;
|
|
48
60
|
/** Where the command line, stdout, stderr and transcript are written. */
|
|
49
61
|
logDir: string;
|
|
50
62
|
/** When set, the Stage is asked for structured output matching this schema. */
|
|
@@ -71,6 +83,19 @@ export interface StageResult {
|
|
|
71
83
|
transcriptPath: string;
|
|
72
84
|
turns?: number;
|
|
73
85
|
durationMs: number;
|
|
86
|
+
/**
|
|
87
|
+
* When the subscription rate limit resets, ISO-8601, as the event that
|
|
88
|
+
* rejected the request said. Present only on a `rate-limited` Stage, and only
|
|
89
|
+
* when the CLI said.
|
|
90
|
+
*/
|
|
91
|
+
limitResetsAt?: string;
|
|
92
|
+
/**
|
|
93
|
+
* What the session said it was billed to, as its `system/init` event's
|
|
94
|
+
* `apiKeySource` names it: `none` for the subscription login,
|
|
95
|
+
* `ANTHROPIC_API_KEY`, `apiKeyHelper` and so on for a key. Absent where the
|
|
96
|
+
* session printed no such event.
|
|
97
|
+
*/
|
|
98
|
+
apiKeySource?: string;
|
|
74
99
|
}
|
|
75
100
|
|
|
76
101
|
/**
|
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
|
*
|
|
@@ -352,6 +374,20 @@ export interface Workspace {
|
|
|
352
374
|
* where the work is once this Host is gone only when that is true.
|
|
353
375
|
*/
|
|
354
376
|
hasRemoteBranch(branch: string): Promise<boolean>;
|
|
377
|
+
/**
|
|
378
|
+
* The remote every branch is fetched from and pushed to, by the name a human
|
|
379
|
+
* types after `git push`, so a message can spell a branch on it as `origin/main`.
|
|
380
|
+
*/
|
|
381
|
+
readonly remote: string;
|
|
382
|
+
/**
|
|
383
|
+
* The contents of `path` at the tip of `branch` as the remote holds it now,
|
|
384
|
+
* which is what every Ticket's worktree is made from, and nothing when the
|
|
385
|
+
* remote has no such branch or the branch no such file.
|
|
386
|
+
*
|
|
387
|
+
* Asked by Target readiness alone, before a Run takes the lock: a file `init`
|
|
388
|
+
* wrote and nobody pushed is in the checkout and in no Stage's worktree.
|
|
389
|
+
*/
|
|
390
|
+
readRemoteFile(branch: string, path: string): Promise<string | undefined>;
|
|
355
391
|
/**
|
|
356
392
|
* Delete `branch` on the remote; the PR is merged, so nothing references it.
|
|
357
393
|
* A branch the remote already deleted, as GitHub does on merge when told to,
|
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.`;
|
|
232
|
+
|
|
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.
|
|
165
244
|
|
|
166
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,27 +279,38 @@ 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,
|
|
@@ -228,10 +324,11 @@ export function conflictPrompt(
|
|
|
228
324
|
base: string,
|
|
229
325
|
extraPrompt: string,
|
|
230
326
|
selfHosted: boolean,
|
|
327
|
+
checks: readonly string[],
|
|
231
328
|
): string {
|
|
232
329
|
return sections([
|
|
233
330
|
`Ticket: ${issueUrl}`,
|
|
234
|
-
conflictInstructions(base),
|
|
331
|
+
conflictInstructions(base, checks),
|
|
235
332
|
outputSection("## Where the rebase stopped", conflict),
|
|
236
333
|
stageBoundary(selfHosted),
|
|
237
334
|
extraPrompt,
|
|
@@ -245,11 +342,12 @@ export function fixPrompt(
|
|
|
245
342
|
base: string,
|
|
246
343
|
extraPrompt: string,
|
|
247
344
|
selfHosted: boolean,
|
|
345
|
+
checks: readonly string[],
|
|
248
346
|
standingNotes?: number,
|
|
249
347
|
): string {
|
|
250
348
|
return sections([
|
|
251
349
|
`Ticket: ${issueUrl}`,
|
|
252
|
-
fixInstructions(base),
|
|
350
|
+
fixInstructions(base, failure.kind, checks),
|
|
253
351
|
failureSection(failure, base),
|
|
254
352
|
stageBoundary(selfHosted),
|
|
255
353
|
notesGuidance(standingNotes),
|
|
@@ -266,6 +364,15 @@ function failureSection({ kind, summary, evidence }: FixFailure, base: string):
|
|
|
266
364
|
);
|
|
267
365
|
}
|
|
268
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
|
+
|
|
269
376
|
/**
|
|
270
377
|
* A heading, an optional line of prose, and raw command output. The output is
|
|
271
378
|
* fenced because it would otherwise be read as Markdown.
|
package/src/readiness.ts
CHANGED
|
@@ -4,6 +4,7 @@ import type { Labels } from "./config.js";
|
|
|
4
4
|
import { CLAUDE_SECTION, CONVENTIONS_PATH, conventionsMark } from "./conventions.js";
|
|
5
5
|
import { OPERATOR_SKILL_PATH } from "./operator-skill.js";
|
|
6
6
|
import type { Authentication, Tracker } from "./ports/tracker.js";
|
|
7
|
+
import type { Workspace } from "./ports/workspace.js";
|
|
7
8
|
|
|
8
9
|
/**
|
|
9
10
|
* What `ticket-runner init` must have left in a Target before a Run may start.
|
|
@@ -22,17 +23,26 @@ import type { Authentication, Tracker } from "./ports/tracker.js";
|
|
|
22
23
|
* Version it names: an Operator installs the pipeline a cloud Host runs at that
|
|
23
24
|
* Version, and a Target without one leaves it guessing (ADR-0008).
|
|
24
25
|
*
|
|
25
|
-
* The
|
|
26
|
+
* The checkout's files are read here rather than through a port, which every
|
|
26
27
|
* external effect of a Run goes through. What a port buys is a fake to drive the
|
|
27
|
-
* state machine with, and there is no state machine here:
|
|
28
|
+
* state machine with, and there is no state machine here: these are questions
|
|
28
29
|
* asked of a directory before a Run exists, and the answers are already driven
|
|
29
30
|
* from a temporary repository root, which is how the local state under
|
|
30
|
-
* `.ticket-runner/` is tested too (ADR-0004).
|
|
31
|
-
*
|
|
32
|
-
*
|
|
31
|
+
* `.ticket-runner/` is tested too (ADR-0004).
|
|
32
|
+
*
|
|
33
|
+
* The same files on the remote's Base branch are the one exception, read
|
|
34
|
+
* through `Workspace` like every other question about the remote: every
|
|
35
|
+
* Ticket's worktree is made from that branch, so a file `init` wrote and nobody
|
|
36
|
+
* pushed is in the checkout and in no Stage's worktree. The conventions
|
|
37
|
+
* document, the `CLAUDE.md` pointer and the Operator's skill are asked of it
|
|
38
|
+
* the same way they are asked of the checkout. The gitignore lines are not:
|
|
39
|
+
* the directories they cover exist only in the main checkout, and only its
|
|
40
|
+
* copy takes effect there.
|
|
33
41
|
*
|
|
34
42
|
* Every item is asked on every Host, the cloud's own needs included, so a
|
|
35
|
-
* Target a workstation accepts is never one a cloud Run then refuses.
|
|
43
|
+
* Target a workstation accepts is never one a cloud Run then refuses. A cloud
|
|
44
|
+
* Host's checkout is a clone of the remote, so there the remote's answers are
|
|
45
|
+
* the checkout's.
|
|
36
46
|
*/
|
|
37
47
|
|
|
38
48
|
/** The file every agent session in a Target reads first. */
|
|
@@ -148,6 +158,10 @@ export interface ReadinessOptions {
|
|
|
148
158
|
* is refused without a network call at all. Whether `gh` is there to ask comes
|
|
149
159
|
* next, so a Host without it is refused in words rather than with the spawn
|
|
150
160
|
* error the first label lookup would crash on.
|
|
161
|
+
*
|
|
162
|
+
* What the remote's Base branch lacks is asked after all of these, by
|
|
163
|
+
* {@link unpushedRefusal}, once the Run has resolved which branch that is: the
|
|
164
|
+
* lookup may ask GitHub, which only a `gh` that runs can.
|
|
151
165
|
*/
|
|
152
166
|
export async function readinessRefusal({
|
|
153
167
|
repoRoot,
|
|
@@ -155,7 +169,7 @@ export async function readinessRefusal({
|
|
|
155
169
|
tracker,
|
|
156
170
|
}: ReadinessOptions): Promise<string | undefined> {
|
|
157
171
|
const missing =
|
|
158
|
-
missingFileMessage(repoRoot) ??
|
|
172
|
+
(await missingFileMessage(repoRoot)) ??
|
|
159
173
|
(await missingGhMessage(tracker)) ??
|
|
160
174
|
(await missingLabelMessage(tracker, labels)) ??
|
|
161
175
|
(await missingBranchDeletionMessage(tracker));
|
|
@@ -168,14 +182,56 @@ export async function readinessRefusal({
|
|
|
168
182
|
].join(" ");
|
|
169
183
|
}
|
|
170
184
|
|
|
185
|
+
export interface UnpushedOptions {
|
|
186
|
+
workspace: Pick<Workspace, "remote" | "readRemoteFile">;
|
|
187
|
+
/** The Run's Base branch, resolved once and carried on into the Run. */
|
|
188
|
+
baseBranch: string;
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
/**
|
|
192
|
+
* The message a Run is refused with when the remote's Base branch lacks a file
|
|
193
|
+
* the checkout has, and nothing when it has them all.
|
|
194
|
+
*
|
|
195
|
+
* Asked once {@link readinessRefusal} has found nothing missing, so a Target
|
|
196
|
+
* that never ran `init` is told to run it and only one that did is told to
|
|
197
|
+
* push. A Base branch the remote does not have lacks every file. The remedy is
|
|
198
|
+
* a commit and a push, which `init` leaves to the human, so this names no
|
|
199
|
+
* command of the pipeline's.
|
|
200
|
+
*/
|
|
201
|
+
export async function unpushedRefusal({
|
|
202
|
+
workspace,
|
|
203
|
+
baseBranch,
|
|
204
|
+
}: UnpushedOptions): Promise<string | undefined> {
|
|
205
|
+
const remoteBase = `${workspace.remote}/${baseBranch}`;
|
|
206
|
+
const missing = await missingItemMessage((path) => workspace.readRemoteFile(baseBranch, path));
|
|
207
|
+
if (missing === undefined) return undefined;
|
|
208
|
+
|
|
209
|
+
return [
|
|
210
|
+
`This Target's \`${remoteBase}\` is not set up: ${missing}.`,
|
|
211
|
+
`Every Ticket's worktree is made from \`${remoteBase}\`, not from this checkout:`,
|
|
212
|
+
"commit and push what `init` wrote there, then start again.",
|
|
213
|
+
].join(" ");
|
|
214
|
+
}
|
|
215
|
+
|
|
171
216
|
/** Names the first thing `init` writes into a Target that this one does not have. */
|
|
172
|
-
function missingFileMessage(repoRoot: string): string | undefined {
|
|
217
|
+
async function missingFileMessage(repoRoot: string): Promise<string | undefined> {
|
|
173
218
|
const [unignored] = missingIgnoreLines(repoRoot);
|
|
174
219
|
if (unignored !== undefined) {
|
|
175
220
|
return `\`.gitignore\` does not ignore \`${unignored.line}\``;
|
|
176
221
|
}
|
|
177
222
|
|
|
178
|
-
|
|
223
|
+
return missingItemMessage(async (path) => readTargetFile(join(repoRoot, path)));
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/**
|
|
227
|
+
* Names the first of the items both the checkout and the remote's Base branch
|
|
228
|
+
* must carry that `read` does not find, asking each the same question in both
|
|
229
|
+
* places. Where it was asked is the refusal's to say.
|
|
230
|
+
*/
|
|
231
|
+
async function missingItemMessage(
|
|
232
|
+
read: (path: string) => Promise<string | undefined>,
|
|
233
|
+
): Promise<string | undefined> {
|
|
234
|
+
const conventions = await read(CONVENTIONS_PATH);
|
|
179
235
|
if (conventions === undefined) {
|
|
180
236
|
return `\`${CONVENTIONS_PATH}\` is not there`;
|
|
181
237
|
}
|
|
@@ -183,13 +239,13 @@ function missingFileMessage(repoRoot: string): string | undefined {
|
|
|
183
239
|
return `\`${CONVENTIONS_PATH}\` carries no Version`;
|
|
184
240
|
}
|
|
185
241
|
|
|
186
|
-
if (!hasClaudePointer(
|
|
242
|
+
if (!hasClaudePointer(await read(CLAUDE_FILENAME))) {
|
|
187
243
|
return `\`${CLAUDE_FILENAME}\` does not point at \`${CONVENTIONS_PATH}\``;
|
|
188
244
|
}
|
|
189
245
|
|
|
190
246
|
// Asked of a workstation too, though only a cloud session reads it: a Target
|
|
191
247
|
// a local Run accepts is then one the app can run as well (ADR-0008).
|
|
192
|
-
if (
|
|
248
|
+
if ((await read(OPERATOR_SKILL_PATH)) === undefined) {
|
|
193
249
|
return `the Operator's skill \`${OPERATOR_SKILL_PATH}\` is not there`;
|
|
194
250
|
}
|
|
195
251
|
|
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
|
};
|