ticket-runner 0.6.5 → 0.6.6
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 +1 -1
- package/README.md +1 -1
- package/docs/templates/operator-skill.md +76 -11
- package/package.json +1 -1
- package/src/acceptance-criteria.ts +97 -0
- package/src/adapters/claude-agent-runner.ts +2 -2
- package/src/adapters/exec.ts +15 -2
- package/src/adapters/gh-tracker.ts +259 -43
- package/src/adapters/git-workspace.ts +15 -2
- package/src/config.ts +18 -0
- package/src/conventions.ts +3 -3
- package/src/criteria.ts +81 -123
- package/src/guards.ts +19 -4
- package/src/note-schema.ts +12 -9
- package/src/notes.ts +11 -1
- package/src/orchestrator.ts +606 -163
- package/src/outside-fault.ts +103 -0
- package/src/ports/tracker.ts +16 -3
- package/src/ports/workspace.ts +29 -2
- package/src/progress.ts +40 -5
- package/src/prompts.ts +184 -19
- package/src/resume.ts +17 -9
- package/src/run.ts +50 -8
- package/src/start.ts +12 -4
- package/src/templates.ts +257 -89
- package/src/title.ts +73 -11
- package/src/transcript-home.ts +49 -0
- package/src/verdict.ts +130 -25
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A fault of GitHub's or of the Host's, which says nothing about the Ticket.
|
|
3
|
+
*
|
|
4
|
+
* Read off what `gh` and git print, since that is all either says about why it
|
|
5
|
+
* failed: GitHub answering with a 5xx status or with a response that is not
|
|
6
|
+
* complete JSON, and git unable to connect to or authenticate with the remote.
|
|
7
|
+
* A Ticket that meets one is released rather than handed off, as over a
|
|
8
|
+
* failing base branch: a human relabelling it would change nothing in its work,
|
|
9
|
+
* and every Ticket behind it would meet the same fault.
|
|
10
|
+
*
|
|
11
|
+
* Everything else a command prints is the Ticket's to answer for, as before: a
|
|
12
|
+
* GitHub 4xx, and a git failure that persists, such as a pull refused over a
|
|
13
|
+
* base branch that has really diverged.
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
/** Whose side the fault is on: GitHub's, or the git remote's. */
|
|
17
|
+
export type FaultSide = "github" | "remote";
|
|
18
|
+
|
|
19
|
+
/** A command that failed for a fault outside the Ticket, and how it failed. */
|
|
20
|
+
export class OutsideFault extends Error {
|
|
21
|
+
constructor(
|
|
22
|
+
readonly side: FaultSide,
|
|
23
|
+
/** The command as a human would type it, on one line. */
|
|
24
|
+
readonly command: string,
|
|
25
|
+
/** The first line of what it printed, which is what the Run's last line quotes. */
|
|
26
|
+
readonly line: string,
|
|
27
|
+
message: string,
|
|
28
|
+
) {
|
|
29
|
+
super(message);
|
|
30
|
+
this.name = "OutsideFault";
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* GitHub failing on its own side: a 5xx status as `gh` reports it, and a
|
|
36
|
+
* response `gh` could not read as JSON, which is how a gateway that cut the
|
|
37
|
+
* answer short shows.
|
|
38
|
+
*/
|
|
39
|
+
const GITHUB_FAULTS = [
|
|
40
|
+
/\bHTTP 5\d\d\b/,
|
|
41
|
+
/unexpected end of JSON input/i,
|
|
42
|
+
/invalid character .{1,12} looking for beginning of value/,
|
|
43
|
+
];
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* git unable to reach the remote or to be let in. `Could not read from remote
|
|
47
|
+
* repository` is not among them: git says it after a repository that does not
|
|
48
|
+
* exist as well, which no wait mends.
|
|
49
|
+
*/
|
|
50
|
+
const REMOTE_FAULTS = [
|
|
51
|
+
/Permission denied \(publickey/i,
|
|
52
|
+
/Could not resolve host/i,
|
|
53
|
+
/Authentication failed/i,
|
|
54
|
+
/could not read (Username|Password) for/i,
|
|
55
|
+
/Connection refused/i,
|
|
56
|
+
/Connection timed out/i,
|
|
57
|
+
/Operation timed out/i,
|
|
58
|
+
/Connection reset by peer/i,
|
|
59
|
+
/Failed to connect to/i,
|
|
60
|
+
];
|
|
61
|
+
|
|
62
|
+
/** The remote answering with a 5xx, which a push it failed on reports too. */
|
|
63
|
+
const REMOTE_5XX = [/The requested URL returned error: 5\d\d/, /RPC failed; HTTP 5\d\d/];
|
|
64
|
+
|
|
65
|
+
/** Whether `gh` printed a fault of GitHub's own. */
|
|
66
|
+
export function isGitHubFault(output: string): boolean {
|
|
67
|
+
return GITHUB_FAULTS.some((pattern) => pattern.test(output));
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* A push the remote, or a hook before it, refused. A connection that cannot
|
|
72
|
+
* be made fails before git gets that far, so the words of one printed beside
|
|
73
|
+
* it are a pre-push hook's own output, such as a test that could not reach
|
|
74
|
+
* its database, and no fault of the remote's.
|
|
75
|
+
*/
|
|
76
|
+
const PUSH_REFUSED = /failed to push some refs/;
|
|
77
|
+
|
|
78
|
+
/** Whether git printed that it could not connect to or authenticate with the remote. */
|
|
79
|
+
export function isRemoteFault(output: string): boolean {
|
|
80
|
+
if (REMOTE_5XX.some((pattern) => pattern.test(output))) return true;
|
|
81
|
+
return !PUSH_REFUSED.test(output) && REMOTE_FAULTS.some((pattern) => pattern.test(output));
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Whose fault a failed `command` is, from what it printed, or nothing when it
|
|
86
|
+
* is no fault outside the Ticket. Only `gh` speaks for GitHub and only git for
|
|
87
|
+
* the remote, so a Check that happens to print the same words is never one.
|
|
88
|
+
*/
|
|
89
|
+
export function faultSide(command: string, output: string): FaultSide | undefined {
|
|
90
|
+
if (command === "gh" && isGitHubFault(output)) return "github";
|
|
91
|
+
if (command === "git" && isRemoteFault(output)) return "remote";
|
|
92
|
+
return undefined;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
/** The first line of `output` with anything on it, trimmed; empty when there is none. */
|
|
96
|
+
export function firstLine(output: string): string {
|
|
97
|
+
return (
|
|
98
|
+
output
|
|
99
|
+
.split(/\r?\n/)
|
|
100
|
+
.map((line) => line.trim())
|
|
101
|
+
.find((line) => line !== "") ?? ""
|
|
102
|
+
);
|
|
103
|
+
}
|
package/src/ports/tracker.ts
CHANGED
|
@@ -173,6 +173,9 @@ export type Authentication = "authenticated" | "unauthenticated" | "not-installe
|
|
|
173
173
|
*/
|
|
174
174
|
export type NumberKind = "issue" | "pull-request" | "nothing";
|
|
175
175
|
|
|
176
|
+
/** Whether anybody may read a repository, or only those it is shared with. */
|
|
177
|
+
export type Visibility = "public" | "private";
|
|
178
|
+
|
|
176
179
|
export interface Tracker {
|
|
177
180
|
/**
|
|
178
181
|
* Whether `gh` can speak to GitHub as somebody, and if not, whether it is
|
|
@@ -203,6 +206,16 @@ export interface Tracker {
|
|
|
203
206
|
* an answer: a Target this cannot name is treated as any other Target.
|
|
204
207
|
*/
|
|
205
208
|
repository(): Promise<string | undefined>;
|
|
209
|
+
/**
|
|
210
|
+
* Whether anybody may read the Target, or nothing where GitHub could not be
|
|
211
|
+
* asked. An `internal` repository, readable only inside its enterprise, is
|
|
212
|
+
* private here.
|
|
213
|
+
*
|
|
214
|
+
* Asked once at the start of a Run, and only where the config does not say
|
|
215
|
+
* whether a handed-off Ticket's transcripts are kept on the remote. Nothing
|
|
216
|
+
* is refused over the answer: no answer counts as public.
|
|
217
|
+
*/
|
|
218
|
+
visibility(): Promise<Visibility | undefined>;
|
|
206
219
|
/**
|
|
207
220
|
* The tag of the highest version `repository` has published as a GitHub
|
|
208
221
|
* Release, named `owner/name`, or nothing where GitHub could not be asked.
|
|
@@ -318,9 +331,9 @@ export interface Tracker {
|
|
|
318
331
|
/**
|
|
319
332
|
* Replace the body of an open pull request.
|
|
320
333
|
*
|
|
321
|
-
* A Ticket that spends its fix budget
|
|
322
|
-
* the
|
|
323
|
-
*
|
|
334
|
+
* A Ticket that spends its fix budget comes back to its pull request, and
|
|
335
|
+
* the body is written from the latest body a Stage answered; without this it
|
|
336
|
+
* would keep describing the branch before the fix Stage changed it.
|
|
324
337
|
*/
|
|
325
338
|
updatePullRequestBody(number: number, body: string): Promise<void>;
|
|
326
339
|
/**
|
package/src/ports/workspace.ts
CHANGED
|
@@ -82,6 +82,16 @@ 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
|
+
* The latest pull request body, problem and solution a Stage answered for
|
|
87
|
+
* the whole branch, which the pull request body and the squash commit are
|
|
88
|
+
* written from. Without them a Run that resumes after the Stage that wrote
|
|
89
|
+
* them would publish `Closes #<n>` alone. Each is absent when no Stage has
|
|
90
|
+
* answered it, and in state an earlier pipeline left.
|
|
91
|
+
*/
|
|
92
|
+
body?: string;
|
|
93
|
+
problem?: string;
|
|
94
|
+
solution?: string;
|
|
85
95
|
/**
|
|
86
96
|
* Whether the Run that takes the Ticket up rebases its branch onto the Base
|
|
87
97
|
* branch before its Checks. Set by a Release over a failing base branch, so
|
|
@@ -313,8 +323,8 @@ export interface Workspace {
|
|
|
313
323
|
* Subjects of the commits on `branch` that `base` does not have, oldest first.
|
|
314
324
|
*
|
|
315
325
|
* The order is the port's promise, not an accident of git's default: the
|
|
316
|
-
* first subject names the whole Ticket, and
|
|
317
|
-
* in the order they were written.
|
|
326
|
+
* first subject names the whole Ticket, and a squash commit with no solution
|
|
327
|
+
* answered lists them in the order they were written.
|
|
318
328
|
*/
|
|
319
329
|
commitSubjects(branch: string, base: string): Promise<string[]>;
|
|
320
330
|
/**
|
|
@@ -395,6 +405,15 @@ export interface Workspace {
|
|
|
395
405
|
* counts as deleted without a delete being sent, which a cloud Host could not.
|
|
396
406
|
*/
|
|
397
407
|
deleteRemoteBranch(branch: string): Promise<void>;
|
|
408
|
+
/**
|
|
409
|
+
* Fetch the whole history of a clone that is shallow, and say whether it was.
|
|
410
|
+
*
|
|
411
|
+
* Asked once before a Run claims anything. A shallow clone cannot show that
|
|
412
|
+
* the remote's base branch is a fast-forward of a local one left on an
|
|
413
|
+
* older commit, so every {@link pullBase} on it is refused, and every Ticket
|
|
414
|
+
* handed off at the rebase.
|
|
415
|
+
*/
|
|
416
|
+
unshallow(): Promise<boolean>;
|
|
398
417
|
/**
|
|
399
418
|
* Fast-forward the main checkout's `base` to the remote: at the door of the
|
|
400
419
|
* Landing, so the rebase is onto what the merge will land on, and after a
|
|
@@ -433,6 +452,14 @@ export interface Workspace {
|
|
|
433
452
|
* the Run left none for the Ticket.
|
|
434
453
|
*/
|
|
435
454
|
keepTranscripts(ticket: number, runId: string): Promise<KeptTranscripts | undefined>;
|
|
455
|
+
/**
|
|
456
|
+
* Where on this Host Run `runId` wrote the files {@link keepTranscripts}
|
|
457
|
+
* would keep for `ticket`, as a `/`-separated directory relative to the
|
|
458
|
+
* checkout and ending in `/`, or nothing when it wrote none. Asked of a
|
|
459
|
+
* hand-off whose Run keeps transcripts off the remote: relative, so a public
|
|
460
|
+
* comment naming it does not publish the Host's home path.
|
|
461
|
+
*/
|
|
462
|
+
transcriptsOnHost(ticket: number, runId: string): Promise<string | undefined>;
|
|
436
463
|
/**
|
|
437
464
|
* Take the Run lock for this Run, or say what stands in the way. Taking it is
|
|
438
465
|
* the whole of the mutual exclusion: two Runs never both get `taken`, on one
|
package/src/progress.ts
CHANGED
|
@@ -26,14 +26,19 @@ export const PROGRESS_MARKER = "<!-- ticket-runner:progress -->";
|
|
|
26
26
|
/**
|
|
27
27
|
* What a row is about. Named after the lifecycle step rather than the Stage, for
|
|
28
28
|
* the reason `FailurePoint` in `lifecycle.ts` is: the Checks, CI and the merge
|
|
29
|
-
* each earn a row, and none of them is an agent session.
|
|
29
|
+
* each earn a row, and none of them is an agent session. `setup`, `rebase` and
|
|
30
|
+
* `pr` earn one only where GitHub or the remote failing on its own side
|
|
31
|
+
* released the Ticket there.
|
|
30
32
|
*/
|
|
31
33
|
export type ProgressPoint =
|
|
34
|
+
| "setup"
|
|
32
35
|
| "implement"
|
|
33
36
|
| "checks"
|
|
34
37
|
| "verify"
|
|
35
38
|
| "fix"
|
|
36
39
|
| "conflict"
|
|
40
|
+
| "rebase"
|
|
41
|
+
| "pr"
|
|
37
42
|
| "ci"
|
|
38
43
|
| "merge";
|
|
39
44
|
|
|
@@ -88,7 +93,7 @@ export function progressComment({
|
|
|
88
93
|
"|---|---|---|---|",
|
|
89
94
|
...rows.map(
|
|
90
95
|
(row) =>
|
|
91
|
-
`| ${row.point} | ${cell(row.outcome)} | ${count(row.turns)} | ${
|
|
96
|
+
`| ${row.point} | ${cell(row.outcome)} | ${count(row.turns)} | ${duration(row.durationMs)} |`,
|
|
92
97
|
),
|
|
93
98
|
"",
|
|
94
99
|
].join("\n");
|
|
@@ -136,9 +141,20 @@ function count(turns: number | undefined): string {
|
|
|
136
141
|
return turns === undefined ? NO_ANSWER : String(turns);
|
|
137
142
|
}
|
|
138
143
|
|
|
139
|
-
/**
|
|
140
|
-
|
|
141
|
-
|
|
144
|
+
/**
|
|
145
|
+
* A duration as GitHub Actions writes one on a pull request's checks: `40s`,
|
|
146
|
+
* `1m 5s`, `3h 15m 35s`. The template says why. A clock stepped back mid-Stage
|
|
147
|
+
* reads `0s` rather than a negative.
|
|
148
|
+
*/
|
|
149
|
+
function duration(durationMs: number | undefined): string {
|
|
150
|
+
if (durationMs === undefined) return NO_ANSWER;
|
|
151
|
+
const total = Math.max(0, Math.round(durationMs / 1000));
|
|
152
|
+
const hours = Math.floor(total / 3600);
|
|
153
|
+
const minutes = Math.floor((total % 3600) / 60);
|
|
154
|
+
const seconds = total % 60;
|
|
155
|
+
if (hours > 0) return `${hours}h ${minutes}m ${seconds}s`;
|
|
156
|
+
if (minutes > 0) return `${minutes}m ${seconds}s`;
|
|
157
|
+
return `${seconds}s`;
|
|
142
158
|
}
|
|
143
159
|
|
|
144
160
|
/**
|
|
@@ -181,6 +197,8 @@ export class Progress {
|
|
|
181
197
|
private readonly earlier: string;
|
|
182
198
|
/** Set when reporting again could only mean a second comment, never an edit. */
|
|
183
199
|
private stopped = false;
|
|
200
|
+
/** Set while the comment on the Ticket lacks a row the last write failed to carry. */
|
|
201
|
+
private behind = false;
|
|
184
202
|
|
|
185
203
|
constructor(private readonly options: ProgressOptions) {
|
|
186
204
|
// A Ticket taken back from a human keeps the comment that human read: a
|
|
@@ -198,6 +216,20 @@ export class Progress {
|
|
|
198
216
|
/** Append a row, and show it on the Ticket. */
|
|
199
217
|
async record(row: ProgressRow): Promise<void> {
|
|
200
218
|
this.rows.push(row);
|
|
219
|
+
await this.write();
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/**
|
|
223
|
+
* Write the comment once more if its last write failed, so a row GitHub
|
|
224
|
+
* refused mid-Ticket is on the Ticket by the time it ends. Called once the
|
|
225
|
+
* Ticket merges, is handed off or is released: no later write of the Run
|
|
226
|
+
* would carry it otherwise.
|
|
227
|
+
*/
|
|
228
|
+
async settle(): Promise<void> {
|
|
229
|
+
if (this.behind) await this.write();
|
|
230
|
+
}
|
|
231
|
+
|
|
232
|
+
private async write(): Promise<void> {
|
|
201
233
|
if (this.stopped) return;
|
|
202
234
|
|
|
203
235
|
const { tracker, ticket, version, runId, branch } = this.options;
|
|
@@ -213,9 +245,11 @@ export class Progress {
|
|
|
213
245
|
const id = this.comment?.id;
|
|
214
246
|
if (id !== undefined) {
|
|
215
247
|
await tracker.updateComment(id, body);
|
|
248
|
+
this.behind = false;
|
|
216
249
|
return;
|
|
217
250
|
}
|
|
218
251
|
this.comment = await tracker.comment(ticket, body);
|
|
252
|
+
this.behind = false;
|
|
219
253
|
if (this.comment.id === undefined) {
|
|
220
254
|
// A comment nothing can edit is a comment per Stage, which is the noise
|
|
221
255
|
// this whole table exists to avoid. One row is better than a dozen.
|
|
@@ -223,6 +257,7 @@ export class Progress {
|
|
|
223
257
|
this.options.log?.(`#${ticket} posted a progress comment it cannot edit again`);
|
|
224
258
|
}
|
|
225
259
|
} catch (error) {
|
|
260
|
+
this.behind = true;
|
|
226
261
|
this.options.log?.(
|
|
227
262
|
`#${ticket} could not write the progress comment: ${(error as Error).message}`,
|
|
228
263
|
);
|
package/src/prompts.ts
CHANGED
|
@@ -4,10 +4,12 @@
|
|
|
4
4
|
* (ADR-0002).
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
|
+
import type { ListedCriterion } from "./acceptance-criteria.js";
|
|
7
8
|
import type { FailureKind } from "./lifecycle.js";
|
|
8
|
-
import { OWN_DEFECT } from "./note-schema.js";
|
|
9
|
+
import { BRANCH_DEFECT, OWN_DEFECT } from "./note-schema.js";
|
|
10
|
+
import { NOTE_PARTS, type WrittenNote } from "./notes.js";
|
|
9
11
|
import { STAGE_ENV_VAR } from "./stage-guard.js";
|
|
10
|
-
import { BRANCH_TITLE, SUBJECT_SHAPE } from "./title.js";
|
|
12
|
+
import { BRANCH_PROSE_FIELDS, BRANCH_TITLE, type BranchProse, SUBJECT_SHAPE } from "./title.js";
|
|
11
13
|
|
|
12
14
|
/**
|
|
13
15
|
* Appended to every Stage prompt, the fix Stage included, in every Target. The
|
|
@@ -88,6 +90,50 @@ function codeChecksLine(checks: readonly string[], afterReview: boolean): string
|
|
|
88
90
|
const titleGuidance = (base: string) =>
|
|
89
91
|
`- Answer a \`title\` beside your Notes: ${BRANCH_TITLE}, in the \`${SUBJECT_SHAPE}\` shape and without the \`(#<n>)\`. It titles the pull request and the squash commit on \`${base}\`, so each commit subject describes only its own commit.`;
|
|
90
92
|
|
|
93
|
+
/**
|
|
94
|
+
* Where the pull request body's shape comes from. A Target's own rules come
|
|
95
|
+
* first: a Stage reads its instructions anyway, so ignoring them would leave it
|
|
96
|
+
* two conflicting orders. The `pr` skill is named by its full name, because a
|
|
97
|
+
* short name may match a skill of the Target's own.
|
|
98
|
+
*/
|
|
99
|
+
const BODY_SHAPE =
|
|
100
|
+
"in the shape this repository's contributing guide or its `.github/PULL_REQUEST_TEMPLATE.md` sets, when either sets a pull request body's sections or content beyond the `Closes` line; where neither does, invoke `/mattpocock-skills:pr` by that full name and write it in that skill's shape";
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* How the problem and the solution read. The shape is stated here rather than
|
|
104
|
+
* pointed at, because the skill it comes from is a personal one, not part of
|
|
105
|
+
* the plugin a Target installs.
|
|
106
|
+
*/
|
|
107
|
+
const PROSE_SHAPE =
|
|
108
|
+
"as this repository's contributing guide sets a commit body, when it does; where it does not, the problem is the state before the change and its effect, and the solution is what the change does and why, each in at most two sentences, readable without opening the Ticket, leaving out what the diff and the body already show, such as side changes and individual names";
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* What none of the three may carry. They are published on the Target's
|
|
112
|
+
* repository, and the pipeline writes the one `Closes #<n>` itself, so a
|
|
113
|
+
* second closing keyword could close an issue nobody meant to.
|
|
114
|
+
*/
|
|
115
|
+
const PROSE_LIMITS =
|
|
116
|
+
"None of the three carries a title, a closing keyword (`Closes`, `Fixes`, `Resolves`) before an issue reference, a screenshot or a local path: they are published on this repository, and the pipeline writes the one `Closes #<n>` itself.";
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* How the implement Stage is told to answer the body, the problem and the
|
|
120
|
+
* solution: once, for the whole branch, after the review that changes it.
|
|
121
|
+
*/
|
|
122
|
+
const PROSE_GUIDANCE = `- Once the review's fixes are committed, answer a \`body\`, a \`problem\` and a \`solution\` beside \`title\`, each written for the whole branch. The \`body\` is the pull request's body below the \`Closes #<n>\` line the pipeline writes: write it ${BODY_SHAPE}. The \`problem\` and the \`solution\` open the squash commit's body, so \`git log\` says why without the Ticket: write them ${PROSE_SHAPE}. ${PROSE_LIMITS}`;
|
|
123
|
+
|
|
124
|
+
/**
|
|
125
|
+
* The language a Stage writes its answers in. A Stage left to itself wrote
|
|
126
|
+
* English on a Target whose issues and commits are in another language. The
|
|
127
|
+
* criterion's text is the exception: it is the Ticket's, quoted.
|
|
128
|
+
*/
|
|
129
|
+
const languageLine = (answers: string) =>
|
|
130
|
+
`- Write ${answers} in the language this repository's contributing guide sets for issues and commits, and where it sets none, in the language the Ticket is written in. A criterion's text stays as the Ticket writes it.`;
|
|
131
|
+
|
|
132
|
+
/** What the two Stages that write code answer in the Target's language. */
|
|
133
|
+
const CODE_STAGE_LANGUAGE = languageLine(
|
|
134
|
+
"your Notes, `title`, `body`, `problem`, `solution` and `noCommitReason`",
|
|
135
|
+
);
|
|
136
|
+
|
|
91
137
|
/**
|
|
92
138
|
* Guidance appended to every implement Stage, working around known defects of
|
|
93
139
|
* the `implement` skill in an unattended session.
|
|
@@ -104,6 +150,8 @@ const implementGuidance = (
|
|
|
104
150
|
|
|
105
151
|
- Make an initial commit before running \`/mattpocock-skills:code-review\`, so the reviewed diff is not empty.
|
|
106
152
|
${titleGuidance(base)}
|
|
153
|
+
${PROSE_GUIDANCE}
|
|
154
|
+
${CODE_STAGE_LANGUAGE}
|
|
107
155
|
- 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.
|
|
108
156
|
- Pass the review this Ticket's URL, \`${issueUrl}\`, as the spec. It otherwise looks for the spec in the commit messages, which need not name the Ticket, and reviews with no spec without saying so.
|
|
109
157
|
- 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.
|
|
@@ -136,14 +184,15 @@ ${noteEntryGuidance(standingNotes)}`;
|
|
|
136
184
|
* The guidance above is written for a Stage that could have fixed what it found
|
|
137
185
|
* and is told not to. verify could not: it is told to fix nothing in the first
|
|
138
186
|
* place, and what it has instead of a commit is a verdict with a slot per
|
|
139
|
-
* Acceptance Criterion
|
|
140
|
-
*
|
|
141
|
-
* because a defect
|
|
187
|
+
* Acceptance Criterion and a list of the defects the branch made. So this says
|
|
188
|
+
* which findings that verdict already carries and gives the rest the Notes
|
|
189
|
+
* list, because a defect that is not the branch's has no slot anywhere else.
|
|
142
190
|
*/
|
|
143
|
-
const verifyNotesGuidance = (standingNotes?: number) => `Notes for other Tickets: your verdict
|
|
191
|
+
const verifyNotesGuidance = (standingNotes?: number) => `Notes for other Tickets: your verdict carries what you make of each criterion and every defect this branch made, so anything else you find is lost unless you record it as a Note.
|
|
144
192
|
|
|
145
193
|
- What you make of a criterion belongs in the verdict. A criterion you judge \`unmet\` or \`unverifiable\` is reported in its own slot with the evidence you gathered, and never in a Note as well.
|
|
146
|
-
- A defect
|
|
194
|
+
- A defect this branch made belongs in the verdict's \`defects\`, never in a Note, and so does one among the Notes this Ticket's implement and fix Stages wrote.
|
|
195
|
+
- Any other defect is a Note. Your structured output carries a \`notes\` list beside the criteria, and the pipeline posts each entry where a human will meet it.
|
|
147
196
|
- A Note of yours carries the evidence that the defect is real in its \`evidence\` field, held to the standard you hold a criterion you judge \`unmet\` to. You have the branch and you can run it, so something you suspect but did not demonstrate is not a Note.
|
|
148
197
|
- Writing the Note is all you do about it: fix nothing, commit nothing, stage nothing, exactly as the rest of your brief says.
|
|
149
198
|
${noteEntryGuidance(standingNotes)}`;
|
|
@@ -160,6 +209,7 @@ ${noteEntryGuidance(standingNotes)}`;
|
|
|
160
209
|
* to write more.
|
|
161
210
|
*/
|
|
162
211
|
const noteEntryGuidance = (standingNotes?: number) => `- A Note is a defect — something that behaves wrongly or breaks. A preference of yours, a refactor you would enjoy and a test that would be nice to have are not Notes, however right you are about them.
|
|
212
|
+
- What this Ticket's own deliverable already records is not a Note either, such as a finding in the report section the Ticket asks for.
|
|
163
213
|
- Set \`ticket\` to the issue number the Note belongs to, and leave it out when you are not sure which one: a Note with no number becomes a comment on the issue the pipeline gathers Notes for triage on, where a wrong number lands on somebody else's Ticket.
|
|
164
214
|
- Write each Note in its parts: \`summary\` is one short sentence naming the defect; \`evidence\` is where the defect is and what shows it is real, what you ran or read, what you expected and what came back; \`impact\` is what breaks, and for whom; \`next\` is the fix, or the decision a human has to take before anyone can fix it, and is left out when there is neither.
|
|
165
215
|
- Write every part as plain sentences. No checkboxes: they would read as Acceptance Criteria.
|
|
@@ -207,17 +257,27 @@ const NEEDS_A_HUMAN =
|
|
|
207
257
|
* counterexample; the next verify broke the patch with the next input, while a
|
|
208
258
|
* fix of the cause was open within the Ticket's limit all along. A limit the
|
|
209
259
|
* evidence quotes is still the fix Stage's to know, so it may stay.
|
|
260
|
+
*
|
|
261
|
+
* The criteria are listed by the pipeline and answered by number, so the
|
|
262
|
+
* verdict never has to copy a criterion for anything to find it again.
|
|
263
|
+
*
|
|
264
|
+
* A defect the branch itself made is graded here too, beside the criteria,
|
|
265
|
+
* and fails the verdict as an unmet criterion does. Sent to a Note instead, it
|
|
266
|
+
* merged with the branch that made it, and triage opened a bug Ticket for it
|
|
267
|
+
* within hours.
|
|
210
268
|
*/
|
|
211
|
-
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.
|
|
269
|
+
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, and find the defects this branch made.
|
|
212
270
|
|
|
213
|
-
-
|
|
271
|
+
- The pipeline lists the Ticket's Acceptance Criteria below, numbered, each with the indented lines under its checkbox. Read the Ticket for their context, and grade the criteria as listed: answer each by its number, every listed number once and no other.
|
|
214
272
|
- Work in the checked-out branch, which already contains the implementation.
|
|
215
273
|
- 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)}
|
|
216
274
|
- Judge the code as it is. Do not fix anything, and never commit, stage or push. Scratch files are fine; the pipeline discards them.
|
|
217
275
|
- Mark a criterion \`unverifiable\` only when no evidence can be gathered, never as a substitute for looking.
|
|
218
276
|
- 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.
|
|
277
|
+
- ${BRANCH_DEFECT}, is reported in the verdict's \`defects\`, beside the criteria and not as a Note, when you show it with the evidence an \`unmet\` criterion needs, unless the Ticket leaves it out of scope or a documented decision accepts it. It fails the verdict as an \`unmet\` criterion does, and its evidence follows the same rule.
|
|
219
278
|
- An \`unmet\` criterion's evidence states the failure: where it sits, what you ran or read, what you expected, what came back, and the counterexample. It proposes no fix and no direction for one, and neither does what you say about whether a human decision is needed. It may quote a limit the Ticket, a documented decision or another criterion sets, naming where it comes from. A fix written there is what the fix Stage behind you would implement in place of finding the cause. This holds for a criterion's evidence only: a Note's \`next\` still carries the fix.
|
|
220
|
-
- End by emitting the verdict: one entry per criterion with its status and the evidence you actually gathered
|
|
279
|
+
- End by emitting the verdict: one entry per listed criterion, by its number, with its status and the evidence you actually gathered, and one entry in \`defects\` per defect of this branch you showed.
|
|
280
|
+
${languageLine("your Notes and the verdict's evidence")}`;
|
|
221
281
|
|
|
222
282
|
/** The Checks as the verify Stage is told about them: passed, and not its to run. */
|
|
223
283
|
function verifyChecksLine(checks: readonly string[]): string {
|
|
@@ -235,6 +295,9 @@ function verifyChecksLine(checks: readonly string[]): string {
|
|
|
235
295
|
* It is also told to fix the cause the evidence points at, not the patch the
|
|
236
296
|
* evidence may still propose, and to test that fix the way the next verify will
|
|
237
297
|
* attack it, for the reason {@link verifyInstructions} gives.
|
|
298
|
+
*
|
|
299
|
+
* It drives no plugin skill but the `pr` skill: the implement skill would
|
|
300
|
+
* re-read the Ticket and start over.
|
|
238
301
|
*/
|
|
239
302
|
const fixInstructions = (
|
|
240
303
|
base: string,
|
|
@@ -244,20 +307,33 @@ const fixInstructions = (
|
|
|
244
307
|
|
|
245
308
|
- Commit your fix on the branch you are on, in this worktree. ${NO_OTHER_BRANCH} Do not open pull requests, and do not close the Ticket.
|
|
246
309
|
- Start from the evidence: reproduce the failure, find what actually causes it, and fix that rather than the symptom.
|
|
247
|
-
- 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" ? `${UNMET_CAUSE_LINES}${HUMAN_DECISION_LINE}` : ""}
|
|
310
|
+
- Where the failure is an unmet Acceptance Criterion or a defect this branch made, add the regression test that would have caught it and commit it with the fix.${kind === "unmet-criteria" ? `${UNMET_CAUSE_LINES}${HUMAN_DECISION_LINE}` : ""}
|
|
248
311
|
- 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)}
|
|
249
312
|
${FINISH_GUIDANCE}
|
|
250
313
|
- Write commit subjects in the \`${SUBJECT_SHAPE}\` shape. The pipeline re-runs the Checks and the verify Stage as soon as you finish.
|
|
251
314
|
${titleGuidance(base)}
|
|
315
|
+
${FIX_PROSE_GUIDANCE}
|
|
316
|
+
${CODE_STAGE_LANGUAGE}
|
|
317
|
+
- Invoke no plugin skill but \`/mattpocock-skills:pr\`: the implement skill would re-read the Ticket and start over.
|
|
252
318
|
${NO_COMMIT_LINE}`;
|
|
253
319
|
|
|
320
|
+
/**
|
|
321
|
+
* How the fix Stage is told to answer the body, the problem and the solution:
|
|
322
|
+
* revised for the whole branch where its fix changes what one says, so the
|
|
323
|
+
* before an earlier Stage found is not lost, and blank otherwise, which keeps
|
|
324
|
+
* the earlier one.
|
|
325
|
+
*/
|
|
326
|
+
const FIX_PROSE_GUIDANCE = `- The \`body\`, \`problem\` and \`solution\` answered for this branch so far are below, when there are any. When your fix changes what one of them says, answer that one revised for the whole branch, keeping whatever it says of the branch before your fix that still holds: the \`body\` ${BODY_SHAPE}; the \`problem\` and the \`solution\` ${PROSE_SHAPE}. Answer each one your fix leaves true as an empty string, which keeps it. ${PROSE_LIMITS}`;
|
|
327
|
+
|
|
254
328
|
/**
|
|
255
329
|
* What every fix Stage is told about ending without a new commit, whatever it
|
|
256
330
|
* was sent in for. Ending so hands the Ticket to a human, and the reason the
|
|
257
331
|
* Stage answers is the one thing of what it said that reaches the hand-off:
|
|
258
332
|
* under `--json-schema` a last message in prose stays in the transcript. The
|
|
259
|
-
* implement Stage is not told this:
|
|
260
|
-
*
|
|
333
|
+
* implement Stage is not told this: its prompt names the field only among the
|
|
334
|
+
* answers it writes in the Target's language, and the schema's description is
|
|
335
|
+
* all it reads of what the field is for, so its prompt does not invite it to
|
|
336
|
+
* end without committing.
|
|
261
337
|
*/
|
|
262
338
|
const NO_COMMIT_LINE =
|
|
263
339
|
"- If you end without a new commit, say why in `noCommitReason`, in a few sentences: committing nothing hands the Ticket to a human, and the hand-off comment quotes your reason. Otherwise answer it empty.";
|
|
@@ -269,7 +345,7 @@ const UNMET_CAUSE_LINES = `
|
|
|
269
345
|
|
|
270
346
|
/** What the fix Stage sent in for unmet criteria does with one only a human can settle. */
|
|
271
347
|
const HUMAN_DECISION_LINE = `
|
|
272
|
-
- When any unmet criterion ${NEEDS_A_HUMAN}, as the verify Stage's evidence may already say, commit nothing and give your reason in \`noCommitReason\`: which criterion, and what it collides with. Do not work around it: a fix Stage that commits nothing hands the Ticket to a human, with the unmet criteria, their evidence and your reason.`;
|
|
348
|
+
- When any unmet criterion ${NEEDS_A_HUMAN}, or any defect cannot be fixed without overturning one, as the verify Stage's evidence may already say, commit nothing and give your reason in \`noCommitReason\`: which criterion or defect, and what it collides with. Do not work around it: a fix Stage that commits nothing hands the Ticket to a human, with the unmet criteria, the defects, their evidence and your reason.`;
|
|
273
349
|
|
|
274
350
|
/**
|
|
275
351
|
* The conflict Stage's brief. It may reach past the conflicted files only to
|
|
@@ -300,7 +376,7 @@ const failureSentences = (base: string): Record<FailureKind, string> => ({
|
|
|
300
376
|
"uncommitted-work":
|
|
301
377
|
"the Stage before you left changes in this worktree it never committed, listed below; commit what belongs to this Ticket and discard the rest",
|
|
302
378
|
"failed-check": "a Check the pipeline runs itself failed",
|
|
303
|
-
"unmet-criteria": "the verify Stage found unmet Acceptance Criteria",
|
|
379
|
+
"unmet-criteria": "the verify Stage found unmet Acceptance Criteria, or defects this branch made",
|
|
304
380
|
"failed-ci": "a pull request check failed after the branch was pushed",
|
|
305
381
|
"unresolved-conflict": `the branch conflicts with ${base}, and the session sent in to resolve the rebase did not finish it`,
|
|
306
382
|
});
|
|
@@ -332,6 +408,14 @@ export function implementPrompt(
|
|
|
332
408
|
]);
|
|
333
409
|
}
|
|
334
410
|
|
|
411
|
+
/** What the verify Stage is given to grade beside the Ticket's URL. */
|
|
412
|
+
export interface VerifyBrief {
|
|
413
|
+
/** The Ticket's unticked criteria, numbered, which the verdict answers by number. */
|
|
414
|
+
criteria?: readonly ListedCriterion[];
|
|
415
|
+
/** The Notes this Ticket's implement and fix Stages wrote in this Run. */
|
|
416
|
+
written?: readonly WrittenNote[];
|
|
417
|
+
}
|
|
418
|
+
|
|
335
419
|
/**
|
|
336
420
|
* A fresh session with no plugin skill, graded against the verdict schema.
|
|
337
421
|
*
|
|
@@ -347,11 +431,14 @@ export function verifyPrompt(
|
|
|
347
431
|
checks: readonly string[],
|
|
348
432
|
standingNotes?: number,
|
|
349
433
|
unmetBefore?: string,
|
|
434
|
+
{ criteria = [], written = [] }: VerifyBrief = {},
|
|
350
435
|
): string {
|
|
351
436
|
return sections([
|
|
352
437
|
`Ticket: ${issueUrl}`,
|
|
353
438
|
verifyInstructions(checks),
|
|
439
|
+
criteriaSection(criteria),
|
|
354
440
|
unmetBefore === undefined ? "" : unmetBeforeSection(unmetBefore),
|
|
441
|
+
writtenNotesSection(written),
|
|
355
442
|
stageBoundary(selfHosted),
|
|
356
443
|
verifyNotesGuidance(standingNotes),
|
|
357
444
|
extraPrompt,
|
|
@@ -376,7 +463,10 @@ export function conflictPrompt(
|
|
|
376
463
|
]);
|
|
377
464
|
}
|
|
378
465
|
|
|
379
|
-
/**
|
|
466
|
+
/**
|
|
467
|
+
* A fresh session with no plugin skill but the `pr` skill, given one failure
|
|
468
|
+
* and told to mend it, and the body, problem and solution answered so far.
|
|
469
|
+
*/
|
|
380
470
|
export function fixPrompt(
|
|
381
471
|
issueUrl: string,
|
|
382
472
|
failure: FixFailure,
|
|
@@ -385,11 +475,13 @@ export function fixPrompt(
|
|
|
385
475
|
selfHosted: boolean,
|
|
386
476
|
checks: readonly string[],
|
|
387
477
|
standingNotes?: number,
|
|
478
|
+
prose: BranchProse = {},
|
|
388
479
|
): string {
|
|
389
480
|
return sections([
|
|
390
481
|
`Ticket: ${issueUrl}`,
|
|
391
482
|
fixInstructions(base, failure.kind, checks),
|
|
392
483
|
failureSection(failure, base),
|
|
484
|
+
proseSection(prose),
|
|
393
485
|
stageBoundary(selfHosted),
|
|
394
486
|
notesGuidance(standingNotes),
|
|
395
487
|
extraPrompt,
|
|
@@ -411,17 +503,90 @@ function failureSection({ kind, summary, evidence }: FixFailure, base: string):
|
|
|
411
503
|
|
|
412
504
|
/** How the fix Stage reads the unmet criteria's evidence, said beside it. */
|
|
413
505
|
const UNMET_EVIDENCE_LEAD =
|
|
414
|
-
"This is the verify Stage's evidence for each unmet criterion. A fix this evidence proposes is a lead, not the answer: find the cause yourself, starting from the failure it states.";
|
|
506
|
+
"This is the verify Stage's evidence for each unmet criterion, given as its checkbox line reads, and for each defect this branch made. A fix this evidence proposes is a lead, not the answer: find the cause yourself, starting from the failure it states.";
|
|
415
507
|
|
|
416
|
-
/**
|
|
508
|
+
/**
|
|
509
|
+
* The body, the problem and the solution answered for the branch so far, each
|
|
510
|
+
* under its field's name; nothing where none has been answered.
|
|
511
|
+
*/
|
|
512
|
+
function proseSection(prose: BranchProse): string {
|
|
513
|
+
const answered = BRANCH_PROSE_FIELDS.flatMap((field) => {
|
|
514
|
+
const answer = prose[field];
|
|
515
|
+
return answer === undefined ? [] : [`### \`${field}\`\n\n${fenced(answer)}`];
|
|
516
|
+
});
|
|
517
|
+
if (answered.length === 0) return "";
|
|
518
|
+
return ["## What the branch's answers say now", ...answered].join("\n\n");
|
|
519
|
+
}
|
|
520
|
+
|
|
521
|
+
/**
|
|
522
|
+
* Text fenced with more backticks than any run inside it, so a body that
|
|
523
|
+
* carries a fence of its own reads as one block.
|
|
524
|
+
*/
|
|
525
|
+
function fenced(text: string): string {
|
|
526
|
+
const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
|
|
527
|
+
const fence = "`".repeat(Math.max(3, longest + 1));
|
|
528
|
+
return `${fence}\n${text}\n${fence}`;
|
|
529
|
+
}
|
|
530
|
+
|
|
531
|
+
/** The unmet criteria and defects a fix Stage was sent in for, and what clearing them now takes. */
|
|
417
532
|
function unmetBeforeSection(evidence: string): string {
|
|
418
533
|
return outputSection(
|
|
419
534
|
"## Judged unmet before the fix",
|
|
420
535
|
evidence,
|
|
421
|
-
"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`.",
|
|
536
|
+
"The verify Stage before you judged these criteria unmet, and these defects the branch's own, 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`. Such a defect goes in your `defects` again until its counterexample is gone.",
|
|
422
537
|
);
|
|
423
538
|
}
|
|
424
539
|
|
|
540
|
+
/**
|
|
541
|
+
* The criteria the verdict answers, by number, each with the lines under its
|
|
542
|
+
* checkbox; fenced, because they are the Ticket's Markdown, quoted.
|
|
543
|
+
*/
|
|
544
|
+
function criteriaSection(criteria: readonly ListedCriterion[]): string {
|
|
545
|
+
if (criteria.length === 0) return "";
|
|
546
|
+
const listed = criteria.flatMap(({ number, text, details }) => [
|
|
547
|
+
`${number}. ${text}`,
|
|
548
|
+
...indented(details),
|
|
549
|
+
]);
|
|
550
|
+
return [
|
|
551
|
+
"## The Acceptance Criteria, by number",
|
|
552
|
+
"",
|
|
553
|
+
"Each is an unticked checkbox on the Ticket, in the order the body and then its comments write them. A checkbox nested under another is a criterion of its own.",
|
|
554
|
+
"",
|
|
555
|
+
fenced(listed.join("\n")),
|
|
556
|
+
].join("\n");
|
|
557
|
+
}
|
|
558
|
+
|
|
559
|
+
/** Lines under a numbered criterion, their own indent kept relative to each other. */
|
|
560
|
+
function indented(lines: readonly string[]): string[] {
|
|
561
|
+
const widths = lines
|
|
562
|
+
.filter((line) => line.trim() !== "")
|
|
563
|
+
.map((line) => (/^[ \t]*/.exec(line)?.[0] ?? "").length);
|
|
564
|
+
const common = Math.min(...widths);
|
|
565
|
+
return lines.map((line) => (line.trim() === "" ? "" : ` ${line.slice(common)}`));
|
|
566
|
+
}
|
|
567
|
+
|
|
568
|
+
/**
|
|
569
|
+
* The Notes this Ticket's code Stages wrote in this Run, which the verify Stage
|
|
570
|
+
* grades for a defect of the branch; nothing where they wrote none.
|
|
571
|
+
*/
|
|
572
|
+
function writtenNotesSection(written: readonly WrittenNote[]): string {
|
|
573
|
+
if (written.length === 0) return "";
|
|
574
|
+
const lines = written.flatMap(({ stage, note }) => [
|
|
575
|
+
`- From the ${stage} Stage${note.ticket === undefined ? "" : `, for #${note.ticket}`}: ${note.summary}`,
|
|
576
|
+
...NOTE_PARTS.flatMap((part) => {
|
|
577
|
+
const text = note[part];
|
|
578
|
+
return text === undefined ? [] : [` ${part}: ${text}`];
|
|
579
|
+
}),
|
|
580
|
+
]);
|
|
581
|
+
return [
|
|
582
|
+
"## Notes this Ticket's implement and fix Stages wrote in this Run",
|
|
583
|
+
"",
|
|
584
|
+
"The pipeline has already posted these. One that is a defect this branch made is graded in your verdict's `defects`, held to the same evidence as one you found yourself.",
|
|
585
|
+
"",
|
|
586
|
+
fenced(lines.join("\n")),
|
|
587
|
+
].join("\n");
|
|
588
|
+
}
|
|
589
|
+
|
|
425
590
|
/**
|
|
426
591
|
* A heading, an optional line of prose, and raw command output. The output is
|
|
427
592
|
* fenced because it would otherwise be read as Markdown.
|