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.
Files changed (50) hide show
  1. package/README.ko.md +5 -5
  2. package/README.md +4 -4
  3. package/docs/templates/operator-skill.md +81 -16
  4. package/package.json +1 -1
  5. package/src/acceptance-criteria.ts +99 -2
  6. package/src/adapters/claude-agent-runner.ts +5 -5
  7. package/src/adapters/exec.ts +32 -4
  8. package/src/adapters/gh-tracker.ts +276 -60
  9. package/src/adapters/git-workspace.ts +27 -10
  10. package/src/adapters/liveness.ts +77 -0
  11. package/src/adapters/process-tree.ts +4 -7
  12. package/src/adapters/version.ts +5 -5
  13. package/src/branch.ts +1 -1
  14. package/src/cli.ts +2 -2
  15. package/src/config.ts +22 -4
  16. package/src/conventions.ts +22 -19
  17. package/src/credential.ts +14 -13
  18. package/src/criteria.ts +102 -52
  19. package/src/failing-base.ts +7 -7
  20. package/src/failure-message.ts +72 -0
  21. package/src/guards.ts +21 -6
  22. package/src/handoff.ts +2 -2
  23. package/src/init.ts +8 -8
  24. package/src/landing.ts +1 -1
  25. package/src/lifecycle.ts +2 -2
  26. package/src/lock.ts +10 -2
  27. package/src/note-schema.ts +14 -11
  28. package/src/notes.ts +19 -7
  29. package/src/operator-skill.ts +2 -2
  30. package/src/orchestrator.ts +758 -275
  31. package/src/outside-fault.ts +103 -0
  32. package/src/ports/agent-runner.ts +1 -1
  33. package/src/ports/tracker.ts +29 -15
  34. package/src/ports/workspace.ts +52 -24
  35. package/src/progress.ts +42 -7
  36. package/src/prompts.ts +242 -34
  37. package/src/readiness.ts +11 -11
  38. package/src/remove.ts +7 -7
  39. package/src/resume.ts +28 -20
  40. package/src/run-log.ts +5 -5
  41. package/src/run.ts +55 -13
  42. package/src/staleness.ts +14 -14
  43. package/src/start.ts +29 -16
  44. package/src/stranded.ts +19 -19
  45. package/src/templates.ts +398 -149
  46. package/src/title.ts +106 -8
  47. package/src/transcript-home.ts +49 -0
  48. package/src/verdict.ts +132 -27
  49. package/src/version-number.ts +13 -13
  50. 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.groups].some((group) => alive(-group)) || [...tree.pids].some(alive);
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 | 0): boolean {
217
+ function send(id: number, name: NodeJS.Signals): boolean {
221
218
  try {
222
219
  process.kill(id, name);
223
220
  return true;
@@ -4,11 +4,11 @@ import { fileURLToPath } from "node:url";
4
4
  import { exec } from "./exec.js";
5
5
 
6
6
  /**
7
- * Which Version this copy of the pipeline is (ADR-0007).
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 Progress comment, each State file, the file beside its
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 Version, as everything this Run writes will report it.
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 Version is out. It is
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 Version. */
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 Base branch,
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, State files and transcripts all
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 Version would be published on, read from the same
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 Version doing 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 Version refused it.
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
- * Version added, and on a machine running a stale install the two look exactly
216
- * the same. So the Version is said out loud, and the config file itself is left
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 {
@@ -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
- * The one thing it says about Versions is the mark it bears: which pipeline
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 Version, as the first line of the document ends.
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 Version writing it.
55
+ * the version writing it.
50
56
  *
51
57
  * The number alone, never the commit a development checkout adds: two checkouts
52
- * of one Version write one document, and a Target whose copy was rewritten by
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 Version number a Target's copy was written by, and undefined for a copy
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 Version changes. */
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
- - A commit subject describes its own commit. The whole branch is summarised by the \`title\` the implement and fix Stages each answer beside their Notes: one line in the same shape. The latest one becomes the pull request title, and the pull request title becomes the subject of the squash commit that lands.
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 State of every Ticket a Run can resume, and the transcripts of a handed-off Ticket's Stages. Nothing else commits to either, except a human, or an Operator a human asked, releasing a lock a vanished Host left behind.
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. They are the only thing the verify Stage grades, so a promise written as prose is not one.
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 Base branch. One that fails there too is the Base branch's, not the Ticket's, so the Ticket is released without spending its Fix budget, 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.
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, the Claude session a human opens on this repository from the Claude app, how to start a Run, report on it and stop it. \`ticket-runner init\` writes it and rewrites it like this file, so an edit made there does not survive the next \`init\` either.
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 Base branch, made to run a failing Check there once and removed when it has run.
118
- - \`.ticket-runner/\` — the Run's logs and Stage transcripts. The Run lock and the State 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.
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
- /** The credential, as the Run summary's header and the log name it. */
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 ran on the
27
- * Run's credential. Any other is a Stage billed somewhere the Run did not
28
- * choose: a key an `apiKeyHelper` in the Host's settings supplied, say, which
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 its Run's credential
37
- * expects, which the Run's log and its summary each name.
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 Progress
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 that ran on something other than the Run's credential, in order. */
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 Spend, in dollars: the CLI's figures for the Stages of an `--api-key`
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 Spend is at least {@link spendUsd}.
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 Spend and leaves the Spend exact. A
98
- * stray's figure stays on its own row and out of the Spend, which is the Run's
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 Verdict proved.
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 { TICKED_BOX, UNCHECKED_BOX } from "./acceptance-criteria.js";
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}, extended to capture the criterion text after the box. */
20
- const CHECKBOX_LINE = new RegExp(`${UNCHECKED_BOX}( .*)$`, "gm");
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
- /** {@link TICKED_BOX}, over every line of a text rather than the first. */
23
- const TICKED_LINE = new RegExp(TICKED_BOX, "gm");
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
- * The same criterion as the verify Stage reported it.
27
- *
28
- * The Stage is asked for the criterion verbatim and mostly obliges, but it
29
- * 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.
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
- * `text` with every unticked box whose criterion is in `met` ticked.
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 the text unchanged when nothing matched, which is how the caller
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(text: string, met: string[]): string {
44
- const wanted = new Set(met.map(normalise));
45
- if (wanted.size === 0) return text;
46
-
47
- return text.replaceAll(CHECKBOX_LINE, (line, bullet: string, rest: string) =>
48
- wanted.has(normalise(rest)) ? `${bullet}[x]${rest}` : line,
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 Verdict proved, wherever the Ticket writes it.
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 the Stage reworded past {@link normalise} matches nothing and is
61
- * left as it was, which is said out loud rather than passed over in silence: a
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
- let ticked = 0;
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
- const body = tickCriteria(issue.body, met);
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 = tickCriteria(comment.body, met);
86
- if (edited === comment.body || comment.id === undefined) continue;
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
- if (ticked < met.length) {
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 ${ticked} of ${met.length} met criteria; ` +
94
- "the rest match no checkbox on the Ticket",
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
- /** How many boxes an edit ticked, so a criterion that matched nothing shows up. */
100
- function ticks(before: string, after: string): number {
101
- return countTicked(after) - countTicked(before);
102
- }
103
-
104
- function countTicked(text: string): number {
105
- return [...text.matchAll(TICKED_LINE)].length;
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
  }