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