ticket-runner 0.6.4 → 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 +5 -5
- package/README.md +4 -4
- package/docs/templates/operator-skill.md +81 -16
- package/package.json +1 -1
- package/src/acceptance-criteria.ts +99 -2
- package/src/adapters/claude-agent-runner.ts +5 -5
- package/src/adapters/exec.ts +32 -4
- package/src/adapters/gh-tracker.ts +276 -60
- package/src/adapters/git-workspace.ts +27 -10
- package/src/adapters/liveness.ts +77 -0
- package/src/adapters/process-tree.ts +4 -7
- package/src/adapters/version.ts +5 -5
- package/src/branch.ts +1 -1
- package/src/cli.ts +2 -2
- package/src/config.ts +22 -4
- package/src/conventions.ts +22 -19
- package/src/credential.ts +14 -13
- package/src/criteria.ts +102 -52
- package/src/failing-base.ts +7 -7
- package/src/failure-message.ts +72 -0
- package/src/guards.ts +21 -6
- package/src/handoff.ts +2 -2
- package/src/init.ts +8 -8
- package/src/landing.ts +1 -1
- package/src/lifecycle.ts +2 -2
- package/src/lock.ts +10 -2
- package/src/note-schema.ts +14 -11
- package/src/notes.ts +19 -7
- package/src/operator-skill.ts +2 -2
- package/src/orchestrator.ts +758 -275
- package/src/outside-fault.ts +103 -0
- package/src/ports/agent-runner.ts +1 -1
- package/src/ports/tracker.ts +29 -15
- package/src/ports/workspace.ts +52 -24
- package/src/progress.ts +42 -7
- package/src/prompts.ts +242 -34
- package/src/readiness.ts +11 -11
- package/src/remove.ts +7 -7
- package/src/resume.ts +28 -20
- package/src/run-log.ts +5 -5
- package/src/run.ts +55 -13
- package/src/staleness.ts +14 -14
- package/src/start.ts +29 -16
- package/src/stranded.ts +19 -19
- package/src/templates.ts +398 -149
- package/src/title.ts +106 -8
- package/src/transcript-home.ts +49 -0
- package/src/verdict.ts +132 -27
- package/src/version-number.ts +13 -13
- package/src/version-pr.ts +12 -12
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
import { spawnSync } from "node:child_process";
|
|
2
|
+
import { readFileSync } from "node:fs";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Whether a process, or a process group, is still alive.
|
|
6
|
+
*
|
|
7
|
+
* `process.kill(id, 0)` alone would not say: it still succeeds on a zombie, a
|
|
8
|
+
* process that is dead but not yet reaped, and a killed orphan stays one until
|
|
9
|
+
* the machine's init reaps it, which on a cloud Host takes seconds and in a
|
|
10
|
+
* PID namespace whose init never reaps takes forever. The kill and the tests
|
|
11
|
+
* of it both judge by this.
|
|
12
|
+
*/
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* Whether the process is alive: running, sleeping or stopped. A zombie is not,
|
|
16
|
+
* though it can still be signalled. Where its state cannot be read at all, the
|
|
17
|
+
* signal's answer stands.
|
|
18
|
+
*/
|
|
19
|
+
export function alive(pid: number): boolean {
|
|
20
|
+
if (!signalled(pid)) return false;
|
|
21
|
+
const state = stateOf(pid);
|
|
22
|
+
if (state === null) return true;
|
|
23
|
+
return state !== undefined && !isDead(state);
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Whether any process in the group is alive, by the same judgement. Where the
|
|
28
|
+
* process table cannot be read, the signal's answer stands.
|
|
29
|
+
*/
|
|
30
|
+
export function groupAlive(pgid: number): boolean {
|
|
31
|
+
if (!signalled(-pgid)) return false;
|
|
32
|
+
const listed = spawnSync("ps", ["-A", "-o", "pgid=,stat="], { encoding: "utf8" });
|
|
33
|
+
if (listed.error !== undefined || listed.status !== 0) return true;
|
|
34
|
+
return listed.stdout.split("\n").some((line) => {
|
|
35
|
+
const [group, state] = line.trim().split(/\s+/);
|
|
36
|
+
return Number(group) === pgid && state !== undefined && !isDead(state);
|
|
37
|
+
});
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** Whether a signal 0 reaches anything; a negative id is a process group. */
|
|
41
|
+
function signalled(id: number): boolean {
|
|
42
|
+
try {
|
|
43
|
+
process.kill(id, 0);
|
|
44
|
+
return true;
|
|
45
|
+
} catch {
|
|
46
|
+
return false;
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/** Zombie, or on Linux dead and on its way out of the table. */
|
|
51
|
+
function isDead(state: string): boolean {
|
|
52
|
+
return state.startsWith("Z") || state.startsWith("X");
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* The process's state letters, read from `/proc` where there is one and from
|
|
57
|
+
* `ps` where there is not; `undefined` once it has left the process table, and
|
|
58
|
+
* `null` when there is neither to ask.
|
|
59
|
+
*/
|
|
60
|
+
function stateOf(pid: number): string | undefined | null {
|
|
61
|
+
let stat: string;
|
|
62
|
+
try {
|
|
63
|
+
stat = readFileSync(`/proc/${pid}/stat`, "utf8");
|
|
64
|
+
} catch {
|
|
65
|
+
return stateFromPs(pid);
|
|
66
|
+
}
|
|
67
|
+
// `pid (comm) state ...`, where comm may itself hold spaces and parentheses.
|
|
68
|
+
return stat.slice(stat.lastIndexOf(")") + 1).trim().split(/\s+/)[0];
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** The state `ps` prints for the process, nothing once it has gone, `null` without `ps`. */
|
|
72
|
+
function stateFromPs(pid: number): string | undefined | null {
|
|
73
|
+
const listed = spawnSync("ps", ["-o", "stat=", "-p", String(pid)], { encoding: "utf8" });
|
|
74
|
+
if (listed.error !== undefined) return null;
|
|
75
|
+
const state = listed.stdout.trim();
|
|
76
|
+
return listed.status === 0 && state !== "" ? state : undefined;
|
|
77
|
+
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { spawnSync } from "node:child_process";
|
|
2
2
|
import { readFileSync, readdirSync } from "node:fs";
|
|
3
|
+
import { alive, groupAlive } from "./liveness.js";
|
|
3
4
|
|
|
4
5
|
/**
|
|
5
6
|
* Killing a command together with everything it started.
|
|
@@ -207,17 +208,13 @@ function signal(tree: Tree, name: NodeJS.Signals): void {
|
|
|
207
208
|
for (const pid of tree.pids) send(pid, name);
|
|
208
209
|
}
|
|
209
210
|
|
|
211
|
+
/** A zombie is gone: what is left of it waits only on its parent to reap it. */
|
|
210
212
|
function anyAlive(tree: Tree): boolean {
|
|
211
|
-
return [...tree.
|
|
212
|
-
}
|
|
213
|
-
|
|
214
|
-
/** A negative id is a process group. */
|
|
215
|
-
function alive(id: number): boolean {
|
|
216
|
-
return send(id, 0);
|
|
213
|
+
return [...tree.pids].some(alive) || [...tree.groups].some(groupAlive);
|
|
217
214
|
}
|
|
218
215
|
|
|
219
216
|
/** Whether the signal reached anything; one already gone is not an error here. */
|
|
220
|
-
function send(id: number, name: NodeJS.Signals
|
|
217
|
+
function send(id: number, name: NodeJS.Signals): boolean {
|
|
221
218
|
try {
|
|
222
219
|
process.kill(id, name);
|
|
223
220
|
return true;
|
package/src/adapters/version.ts
CHANGED
|
@@ -4,11 +4,11 @@ import { fileURLToPath } from "node:url";
|
|
|
4
4
|
import { exec } from "./exec.js";
|
|
5
5
|
|
|
6
6
|
/**
|
|
7
|
-
* Which
|
|
7
|
+
* Which version this copy of the pipeline is (ADR-0007).
|
|
8
8
|
*
|
|
9
9
|
* Computed once, in the CLI, and handed to the Run and to `init` the way the
|
|
10
10
|
* run id is. Nothing downstream asks again: every line one Run stamps — its
|
|
11
|
-
* summary, each
|
|
11
|
+
* summary, each progress comment, each state file, the file beside its
|
|
12
12
|
* transcripts — has to say the same thing, and the only way to promise that is
|
|
13
13
|
* to read it once.
|
|
14
14
|
*
|
|
@@ -26,7 +26,7 @@ export const PACKAGE_ROOT = fileURLToPath(new URL("../..", import.meta.url));
|
|
|
26
26
|
const UNKNOWN = "unknown";
|
|
27
27
|
|
|
28
28
|
/**
|
|
29
|
-
* The
|
|
29
|
+
* The version, as everything this Run writes will report it.
|
|
30
30
|
*
|
|
31
31
|
* An installed copy is its number and nothing else, because a machine installs
|
|
32
32
|
* a tag: two machines that say `0.4.0` run the same code. A development
|
|
@@ -45,7 +45,7 @@ export async function pipelineVersion(packageRoot: string = PACKAGE_ROOT): Promi
|
|
|
45
45
|
* its package, and undefined where the package names none or names one this
|
|
46
46
|
* cannot read.
|
|
47
47
|
*
|
|
48
|
-
* The one thing a Run has to know to ask whether a newer
|
|
48
|
+
* The one thing a Run has to know to ask whether a newer version is out. It is
|
|
49
49
|
* read from the package rather than written down here for the same reason the
|
|
50
50
|
* number is: an installed copy and a checkout answer the same way, and a fork
|
|
51
51
|
* asks about itself (ADR-0007).
|
|
@@ -66,7 +66,7 @@ export function pipelineRepository(packageRoot: string = PACKAGE_ROOT): string |
|
|
|
66
66
|
return match?.[1];
|
|
67
67
|
}
|
|
68
68
|
|
|
69
|
-
/** The number in `package.json`, which is the whole of an installed
|
|
69
|
+
/** The number in `package.json`, which is the whole of an installed version. */
|
|
70
70
|
function packageNumber(packageRoot: string): string {
|
|
71
71
|
const version = packageField(packageRoot, "version");
|
|
72
72
|
return typeof version === "string" && version !== "" ? version : UNKNOWN;
|
package/src/branch.ts
CHANGED
|
@@ -33,7 +33,7 @@ export function worktreePath(repoRoot: string, ticket: number): string {
|
|
|
33
33
|
}
|
|
34
34
|
|
|
35
35
|
/**
|
|
36
|
-
* The gitignored worktree a Check runs in at a merge-base with the
|
|
36
|
+
* The gitignored worktree a Check runs in at a merge-base with the base branch,
|
|
37
37
|
* beside the Tickets' own: named for the commit, shortened as git shortens one.
|
|
38
38
|
*/
|
|
39
39
|
export function baseWorktreePath(repoRoot: string, commit: string): string {
|
package/src/cli.ts
CHANGED
|
@@ -38,10 +38,10 @@ async function main(argv: string[]): Promise<number> {
|
|
|
38
38
|
}
|
|
39
39
|
|
|
40
40
|
// Resolved once, here, and handed to everything that stamps it the way the
|
|
41
|
-
// run id is: a Run whose summary, comments,
|
|
41
|
+
// run id is: a Run whose summary, comments, state files and transcripts all
|
|
42
42
|
// read it separately could report four different things (ADR-0007).
|
|
43
43
|
const version = await pipelineVersion();
|
|
44
|
-
// The repository a newer
|
|
44
|
+
// The repository a newer version would be published on, read from the same
|
|
45
45
|
// package the number came from, so a fork asks about itself (ADR-0007).
|
|
46
46
|
const repository = pipelineRepository();
|
|
47
47
|
if (commandLine.kind === "version") {
|
package/src/config.ts
CHANGED
|
@@ -38,6 +38,7 @@ const configSchema = z
|
|
|
38
38
|
baseBranch: z.string().min(1).optional(),
|
|
39
39
|
lanes: z.number().int().positive().optional(),
|
|
40
40
|
checks: z.array(z.string().min(1)).optional(),
|
|
41
|
+
merge: z.boolean().optional(),
|
|
41
42
|
gates: z
|
|
42
43
|
.object({ checks: z.boolean().optional(), ci: z.boolean().optional() })
|
|
43
44
|
.strict()
|
|
@@ -55,6 +56,7 @@ const configSchema = z
|
|
|
55
56
|
ciTimeoutMinutes: z.number().positive().optional(),
|
|
56
57
|
ciGraceMinutes: z.number().nonnegative().optional(),
|
|
57
58
|
checkTimeoutMinutes: z.number().positive().optional(),
|
|
59
|
+
keepTranscripts: z.boolean().optional(),
|
|
58
60
|
labels: z
|
|
59
61
|
.object({
|
|
60
62
|
needsTriage: z.string().min(1).optional(),
|
|
@@ -100,6 +102,13 @@ export interface Config {
|
|
|
100
102
|
*/
|
|
101
103
|
lanes: number;
|
|
102
104
|
checks: string[];
|
|
105
|
+
/**
|
|
106
|
+
* Whether a Run merges a Ticket whose CI is green. A Target that merges by
|
|
107
|
+
* hand sets it to `false`, and its green Tickets are handed off with their
|
|
108
|
+
* pull requests as published. Not a gate: a gate switched off loosens what
|
|
109
|
+
* reaches a merge, and this tightens it.
|
|
110
|
+
*/
|
|
111
|
+
merge: boolean;
|
|
103
112
|
gates: { checks: boolean; ci: boolean };
|
|
104
113
|
stages: {
|
|
105
114
|
implement: StageConfig;
|
|
@@ -121,6 +130,12 @@ export interface Config {
|
|
|
121
130
|
* the whole pipeline, and every command gets the whole of it.
|
|
122
131
|
*/
|
|
123
132
|
checkTimeoutMinutes: number;
|
|
133
|
+
/**
|
|
134
|
+
* Whether a handed-off Ticket's transcripts are kept on the Target's remote,
|
|
135
|
+
* where the config says. Absent means it follows the Target's visibility,
|
|
136
|
+
* which {@link import("./transcript-home.js").resolveTranscriptHome} reads.
|
|
137
|
+
*/
|
|
138
|
+
keepTranscripts?: boolean;
|
|
124
139
|
labels: Labels;
|
|
125
140
|
}
|
|
126
141
|
|
|
@@ -172,7 +187,7 @@ const LABEL_DEFAULTS: Labels = {
|
|
|
172
187
|
* from package.json when the config does not name them.
|
|
173
188
|
*
|
|
174
189
|
* Throws {@link ConfigError} naming the offending field when the file is
|
|
175
|
-
* unusable; a missing file is not an error. `version` is the
|
|
190
|
+
* unusable; a missing file is not an error. `version` is the version doing the
|
|
176
191
|
* refusing, which the message for an unknown key carries.
|
|
177
192
|
*/
|
|
178
193
|
export function loadConfig(repoRoot: string, version: string): Config {
|
|
@@ -189,6 +204,7 @@ export function loadConfig(repoRoot: string, version: string): Config {
|
|
|
189
204
|
...(file.baseBranch === undefined ? {} : { baseBranch: file.baseBranch }),
|
|
190
205
|
lanes: file.lanes ?? DEFAULT_LANES,
|
|
191
206
|
checks: file.checks ?? inferChecks(repoRoot),
|
|
207
|
+
merge: file.merge ?? true,
|
|
192
208
|
gates: {
|
|
193
209
|
checks: file.gates?.checks ?? true,
|
|
194
210
|
ci: file.gates?.ci ?? true,
|
|
@@ -203,17 +219,19 @@ export function loadConfig(repoRoot: string, version: string): Config {
|
|
|
203
219
|
ciTimeoutMinutes: file.ciTimeoutMinutes ?? 30,
|
|
204
220
|
ciGraceMinutes: file.ciGraceMinutes ?? DEFAULT_CI_GRACE_MINUTES,
|
|
205
221
|
checkTimeoutMinutes: file.checkTimeoutMinutes ?? DEFAULT_CHECK_TIMEOUT_MINUTES,
|
|
222
|
+
// Spread, as baseBranch is: unset is an answer of its own, not false.
|
|
223
|
+
...(file.keepTranscripts === undefined ? {} : { keepTranscripts: file.keepTranscripts }),
|
|
206
224
|
labels: labels(file.labels),
|
|
207
225
|
};
|
|
208
226
|
}
|
|
209
227
|
|
|
210
228
|
/**
|
|
211
|
-
* Why the file was refused, and — for an unknown key — which
|
|
229
|
+
* Why the file was refused, and — for an unknown key — which version refused it.
|
|
212
230
|
*
|
|
213
231
|
* The schema is strict, so a key this install has never heard of is refused by
|
|
214
232
|
* name. That is the right answer to a typo and a confusing one to a key a newer
|
|
215
|
-
*
|
|
216
|
-
* the same. So the
|
|
233
|
+
* version added, and on a machine running a stale install the two look exactly
|
|
234
|
+
* the same. So the version is said out loud, and the config file itself is left
|
|
217
235
|
* without one to carry (ADR-0007).
|
|
218
236
|
*/
|
|
219
237
|
function refusal(error: z.ZodError, version: string): string {
|
package/src/conventions.ts
CHANGED
|
@@ -11,7 +11,13 @@
|
|
|
11
11
|
* vocabulary, the review rules, the test policy are the Target's business, and a
|
|
12
12
|
* document that took them over would be rewritten out from under it.
|
|
13
13
|
*
|
|
14
|
-
*
|
|
14
|
+
* It is for the readers the pipeline does not brief: humans, attended Claude
|
|
15
|
+
* sessions in a Target, and the Planning skills that write Tickets. It leaves
|
|
16
|
+
* out what the Stage prompts already say, such as how a Stage titles its branch
|
|
17
|
+
* and that it opens no pull request: a Stage hears those from its own prompt,
|
|
18
|
+
* and a second copy here would only drift from it.
|
|
19
|
+
*
|
|
20
|
+
* The one thing it says about versions is the mark it bears: which pipeline
|
|
15
21
|
* wrote the copy a Target carries, hidden on the first line so no reader of the
|
|
16
22
|
* document meets it. That is a direction comparing text never gives — `init`
|
|
17
23
|
* leaves a document a newer pipeline wrote alone, and a Run behind one warns
|
|
@@ -37,7 +43,7 @@ export const CLAUDE_SECTION = `## Pipeline conventions
|
|
|
37
43
|
`;
|
|
38
44
|
|
|
39
45
|
/**
|
|
40
|
-
* The marker carrying the
|
|
46
|
+
* The marker carrying the version, as the first line of the document ends.
|
|
41
47
|
*
|
|
42
48
|
* An HTML comment, like every other marker the pipeline finds its own writing
|
|
43
49
|
* by, so it is on the line a reader sees and in none of the text they read.
|
|
@@ -46,10 +52,10 @@ const MARKER = /<!-- ticket-runner:version ([^\s>]+) -->/;
|
|
|
46
52
|
|
|
47
53
|
/**
|
|
48
54
|
* The document itself, as {@link CONVENTIONS_PATH} must contain it, marked with
|
|
49
|
-
* the
|
|
55
|
+
* the version writing it.
|
|
50
56
|
*
|
|
51
57
|
* The number alone, never the commit a development checkout adds: two checkouts
|
|
52
|
-
* of one
|
|
58
|
+
* of one version write one document, and a Target whose copy was rewritten by
|
|
53
59
|
* every commit would say nothing by having been.
|
|
54
60
|
*
|
|
55
61
|
* A copy with no number to stamp carries no marker rather than a marker saying
|
|
@@ -63,7 +69,7 @@ export function conventionsDoc(version: string): string {
|
|
|
63
69
|
}
|
|
64
70
|
|
|
65
71
|
/**
|
|
66
|
-
* The
|
|
72
|
+
* The version number a Target's copy was written by, and undefined for a copy
|
|
67
73
|
* carrying no mark at all — every copy an older pipeline wrote, which is read
|
|
68
74
|
* as being behind rather than as being wrong.
|
|
69
75
|
*/
|
|
@@ -73,47 +79,44 @@ export function conventionsMark(document: string | undefined): string | undefine
|
|
|
73
79
|
return marked === undefined ? undefined : versionNumber(marked);
|
|
74
80
|
}
|
|
75
81
|
|
|
76
|
-
/** Everything under the marked first line, which no
|
|
82
|
+
/** Everything under the marked first line, which no version changes. */
|
|
77
83
|
const BODY = `
|
|
78
84
|
What \`ticket-runner\` requires of this repository, and nothing else. \`ticket-runner init\` writes this file and rewrites it whenever those requirements change, so an edit made here does not survive the next \`init\`. Everything the pipeline leaves to this repository — which commit types and scopes it uses, how it reviews, what it tests — belongs in the repository's own contributing guide.
|
|
79
85
|
|
|
86
|
+
Besides names such as GitHub and Claude Code, a capitalised word below is one of the pipeline's own terms, said in a few words where it first appears; every other word means what it ordinarily does. To the pipeline this repository is a Target, the repository a Run takes its work from and merges into. A Run is one invocation of the pipeline on a Host, the machine it executes on, and works through Tickets, GitHub issues each sized for one session of work, until it has none left to take or is told to take no more. Each Ticket is worked by Stages, each one Claude Code session with a single purpose: implement, verify, fix, or resolve a rebase conflict. A Stage may answer Notes beside its work: defects it met that belong to another Ticket or to none yet, recorded where a human will find them instead of being fixed there.
|
|
87
|
+
|
|
80
88
|
## Commits
|
|
81
89
|
|
|
82
90
|
- Subject: \`<type>(<scope>): <summary>\`.
|
|
83
91
|
- The type and scope vocabulary is this repository's own. The pipeline reads the shape, never the words.
|
|
84
|
-
-
|
|
92
|
+
- This repository's own commit conventions must fit this shape: the pipeline titles its pull requests in it where it can, and so the squash commits they land as. Where it cannot, a pull request takes the Ticket's title.
|
|
85
93
|
|
|
86
94
|
## Branches
|
|
87
95
|
|
|
88
96
|
- \`agent/<n>-<slug>\` belongs to the pipeline. A Run creates one per Ticket, works in a worktree of it, and pushes it after every Stage that commits. The repository deletes it when the pull request merges, a setting \`ticket-runner init\` switches on. Nothing else branches there.
|
|
89
|
-
- \`ticket-runner/lock\` and \`ticket-runner/state\` belong to the pipeline too. The first says which Run holds this repository, and the second keeps the
|
|
90
|
-
- A Stage commits only to the branch already checked out in the worktree it was started in. It creates no branch and switches to none.
|
|
91
|
-
|
|
92
|
-
## What a Stage does not do
|
|
93
|
-
|
|
94
|
-
- A Stage opens no pull request and closes no issue. The pipeline opens the pull request when the Stage finishes, waits for CI, merges it, and lets the merge close the Ticket.
|
|
97
|
+
- \`ticket-runner/lock\` and \`ticket-runner/state\` belong to the pipeline too. The first says which Run holds this repository, and the second keeps the state file of every Ticket a Run can resume, and the transcripts of the Stages of a handed-off Ticket where the \`keepTranscripts\` setting keeps them there, which it does by default only on a private repository. A Hand-off gives a Ticket to a human rather than merging it, and leaves its work where they can carry on from it. Nothing else commits to either, except a human, or an Operator a human asked, the Claude session a human opens on a cloud Host from the Claude app to start a Run, watch it and stop it, and, while no Run holds this repository, to carry the human's decision on a handed-off Ticket to the board, releasing a lock a vanished Host left behind.
|
|
95
98
|
|
|
96
99
|
## What a Ticket needs
|
|
97
100
|
|
|
98
101
|
A Ticket is one issue the pipeline can implement in a single session. It is refused unless it carries all three:
|
|
99
102
|
|
|
100
|
-
- **Acceptance Criteria** — unticked task list items, a \`- [ ]\` at the head of a line, in the issue body or in one of its comments.
|
|
103
|
+
- **Acceptance Criteria** — unticked task list items, a \`- [ ]\` at the head of a line, in the issue body or in one of its comments. The verify Stage grades them one by one, and beside them any defect the Ticket's own branch made, which fails the Ticket as an unmet criterion does unless the Ticket leaves it out of scope or a documented decision accepts it. A promise written as prose is not a criterion, and a Ticket whose checkboxes are all ticked has none.
|
|
101
104
|
- **Blockers as native dependencies** — GitHub's own \`blocked by\` edges, as \`gh issue create --blocked-by <n>\` records them. A \`Blocked by\` section in the body is a human-readable copy and nothing the pipeline reads.
|
|
102
105
|
- **The \`ready-for-agent\` label** — how a Run finds the Ticket. A Run labels it \`in-progress\` for as long as it holds it.
|
|
103
106
|
|
|
104
107
|
## Checks
|
|
105
108
|
|
|
106
|
-
- The Checks of different Tickets may run at the same time, each in its own worktree, because a Run has as many Lanes as \`lanes\` says. A Target whose Checks need a port, a database or anything else they would have to share keeps \`lanes\` at one, or makes them independent of each other.
|
|
107
|
-
- A Check that fails on a Ticket's branch, or CI that fails on its pull request, is graded again at what the branch inherited: the pipeline runs the Check commands in a clean worktree at the branch's merge-base with the
|
|
109
|
+
- A Check is a command the pipeline runs itself on a Ticket's code to gate it, such as its tests or its typecheck, and never the CI on a pull request, which the pipeline only waits for. The Checks of different Tickets may run at the same time, each in its own worktree, because a Run has as many Lanes as \`lanes\` says, and each Lane holds one Ticket in progress. A Target whose Checks need a port, a database or anything else they would have to share keeps \`lanes\` at one, or makes them independent of each other.
|
|
110
|
+
- A Check that fails on a Ticket's branch, or CI that fails on its pull request, is graded again at what the branch inherited: the pipeline runs the Check commands in a clean worktree at the branch's merge-base with the base branch. One that fails there too is the base branch's, not the Ticket's, so the Ticket is released, given back to the pipeline for a later Run to take up again, as something outside the Ticket stopped its work. That Release spends none of its fix budget (the fix Stages it is allowed), the Run claims no more Tickets, and the pipeline posts a Note on the standing Notes issue naming the Check. The next Run rebases the Ticket onto the base branch before its Checks, so mending the base branch is what frees it. Nothing is installed in the worktree at the merge-base: its Checks find their dependencies in the main checkout, as a Ticket's worktree does, so Checks that need an install or a build step of their own fail there and release the Ticket, and the Note's output shows it.
|
|
108
111
|
|
|
109
112
|
## The Operator's skill
|
|
110
113
|
|
|
111
|
-
- \`.claude/skills/ticket-runner/\` belongs to the pipeline. It tells an Operator,
|
|
114
|
+
- \`.claude/skills/ticket-runner/\` belongs to the pipeline. It tells an Operator how to start a Run, report on it and pass on a Stop, a human's request that the Run finish the Tickets its Lanes hold and take no more. It also says what an Operator may write on the board, only at a human's explicit request and only while no Run holds this repository: swap a handed-off Ticket's \`ready-for-human\` label for \`ready-for-agent\`, post the human's decision as a comment with each new criterion as its own \`- [ ]\` checkbox, and turn a criterion the human names as replaced into \`- (superseded)\` followed by its words. It rewrites no criterion and no body otherwise. \`ticket-runner init\` writes it and rewrites it like this file, so an edit made there does not survive the next \`init\` either.
|
|
112
115
|
|
|
113
116
|
## Local directories
|
|
114
117
|
|
|
115
118
|
Both are \`ticket-runner\`'s own, both are gitignored by \`ticket-runner init\`, and neither is ever committed.
|
|
116
119
|
|
|
117
|
-
- \`.worktrees/ticket-<n>/\` — one git worktree per claimed Ticket, where its Stages run. Beside them, \`.worktrees/base-<commit>/\` is a clean worktree at a merge-base with the
|
|
118
|
-
- \`.ticket-runner/\` — the Run's logs and Stage transcripts. The Run lock and the
|
|
120
|
+
- \`.worktrees/ticket-<n>/\` — one git worktree per claimed Ticket, where its Stages run. Beside them, \`.worktrees/base-<commit>/\` is a clean worktree at a merge-base with the base branch, made to run a failing Check there once and removed when it has run.
|
|
121
|
+
- \`.ticket-runner/\` — the Run's logs and Stage transcripts. The Run lock and the state file a Ticket keeps while its branch has work worth resuming are not here but on the Target's remote, so that a Run on any Host sees which Run holds the Target, and carries on from where a killed Run, or a handed-off Ticket relabelled \`ready-for-agent\`, stopped.
|
|
119
122
|
`;
|
package/src/credential.ts
CHANGED
|
@@ -16,25 +16,26 @@ export type Credential = "subscription" | "api-key";
|
|
|
16
16
|
*/
|
|
17
17
|
export const API_KEY_ENV_VAR = "ANTHROPIC_API_KEY";
|
|
18
18
|
|
|
19
|
-
/**
|
|
19
|
+
/** What the Stages are billed to, as the Run summary's header and the log name it. */
|
|
20
20
|
export const CREDENTIAL_WORDS: Record<Credential, string> = {
|
|
21
21
|
subscription: "subscription",
|
|
22
22
|
"api-key": "API key",
|
|
23
23
|
};
|
|
24
24
|
|
|
25
25
|
/**
|
|
26
|
-
* The `apiKeySource` a Stage's `system/init` event reports when it
|
|
27
|
-
* Run
|
|
28
|
-
* choose: a key an `apiKeyHelper` in the
|
|
29
|
-
* no environment variable removes.
|
|
26
|
+
* The `apiKeySource` a Stage's `system/init` event reports when it was billed
|
|
27
|
+
* to the subscription or API key its Run started with. Any other is a Stage
|
|
28
|
+
* billed somewhere the Run did not choose: a key an `apiKeyHelper` in the
|
|
29
|
+
* Host's settings supplied, say, which no environment variable removes.
|
|
30
30
|
*/
|
|
31
31
|
export function expectedKeySource(credential: Credential): string {
|
|
32
32
|
return credential === "api-key" ? API_KEY_ENV_VAR : "none";
|
|
33
33
|
}
|
|
34
34
|
|
|
35
35
|
/**
|
|
36
|
-
* A Stage that reported another `apiKeySource` than
|
|
37
|
-
*
|
|
36
|
+
* A Stage that reported another `apiKeySource` than the one
|
|
37
|
+
* {@link expectedKeySource} gives its Run, which the Run's log and its
|
|
38
|
+
* summary each name.
|
|
38
39
|
*/
|
|
39
40
|
export interface StrayStage {
|
|
40
41
|
ticket: number;
|
|
@@ -49,14 +50,14 @@ export interface StrayStage {
|
|
|
49
50
|
|
|
50
51
|
/**
|
|
51
52
|
* What a Run's Stages were billed, gathered as each comes back and shared by
|
|
52
|
-
* every Ticket, for the Run summary and nothing else: the log and the
|
|
53
|
+
* every Ticket, for the Run summary and nothing else: the log and the progress
|
|
53
54
|
* comment carry no amount.
|
|
54
55
|
*/
|
|
55
56
|
export interface Billing {
|
|
56
|
-
/** Every Stage
|
|
57
|
+
/** Every Stage billed to something other than its Run's subscription or API key, in order. */
|
|
57
58
|
strays: StrayStage[];
|
|
58
59
|
/**
|
|
59
|
-
* The
|
|
60
|
+
* The spend, in dollars: the CLI's figures for the Stages of an `--api-key`
|
|
60
61
|
* Run that ran on the Run's own key, added up, which is the amount that key's
|
|
61
62
|
* Console can be checked against. Always zero on a subscription Run, whose
|
|
62
63
|
* figure is an estimate at API prices and not money spent.
|
|
@@ -65,7 +66,7 @@ export interface Billing {
|
|
|
65
66
|
/**
|
|
66
67
|
* Whether a Stage that ran on the Run's own key reported no figure, or only
|
|
67
68
|
* part of its session's — one the wall-clock limit stopped or that crashed —
|
|
68
|
-
* so the
|
|
69
|
+
* so the spend is at least {@link spendUsd}.
|
|
69
70
|
*/
|
|
70
71
|
spendUnreported: boolean;
|
|
71
72
|
/** Whether any Stage said it ran on the subscription's extra usage. */
|
|
@@ -94,8 +95,8 @@ export interface StageBilling {
|
|
|
94
95
|
* a stray where it ran on something else.
|
|
95
96
|
*
|
|
96
97
|
* A Stage that reported no `apiKeySource` printed no `system/init` event and so
|
|
97
|
-
* made no request: it is no stray, adds no
|
|
98
|
-
* stray's figure stays on its own row and out of the
|
|
98
|
+
* made no request: it is no stray, adds no spend and leaves the spend exact. A
|
|
99
|
+
* stray's figure stays on its own row and out of the spend, which is the Run's
|
|
99
100
|
* own key's alone.
|
|
100
101
|
*/
|
|
101
102
|
export function recordStage(
|
package/src/criteria.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Ticking the Acceptance Criteria a
|
|
2
|
+
* Ticking the Acceptance Criteria a verdict proved.
|
|
3
3
|
*
|
|
4
4
|
* A merged Ticket whose checkboxes are all still empty reads as unfinished
|
|
5
5
|
* work, so the criteria verify marked `met` are ticked where they live — the
|
|
@@ -7,59 +7,96 @@
|
|
|
7
7
|
* `unverifiable` criterion is one nobody has evidence for, and a tick would
|
|
8
8
|
* claim otherwise.
|
|
9
9
|
*
|
|
10
|
+
* The verdict answers each criterion by the number the pipeline listed it
|
|
11
|
+
* under, so a met criterion is found again by the checkbox line it was listed
|
|
12
|
+
* as, never by what the verify Stage wrote about it. A Ticket edited between
|
|
13
|
+
* verify and the merge can leave that line reading otherwise, or twice; then
|
|
14
|
+
* nothing is ticked for it, since a box left unticked only says the line moved,
|
|
15
|
+
* where a wrong one claims a criterion was graded that never was.
|
|
16
|
+
*
|
|
10
17
|
* Nothing else in the text is touched. The pipeline is editing a human's
|
|
11
18
|
* writing, so it rewrites three characters of a line it recognises and leaves
|
|
12
19
|
* the line, and the document around it, as it found them.
|
|
13
20
|
*/
|
|
14
21
|
|
|
15
|
-
import {
|
|
22
|
+
import { UNCHECKED_BOX } from "./acceptance-criteria.js";
|
|
16
23
|
import type { Tracker } from "./ports/tracker.js";
|
|
17
24
|
import type { Verdict } from "./verdict.js";
|
|
18
25
|
|
|
19
|
-
/** {@link UNCHECKED_BOX},
|
|
20
|
-
const CHECKBOX_LINE = new RegExp(`${UNCHECKED_BOX}(
|
|
26
|
+
/** {@link UNCHECKED_BOX}, over every line of a text, capturing the rest of the line. */
|
|
27
|
+
const CHECKBOX_LINE = new RegExp(`${UNCHECKED_BOX}(.*)$`, "gm");
|
|
21
28
|
|
|
22
|
-
/**
|
|
23
|
-
|
|
29
|
+
/** A met criterion, as ticking needs it: its number, and the line it was listed as. */
|
|
30
|
+
export interface MetCriterion {
|
|
31
|
+
number: number;
|
|
32
|
+
line: string;
|
|
33
|
+
}
|
|
24
34
|
|
|
25
|
-
/**
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
* Ticket unticked. Whitespace and case are the differences worth forgiving;
|
|
31
|
-
* anything more and the risk is ticking a box nobody graded.
|
|
32
|
-
*/
|
|
33
|
-
function normalise(text: string): string {
|
|
34
|
-
return text.trim().replaceAll(/\s+/g, " ").toLowerCase();
|
|
35
|
+
/** A met criterion nothing was ticked for, and how many unticked lines read as its own. */
|
|
36
|
+
export interface Untickable {
|
|
37
|
+
number: number;
|
|
38
|
+
/** 0 when no line reads so any more, 2 or more when it is no longer one line. */
|
|
39
|
+
matching: number;
|
|
35
40
|
}
|
|
36
41
|
|
|
37
42
|
/**
|
|
38
|
-
* `
|
|
43
|
+
* `texts` with the unticked box of each criterion in `met` ticked, the texts
|
|
44
|
+
* being every place one Ticket writes its criteria: its body and its comments.
|
|
45
|
+
*
|
|
46
|
+
* A criterion is ticked on the one unticked checkbox line, across all the
|
|
47
|
+
* texts together, that reads as the line it was listed as, trailing spaces
|
|
48
|
+
* aside. None is ticked when no line, or more than one, reads so.
|
|
39
49
|
*
|
|
40
|
-
* Returns
|
|
41
|
-
* knows there is nothing to write back.
|
|
50
|
+
* Returns each text unchanged when nothing in it was ticked, which is how the
|
|
51
|
+
* caller knows there is nothing to write back.
|
|
42
52
|
*/
|
|
43
|
-
export function tickCriteria(
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
53
|
+
export function tickCriteria(
|
|
54
|
+
texts: readonly string[],
|
|
55
|
+
met: readonly MetCriterion[],
|
|
56
|
+
): { texts: string[]; untickable: Untickable[] } {
|
|
57
|
+
const open = texts.flatMap((text, place) =>
|
|
58
|
+
[...text.matchAll(CHECKBOX_LINE)].map(({ index, 0: line }) => ({
|
|
59
|
+
key: lineKey(place, index),
|
|
60
|
+
line: line.trimEnd(),
|
|
61
|
+
})),
|
|
49
62
|
);
|
|
63
|
+
|
|
64
|
+
const chosen = new Set<string>();
|
|
65
|
+
const untickable: Untickable[] = [];
|
|
66
|
+
for (const criterion of met) {
|
|
67
|
+
const wanted = criterion.line.trimEnd();
|
|
68
|
+
const matches = open.filter((line) => line.line === wanted);
|
|
69
|
+
const [only] = matches;
|
|
70
|
+
if (matches.length === 1 && only !== undefined) chosen.add(only.key);
|
|
71
|
+
else untickable.push({ number: criterion.number, matching: matches.length });
|
|
72
|
+
}
|
|
73
|
+
if (chosen.size === 0) return { texts: [...texts], untickable };
|
|
74
|
+
|
|
75
|
+
return {
|
|
76
|
+
texts: texts.map((text, place) =>
|
|
77
|
+
text.replaceAll(CHECKBOX_LINE, (line, bullet: string, rest: string, index: number) =>
|
|
78
|
+
chosen.has(lineKey(place, index)) ? `${bullet}[x]${rest}` : line,
|
|
79
|
+
),
|
|
80
|
+
),
|
|
81
|
+
untickable,
|
|
82
|
+
};
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** One checkbox line on the whole Ticket: which text it is in, and where in it. */
|
|
86
|
+
function lineKey(place: number, index: number): string {
|
|
87
|
+
return `${place}:${index}`;
|
|
50
88
|
}
|
|
51
89
|
|
|
52
90
|
/**
|
|
53
|
-
* Tick every criterion the
|
|
91
|
+
* Tick every criterion the verdict proved, wherever the Ticket writes it.
|
|
54
92
|
*
|
|
55
93
|
* The issue is read again rather than reusing the copy it was claimed with: a
|
|
56
94
|
* whole Run has happened since, and both the body and any comment are written
|
|
57
95
|
* back whole. Triage posts its brief as a comment, and nothing says all the
|
|
58
96
|
* criteria are in one place, so every comment is offered the same edit.
|
|
59
97
|
*
|
|
60
|
-
* A criterion
|
|
61
|
-
*
|
|
62
|
-
* merged Ticket with an unticked criterion is otherwise a mystery.
|
|
98
|
+
* A met criterion left unticked is said out loud rather than passed over in
|
|
99
|
+
* silence: a merged Ticket with an unticked criterion is otherwise a mystery.
|
|
63
100
|
*/
|
|
64
101
|
export async function tickMetCriteria(
|
|
65
102
|
tracker: Tracker,
|
|
@@ -67,40 +104,53 @@ export async function tickMetCriteria(
|
|
|
67
104
|
verdict: Verdict,
|
|
68
105
|
log?: (line: string) => void,
|
|
69
106
|
): Promise<void> {
|
|
70
|
-
const met = verdict.criteria
|
|
71
|
-
.filter((criterion) => criterion.status === "met")
|
|
72
|
-
.map((criterion) => criterion.text);
|
|
107
|
+
const met = verdict.criteria.filter((criterion) => criterion.status === "met");
|
|
73
108
|
if (met.length === 0) return;
|
|
74
109
|
|
|
75
110
|
const issue = await tracker.getIssue(ticket);
|
|
76
|
-
|
|
111
|
+
const { texts, untickable } = tickCriteria(
|
|
112
|
+
[issue.body, ...issue.comments.map((comment) => comment.body)],
|
|
113
|
+
met,
|
|
114
|
+
);
|
|
115
|
+
const [body = issue.body, ...comments] = texts;
|
|
116
|
+
const unwritten: number[] = [];
|
|
77
117
|
|
|
78
|
-
|
|
79
|
-
if (body !== issue.body) {
|
|
80
|
-
await tracker.updateIssueBody(ticket, body);
|
|
81
|
-
ticked += ticks(issue.body, body);
|
|
82
|
-
}
|
|
118
|
+
if (body !== issue.body) await tracker.updateIssueBody(ticket, body);
|
|
83
119
|
|
|
84
|
-
for (const comment of issue.comments) {
|
|
85
|
-
const edited =
|
|
86
|
-
if (edited === comment.body
|
|
120
|
+
for (const [place, comment] of issue.comments.entries()) {
|
|
121
|
+
const edited = comments[place] ?? comment.body;
|
|
122
|
+
if (edited === comment.body) continue;
|
|
123
|
+
if (comment.id === undefined) {
|
|
124
|
+
unwritten.push(...ticksIn(comment.body, edited, met));
|
|
125
|
+
continue;
|
|
126
|
+
}
|
|
87
127
|
await tracker.updateComment(comment.id, edited);
|
|
88
|
-
ticked += ticks(comment.body, edited);
|
|
89
128
|
}
|
|
90
129
|
|
|
91
|
-
|
|
130
|
+
const missed = [
|
|
131
|
+
...untickable.map(({ number, matching }) =>
|
|
132
|
+
matching === 0
|
|
133
|
+
? `criterion ${number}, which no unticked line reads as any more`
|
|
134
|
+
: `criterion ${number}, which ${matching} unticked lines read as`,
|
|
135
|
+
),
|
|
136
|
+
...unwritten.map((number) => `criterion ${number}, in a comment it cannot edit`),
|
|
137
|
+
];
|
|
138
|
+
if (missed.length > 0) {
|
|
92
139
|
log?.(
|
|
93
|
-
`#${ticket} ticked ${
|
|
94
|
-
|
|
140
|
+
`#${ticket} ticked ${met.length - missed.length} of ${met.length} met criteria; ` +
|
|
141
|
+
`left unticked: ${missed.join("; ")}`,
|
|
95
142
|
);
|
|
96
143
|
}
|
|
97
144
|
}
|
|
98
145
|
|
|
99
|
-
/**
|
|
100
|
-
function
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
146
|
+
/** The numbers of the criteria in `met` whose line an edit ticked, which leaves the line count as it was. */
|
|
147
|
+
function ticksIn(before: string, after: string, met: readonly MetCriterion[]): number[] {
|
|
148
|
+
const now = after.split("\n");
|
|
149
|
+
const changed = before
|
|
150
|
+
.split("\n")
|
|
151
|
+
.filter((line, index) => line !== now[index])
|
|
152
|
+
.map((line) => line.trimEnd());
|
|
153
|
+
return met
|
|
154
|
+
.filter((criterion) => changed.includes(criterion.line.trimEnd()))
|
|
155
|
+
.map((criterion) => criterion.number);
|
|
106
156
|
}
|