ticket-runner 0.6.3 → 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.
Files changed (49) hide show
  1. package/README.ko.md +4 -4
  2. package/README.md +3 -3
  3. package/docs/templates/operator-skill.md +7 -7
  4. package/package.json +1 -1
  5. package/src/acceptance-criteria.ts +2 -2
  6. package/src/adapters/claude-agent-runner.ts +49 -5
  7. package/src/adapters/exec.ts +19 -4
  8. package/src/adapters/gh-tracker.ts +17 -17
  9. package/src/adapters/git-workspace.ts +12 -8
  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 +7 -6
  16. package/src/conventions.ts +23 -20
  17. package/src/credential.ts +92 -7
  18. package/src/criteria.ts +107 -15
  19. package/src/failing-base.ts +7 -7
  20. package/src/failure-message.ts +72 -0
  21. package/src/guards.ts +2 -2
  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 +3 -3
  28. package/src/notes.ts +8 -6
  29. package/src/operator-skill.ts +2 -2
  30. package/src/orchestrator.ts +194 -144
  31. package/src/ports/agent-runner.ts +21 -1
  32. package/src/ports/tracker.ts +14 -13
  33. package/src/ports/workspace.ts +23 -22
  34. package/src/progress.ts +2 -2
  35. package/src/prompts.ts +74 -25
  36. package/src/readiness.ts +11 -11
  37. package/src/remove.ts +7 -7
  38. package/src/resume.ts +12 -12
  39. package/src/run-log.ts +5 -5
  40. package/src/run.ts +72 -10
  41. package/src/staleness.ts +14 -14
  42. package/src/start.ts +20 -15
  43. package/src/stranded.ts +19 -19
  44. package/src/templates.ts +191 -73
  45. package/src/timer.ts +25 -0
  46. package/src/title.ts +45 -9
  47. package/src/verdict.ts +7 -7
  48. package/src/version-number.ts +13 -13
  49. package/src/version-pr.ts +12 -12
@@ -65,7 +65,7 @@ export interface StageRequest {
65
65
  * Whether a Stage that emitted no structured output has failed. Defaults to
66
66
  * true.
67
67
  *
68
- * It is the verify Stage's Verdict that makes it true there: a session that
68
+ * It is the verify Stage's verdict that makes it true there: a session that
69
69
  * graded nothing has done none of its job. A schema that only carries Notes
70
70
  * is a side channel the Stage may have had nothing to put in, and failing a
71
71
  * Ticket over an empty one would be failing it for finding nothing.
@@ -96,6 +96,26 @@ export interface StageResult {
96
96
  * session printed no such event.
97
97
  */
98
98
  apiKeySource?: string;
99
+ /**
100
+ * What the CLI priced the session at, in dollars: the `total_cost_usd` of its
101
+ * last `result` event. A session that woke for background agents repeats the
102
+ * whole session's figure on every waking, so it is read once, never summed.
103
+ * Absent where no `result` event carried one: a session a Stop killed, the
104
+ * wall-clock limit stopped, or that crashed before it.
105
+ */
106
+ costUsd?: number;
107
+ /**
108
+ * Present, and true, when {@link costUsd} is only part of the session's:
109
+ * the session went on past the last `result` event that gave a figure, and
110
+ * was killed or crashed before it gave another, or the wall-clock limit
111
+ * stopped it while it waited for a background agent.
112
+ */
113
+ costIncomplete?: true;
114
+ /**
115
+ * Present, and true, when one of the session's `rate_limit_event`s said it
116
+ * was using the subscription's extra usage (`isUsingOverage`).
117
+ */
118
+ extraUsage?: true;
99
119
  }
100
120
 
101
121
  /**
@@ -40,7 +40,7 @@ export interface Issue {
40
40
  * Whether the issue is closed.
41
41
  *
42
42
  * Only ever asked of a Ticket the pipeline kept local state for: a Run sweeps
43
- * its State files before it does anything else, and a Ticket that has closed
43
+ * its state files before it does anything else, and a Ticket that has closed
44
44
  * since is one there is nothing left to resume.
45
45
  */
46
46
  closed: boolean;
@@ -128,13 +128,14 @@ export interface CreatePullRequest {
128
128
  * The outcome of waiting for a pull request's CI checks. Distinct from a Check,
129
129
  * which is a command the pipeline runs itself (GLOSSARY.md).
130
130
  *
131
- * `none` means the PR has no checks at all, which `gates.ci` treats as a
132
- * failure rather than a silent bypass.
131
+ * `none` means the pull request has no checks at all, which `gates.ci` treats
132
+ * as a failure rather than a silent bypass.
133
133
  *
134
- * `conflicting` means the PR has no checks because GitHub reports it as
135
- * conflicting with the Base branch: GitHub runs no `pull_request` workflow for
136
- * such a PR, so it would otherwise read as `none`. It cannot be merged, so no gate
137
- * lets it through, and it has nothing a fix Stage could act on.
134
+ * `conflicting` means the pull request has no checks because GitHub reports it
135
+ * as conflicting with the base branch: GitHub runs no `pull_request` workflow
136
+ * for such a pull request, so it would otherwise read as `none`. It cannot be
137
+ * merged, so no gate lets it through, and it has nothing a fix Stage could act
138
+ * on.
138
139
  */
139
140
  export type CiOutcome =
140
141
  | { state: "passed" }
@@ -203,21 +204,21 @@ export interface Tracker {
203
204
  */
204
205
  repository(): Promise<string | undefined>;
205
206
  /**
206
- * The tag of the highest Version `repository` has published as a GitHub
207
+ * The tag of the highest version `repository` has published as a GitHub
207
208
  * Release, named `owner/name`, or nothing where GitHub could not be asked.
208
209
  *
209
210
  * Named for the tag rather than for the Release, because a Release in this
210
211
  * codebase is what a Stage the rate limit or an API failure stopped does to
211
212
  * a Ticket (GLOSSARY.md). A published GitHub Release is what makes a tag a
212
- * Version anybody can install, which is why it is the question rather than
213
+ * version anybody can install, which is why it is the question rather than
213
214
  * the tag alone.
214
215
  *
215
216
  * The one method of this port that is not about the Target: it is asked about
216
217
  * the pipeline's own repository, so a Run and `init` can say that a newer
217
- * Version is out. Nothing is ever refused over the answer, so no answer is an
218
+ * version is out. Nothing is ever refused over the answer, so no answer is an
218
219
  * answer — a Target with no network is a Target that works (ADR-0007).
219
220
  *
220
- * Drafts and pre-releases are not published Versions and are not counted. The
221
+ * Drafts and pre-releases are not published versions and are not counted. The
221
222
  * tag comes back as it was cut, `v0.4.0`, because that is what a human would
222
223
  * go and look for.
223
224
  */
@@ -292,7 +293,7 @@ export interface Tracker {
292
293
  /**
293
294
  * Replace an issue's body.
294
295
  *
295
- * Only ever used to tick Acceptance Criteria a Verdict proved, so whatever
296
+ * Only ever used to tick Acceptance Criteria a verdict proved, so whatever
296
297
  * else the body says is read first and written back unchanged.
297
298
  */
298
299
  updateIssueBody(number: number, body: string): Promise<void>;
@@ -318,7 +319,7 @@ export interface Tracker {
318
319
  * Replace the body of an open pull request.
319
320
  *
320
321
  * A Ticket that spends its fix budget is graded twice, and the body carries
321
- * the Verdict a human reads; without this it would keep the Verdict that
322
+ * the verdict a human reads; without this it would keep the verdict that
322
323
  * failed while the squash commit carried the one that passed.
323
324
  */
324
325
  updatePullRequestBody(number: number, body: string): Promise<void>;
@@ -11,7 +11,7 @@ import type { Host } from "../host.js";
11
11
  * Run, and a port that kept its own copy would be a second answer to the same
12
12
  * question.
13
13
  *
14
- * It also keeps the pipeline's own bookkeeping about the Target: the State each
14
+ * It also keeps the pipeline's own bookkeeping about the Target: the state each
15
15
  * resumable Ticket keeps, and the Run lock. Where those live is the adapter's
16
16
  * business (ADR-0004), so nothing above the port says whether they are files,
17
17
  * a branch, or a map in a test.
@@ -46,7 +46,7 @@ export type RebaseState = { resolved: true } | { resolved: false; unresolved: st
46
46
  * behind it.
47
47
  *
48
48
  * A state of the lifecycle, not a Stage — a Stage is a session (GLOSSARY.md), and
49
- * what the State records is what the Ticket has, not what was running. Only these
49
+ * what the state records is what the Ticket has, not what was running. Only these
50
50
  * two, because everything after the implement Stage — the Checks, the rebase,
51
51
  * the pull request, CI and the merge — is re-run from the top by a Run that
52
52
  * resumes at `implemented`, and none of them is worth a state a resume could
@@ -56,16 +56,16 @@ export const REACHED_STATES = ["claimed", "implemented"] as const;
56
56
 
57
57
  export type ReachedState = (typeof REACHED_STATES)[number];
58
58
 
59
- /** The State a Ticket keeps while its branch carries work worth resuming. */
59
+ /** The state a Ticket keeps while its branch carries work worth resuming. */
60
60
  export interface TicketState {
61
- /** Carried in the State as well as its name, so it reads on its own. */
61
+ /** Carried in the state as well as its name, so it reads on its own. */
62
62
  ticket: number;
63
63
  /** The branch the work is on, which the resuming Run uses rather than deriving. */
64
64
  branch: string;
65
65
  /** The state the Ticket had reached, which is where a later Run picks it up. */
66
66
  state: ReachedState;
67
67
  /**
68
- * Whether the Fix budget has been spent. Resuming must not hand the Ticket a
68
+ * Whether the fix budget has been spent. Resuming must not hand the Ticket a
69
69
  * second fix Stage it never earned — except after a hand-off, which records it
70
70
  * unspent, the Ticket having been through a human's hands since.
71
71
  */
@@ -79,21 +79,21 @@ export interface TicketState {
79
79
  * The latest title a Stage answered for the whole branch, which names the
80
80
  * pull request and the squash commit. Without it a Run that resumes after the
81
81
  * Stage that wrote it would fall back to the first commit subject. Absent
82
- * when no Stage has answered one, and in State an earlier pipeline left.
82
+ * when no Stage has answered one, and in state an earlier pipeline left.
83
83
  */
84
84
  title?: string;
85
85
  /**
86
86
  * Whether the Run that takes the Ticket up rebases its branch onto the Base
87
- * branch before its Checks. Set by a Release over a failing Base branch, so
87
+ * branch before its Checks. Set by a Release over a failing base branch, so
88
88
  * a fix a human has landed there meanwhile reaches the branch; absent
89
- * otherwise, and in State an earlier pipeline left.
89
+ * otherwise, and in state an earlier pipeline left.
90
90
  */
91
91
  rebaseFirst?: boolean;
92
- /** The Run that last wrote the State, and when — both for a human reading it. */
92
+ /** The Run that last wrote the state, and when — both for a human reading it. */
93
93
  runId: string;
94
94
  /**
95
- * The Version that wrote the State (ADR-0007). Written on every write, and
96
- * optional when read: State an earlier pipeline left names none, and a
95
+ * The version that wrote the state (ADR-0007). Written on every write, and
96
+ * optional when read: state an earlier pipeline left names none, and a
97
97
  * Ticket claimed before this existed still resumes.
98
98
  */
99
99
  version?: string;
@@ -102,10 +102,10 @@ export interface TicketState {
102
102
  }
103
103
 
104
104
  /**
105
- * What one Ticket's recorded State turned out to be.
105
+ * What one Ticket's recorded state turned out to be.
106
106
  *
107
- * Two cases, where no State at all is a third: State a Run can resume from, and
108
- * State it cannot. The second is the one that most needs saying out loud: its
107
+ * Two cases, where no state at all is a third: state a Run can resume from, and
108
+ * state it cannot. The second is the one that most needs saying out loud: its
109
109
  * Ticket is claimed on the board, so the sweep for Stranded Tickets is the only
110
110
  * thing that could ever have found it (ADR-0007).
111
111
  */
@@ -113,9 +113,9 @@ export type StateFile =
113
113
  | { readable: true; state: TicketState }
114
114
  | {
115
115
  readable: false;
116
- /** Read off where the State was kept, which is the only part of it that parsed. */
116
+ /** Read off where the state was kept, which is the only part of it that parsed. */
117
117
  ticket: number;
118
- /** The Version the State names, where it names one a reader can make out. */
118
+ /** The version the state names, where it names one a reader can make out. */
119
119
  version?: string;
120
120
  };
121
121
 
@@ -389,7 +389,8 @@ export interface Workspace {
389
389
  */
390
390
  readRemoteFile(branch: string, path: string): Promise<string | undefined>;
391
391
  /**
392
- * Delete `branch` on the remote; the PR is merged, so nothing references it.
392
+ * Delete `branch` on the remote; the pull request is merged, so nothing
393
+ * references it.
393
394
  * A branch the remote already deleted, as GitHub does on merge when told to,
394
395
  * counts as deleted without a delete being sent, which a cloud Host could not.
395
396
  */
@@ -402,15 +403,15 @@ export interface Workspace {
402
403
  pullBase(base: string): Promise<void>;
403
404
 
404
405
  /**
405
- * The State `ticket` keeps, when a Run can resume from it.
406
+ * The state `ticket` keeps, when a Run can resume from it.
406
407
  *
407
- * State nothing wrote, and State this pipeline cannot read, are both
408
+ * State nothing wrote, and state this pipeline cannot read, are both
408
409
  * undefined: starting the Ticket over is always safe, and resuming on a guess
409
410
  * is not.
410
411
  */
411
412
  readState(ticket: number): Promise<TicketState | undefined>;
412
413
  /**
413
- * Every Ticket's State, in ascending Ticket number, the unreadable ones
414
+ * Every Ticket's state, in ascending Ticket number, the unreadable ones
414
415
  * included: their Tickets are claimed, and the sweep is what tells a human
415
416
  * they are there.
416
417
  */
@@ -419,12 +420,12 @@ export interface Workspace {
419
420
  writeState(state: TicketState): Promise<void>;
420
421
  /**
421
422
  * Forget `ticket` is resumable, and the transcripts {@link keepTranscripts}
422
- * kept beside its State with it. A Ticket with no State is not an error.
423
+ * kept beside its state with it. A Ticket with no state is not an error.
423
424
  */
424
425
  removeState(ticket: number): Promise<void>;
425
426
  /**
426
427
  * Keep the command lines and transcripts of the Stages Run `runId` ran for
427
- * `ticket` beside its State, where a human can still read them once this
428
+ * `ticket` beside its state, where a human can still read them once this
428
429
  * Host is gone. Asked of a hand-off, and nothing else: a Ticket nobody has to
429
430
  * look into leaves nothing behind.
430
431
  *
package/src/progress.ts CHANGED
@@ -51,7 +51,7 @@ export interface ProgressRow {
51
51
  const NO_ANSWER = "–";
52
52
 
53
53
  export interface ProgressCommentBody {
54
- /** The Version reporting, as every line one Run stamps carries it. */
54
+ /** The version reporting, as every line one Run stamps carries it. */
55
55
  version: string;
56
56
  runId: string;
57
57
  branch: string;
@@ -99,7 +99,7 @@ export function progressComment({
99
99
  *
100
100
  * Every section under the marker, minus the last when it is this Run's own: a
101
101
  * Run that reads the Ticket again rewrites its section rather than starting a
102
- * second. A comment an earlier Version wrote, with one header and one table, is
102
+ * second. A comment an earlier version wrote, with one header and one table, is
103
103
  * one section like any other.
104
104
  */
105
105
  function earlierSections(body: string, runId: string): string {
package/src/prompts.ts CHANGED
@@ -4,11 +4,10 @@
4
4
  * (ADR-0002).
5
5
  */
6
6
 
7
- import { CONVENTIONS_PATH } from "./conventions.js";
8
7
  import type { FailureKind } from "./lifecycle.js";
9
8
  import { OWN_DEFECT } from "./note-schema.js";
10
9
  import { STAGE_ENV_VAR } from "./stage-guard.js";
11
- import { BRANCH_TITLE } from "./title.js";
10
+ import { BRANCH_TITLE, SUBJECT_SHAPE } from "./title.js";
12
11
 
13
12
  /**
14
13
  * Appended to every Stage prompt, the fix Stage included, in every Target. The
@@ -52,6 +51,12 @@ const FINISH_GUIDANCE = `- Never end your turn while uncommitted work waits on a
52
51
  - Leave the worktree clean: commit your work and remove every untracked file that is not ignored and that no commit carries, test output included. The pipeline refuses a worktree holding changes no commit carries.
53
52
  - Keep gitignored files, such as dependencies you installed. The pipeline does not count them against a clean worktree, and deleting them only leaves the next Stage to install them again.`;
54
53
 
54
+ /**
55
+ * What every Stage that commits is told about branches, in one sentence: the
56
+ * pipeline pushes the branch it checked out, so work on any other is lost.
57
+ */
58
+ const NO_OTHER_BRANCH = "Do not create a branch, and do not switch to another.";
59
+
55
60
  /** The Check commands as a prompt names them. */
56
61
  function checkList(checks: readonly string[]): string {
57
62
  return checks.map((command) => `\`${command}\``).join(", ");
@@ -65,7 +70,7 @@ function checkList(checks: readonly string[]): string {
65
70
  * whole suite while it works, and again after each change, pays for runs the
66
71
  * pipeline is about to make anyway: in the logged Runs that was half of an
67
72
  * implement Stage's wall clock. One run after its last commit still catches a
68
- * failure before it spends the Fix budget. implement's comes after the review,
73
+ * failure before it spends the fix budget. implement's comes after the review,
69
74
  * because the review changes code in nearly every Stage.
70
75
  */
71
76
  function codeChecksLine(checks: readonly string[], afterReview: boolean): string {
@@ -81,13 +86,18 @@ function codeChecksLine(checks: readonly string[], afterReview: boolean): string
81
86
  * was already pushed without rewriting it.
82
87
  */
83
88
  const titleGuidance = (base: string) =>
84
- `- Answer a \`title\` beside your Notes: ${BRANCH_TITLE}, in the \`<type>(<scope>): <summary>\` shape \`${CONVENTIONS_PATH}\` states and without the \`(#<n>)\`. It titles the pull request and the squash commit on \`${base}\`, so each commit subject describes only its own commit.`;
89
+ `- Answer a \`title\` beside your Notes: ${BRANCH_TITLE}, in the \`${SUBJECT_SHAPE}\` shape and without the \`(#<n>)\`. It titles the pull request and the squash commit on \`${base}\`, so each commit subject describes only its own commit.`;
85
90
 
86
91
  /**
87
92
  * Guidance appended to every implement Stage, working around known defects of
88
93
  * the `implement` skill in an unattended session.
94
+ *
95
+ * The Ticket's URL is handed to the review explicitly: the review looks for its
96
+ * spec in the commit messages first, the skill does not always pass it on, and
97
+ * commit subjects need not carry the Ticket number.
89
98
  */
90
99
  const implementGuidance = (
100
+ issueUrl: string,
91
101
  base: string,
92
102
  checks: readonly string[],
93
103
  ) => `This session is unattended. Follow this guidance as well as the skill's own:
@@ -95,13 +105,14 @@ const implementGuidance = (
95
105
  - Make an initial commit before running \`/mattpocock-skills:code-review\`, so the reviewed diff is not empty.
96
106
  ${titleGuidance(base)}
97
107
  - The review the skill asks for is \`/mattpocock-skills:code-review\`. Invoke it by that full name: the short name also matches the CLI's own built-in review skill, which runs neither the Standards review nor the Spec review.
108
+ - Pass the review this Ticket's URL, \`${issueUrl}\`, as the spec. It otherwise looks for the spec in the commit messages, which need not name the Ticket, and reviews with no spec without saying so.
98
109
  - Spawn its review sub-agents with \`run_in_background: false\` set explicitly, several in one message so they still run in parallel. Omitting \`run_in_background\` still runs them in the background, and you would then reach your answer before the review has come back.
99
110
  - Do not answer the schema until the review has returned and the fixes you take from it are committed. An answer you have already given does not stop you committing: the pipeline waits for this session to exit before it reads the branch.
100
111
  - A later answer replaces an earlier one, so if you answer again, repeat every Note you still stand by.${codeChecksLine(checks, true)}
101
112
  ${FINISH_GUIDANCE}
102
113
  - Do not spawn nested review agents beyond what the skill itself does.
103
114
  - Do not open pull requests and do not close the issue; the pipeline does both.
104
- - Commit all of your work to the branch that is already checked out.`;
115
+ - Commit all of your work to the branch that is already checked out. ${NO_OTHER_BRANCH}`;
105
116
 
106
117
  /**
107
118
  * Appended to the two Stages that write code, which are the two that meet
@@ -124,14 +135,14 @@ ${noteEntryGuidance(standingNotes)}`;
124
135
  *
125
136
  * The guidance above is written for a Stage that could have fixed what it found
126
137
  * and is told not to. verify could not: it is told to fix nothing in the first
127
- * place, and what it has instead of a commit is a Verdict with a slot per
128
- * Acceptance Criterion. So this says which findings that Verdict already
138
+ * place, and what it has instead of a commit is a verdict with a slot per
139
+ * Acceptance Criterion. So this says which findings that verdict already
129
140
  * carries — every judgement of a criterion — and gives the rest the Notes list,
130
141
  * because a defect outside the criteria has no slot anywhere else.
131
142
  */
132
- const verifyNotesGuidance = (standingNotes?: number) => `Notes for other Tickets: your Verdict grades this Ticket's Acceptance Criteria and nothing else, so anything you find beside them is lost unless you record it as a Note.
143
+ const verifyNotesGuidance = (standingNotes?: number) => `Notes for other Tickets: your verdict grades this Ticket's Acceptance Criteria and nothing else, so anything you find beside them is lost unless you record it as a Note.
133
144
 
134
- - What you make of a criterion belongs in the Verdict. A criterion you judge \`unmet\` or \`unverifiable\` is reported in its own slot with the evidence you gathered, and never in a Note as well.
145
+ - What you make of a criterion belongs in the verdict. A criterion you judge \`unmet\` or \`unverifiable\` is reported in its own slot with the evidence you gathered, and never in a Note as well.
135
146
  - A defect the criteria do not cover is a Note. Your structured output carries a \`notes\` list beside the criteria, and the pipeline posts each entry where a human will meet it.
136
147
  - A Note of yours carries the evidence that the defect is real in its \`evidence\` field, held to the standard you hold a criterion you judge \`unmet\` to. You have the branch and you can run it, so something you suspect but did not demonstrate is not a Note.
137
148
  - Writing the Note is all you do about it: fix nothing, commit nothing, stage nothing, exactly as the rest of your brief says.
@@ -189,6 +200,13 @@ const NEEDS_A_HUMAN =
189
200
  * `unmet` with a human's decision as its evidence, rather than met on a
190
201
  * workaround: the fix Stage it buys is told to commit nothing for it, which is
191
202
  * what hands the question to a human.
203
+ *
204
+ * An `unmet` criterion's evidence states the failure and proposes no fix. The
205
+ * fix Stage reads that evidence first, and in #292 it implemented the patch a
206
+ * verify had proposed word for word and tested only that verify's
207
+ * counterexample; the next verify broke the patch with the next input, while a
208
+ * fix of the cause was open within the Ticket's limit all along. A limit the
209
+ * evidence quotes is still the fix Stage's to know, so it may stay.
192
210
  */
193
211
  const verifyInstructions = (checks: readonly string[]) => `You are the verify Stage of an unattended pipeline. Your job is adversarial: try to prove each Acceptance Criterion is NOT met.
194
212
 
@@ -198,7 +216,8 @@ const verifyInstructions = (checks: readonly string[]) => `You are the verify St
198
216
  - Judge the code as it is. Do not fix anything, and never commit, stage or push. Scratch files are fine; the pipeline discards them.
199
217
  - Mark a criterion \`unverifiable\` only when no evidence can be gathered, never as a substitute for looking.
200
218
  - When a criterion ${NEEDS_A_HUMAN}, mark it \`unmet\` and say in its evidence that a human decision is needed, naming what it collides with. A workaround that sidesteps the collision does not meet it.
201
- - End by emitting the Verdict: one entry per criterion with its status and the evidence you actually gathered.`;
219
+ - An \`unmet\` criterion's evidence states the failure: where it sits, what you ran or read, what you expected, what came back, and the counterexample. It proposes no fix and no direction for one, and neither does what you say about whether a human decision is needed. It may quote a limit the Ticket, a documented decision or another criterion sets, naming where it comes from. A fix written there is what the fix Stage behind you would implement in place of finding the cause. This holds for a criterion's evidence only: a Note's \`next\` still carries the fix.
220
+ - End by emitting the verdict: one entry per criterion with its status and the evidence you actually gathered.`;
202
221
 
203
222
  /** The Checks as the verify Stage is told about them: passed, and not its to run. */
204
223
  function verifyChecksLine(checks: readonly string[]): string {
@@ -208,9 +227,14 @@ function verifyChecksLine(checks: readonly string[]): string {
208
227
 
209
228
  /**
210
229
  * The fix Stage's brief. Sent in for unmet criteria, it is told what to do when
211
- * one of them needs a human decision: commit nothing, which hands the Ticket to
212
- * a human with the criteria and their evidence. Left to itself it worked around
230
+ * one of them needs a human decision: commit nothing and say why in
231
+ * `noCommitReason`, which hands the Ticket to a human with the criteria, their
232
+ * evidence and that reason. Left to itself it worked around
213
233
  * every such criterion it met, and the verify behind it passed the workaround.
234
+ *
235
+ * It is also told to fix the cause the evidence points at, not the patch the
236
+ * evidence may still propose, and to test that fix the way the next verify will
237
+ * attack it, for the reason {@link verifyInstructions} gives.
214
238
  */
215
239
  const fixInstructions = (
216
240
  base: string,
@@ -218,22 +242,39 @@ const fixInstructions = (
218
242
  checks: readonly string[],
219
243
  ) => `You are the fix Stage of an unattended pipeline. The Ticket below is already implemented on the branch you are on, and one gate failed. You are what its fix budget bought, and the budget is spent: a second failure of any kind hands the Ticket to a human.
220
244
 
221
- - Commit your fix on the branch you are on, in this worktree. Do not create a branch, do not open pull requests, and do not close the Ticket.
245
+ - Commit your fix on the branch you are on, in this worktree. ${NO_OTHER_BRANCH} Do not open pull requests, and do not close the Ticket.
222
246
  - Start from the evidence: reproduce the failure, find what actually causes it, and fix that rather than the symptom.
223
- - Where the failure is an unmet Acceptance Criterion, add the regression test that would have caught it and commit it with the fix.${kind === "unmet-criteria" ? HUMAN_DECISION_LINE : ""}
247
+ - Where the failure is an unmet Acceptance Criterion, add the regression test that would have caught it and commit it with the fix.${kind === "unmet-criteria" ? `${UNMET_CAUSE_LINES}${HUMAN_DECISION_LINE}` : ""}
224
248
  - Stay inside this Ticket's Acceptance Criteria and the defects this branch introduced. Anything else you find belongs to another Ticket, not to this session; record it as a Note rather than mending it.${codeChecksLine(checks, false)}
225
249
  ${FINISH_GUIDANCE}
226
- - Write commit subjects in the convention \`${CONVENTIONS_PATH}\` states. The pipeline re-runs the Checks and the verify Stage as soon as you finish.
227
- ${titleGuidance(base)}`;
250
+ - Write commit subjects in the \`${SUBJECT_SHAPE}\` shape. The pipeline re-runs the Checks and the verify Stage as soon as you finish.
251
+ ${titleGuidance(base)}
252
+ ${NO_COMMIT_LINE}`;
253
+
254
+ /**
255
+ * What every fix Stage is told about ending without a new commit, whatever it
256
+ * was sent in for. Ending so hands the Ticket to a human, and the reason the
257
+ * Stage answers is the one thing of what it said that reaches the hand-off:
258
+ * under `--json-schema` a last message in prose stays in the transcript. The
259
+ * implement Stage is not told this: the schema's description is all it reads
260
+ * of the field, so its prompt does not invite it to end without committing.
261
+ */
262
+ const NO_COMMIT_LINE =
263
+ "- If you end without a new commit, say why in `noCommitReason`, in a few sentences: committing nothing hands the Ticket to a human, and the hand-off comment quotes your reason. Otherwise answer it empty.";
264
+
265
+ /** How the fix Stage sent in for unmet criteria reaches and tests a fix of the cause. */
266
+ const UNMET_CAUSE_LINES = `
267
+ - Look for a fix of the cause you found within the scope this Ticket sets before you settle for a narrower one, such as a patch that answers only the counterexample.
268
+ - Before you commit, test your fix with inputs built from the cause you found, of the kind a verify Stage trying to falsify the criterion would try, and not only with the counterexample you were given. Your regression test covers the cause, not only that counterexample.`;
228
269
 
229
270
  /** What the fix Stage sent in for unmet criteria does with one only a human can settle. */
230
271
  const HUMAN_DECISION_LINE = `
231
- - When any unmet criterion ${NEEDS_A_HUMAN}, as the verify Stage's evidence may already say, commit nothing and say why in your last message. Do not work around it: a fix Stage that commits nothing hands the Ticket to a human, with the unmet criteria and their evidence.`;
272
+ - When any unmet criterion ${NEEDS_A_HUMAN}, as the verify Stage's evidence may already say, commit nothing and give your reason in \`noCommitReason\`: which criterion, and what it collides with. Do not work around it: a fix Stage that commits nothing hands the Ticket to a human, with the unmet criteria, their evidence and your reason.`;
232
273
 
233
274
  /**
234
275
  * The conflict Stage's brief. It may reach past the conflicted files only to
235
- * repair what the merge broke there, such as a name the Base branch renamed:
236
- * a Stage that left those red would spend the Fix budget on them. Nothing it
276
+ * repair what the merge broke there, such as a name the base branch renamed:
277
+ * a Stage that left those red would spend the fix budget on them. Nothing it
237
278
  * does may change behaviour the criteria cover, because verify does not run
238
279
  * again after it.
239
280
  */
@@ -246,7 +287,7 @@ const conflictInstructions = (
246
287
  - Where the two sides are compatible, keep both intents. Where they are not, keep the behaviour this Ticket's Acceptance Criteria ask for, and keep \`${base}\`'s everywhere the Ticket is silent.
247
288
  - Resolve, do not redesign. Change a file the conflict did not touch only to repair what the merge itself broke, such as a renamed name or a moved field. Implement nothing new, and change no behaviour this Ticket's Acceptance Criteria cover: verify does not grade the branch again after you.
248
289
  - Leave no conflict marker behind in any file, committed or not.
249
- - Do not push, do not open pull requests, and do not close the Ticket.${conflictChecksLine(checks)}`;
290
+ - ${NO_OTHER_BRANCH} Do not push, do not open pull requests, and do not close the Ticket.${conflictChecksLine(checks)}`;
250
291
 
251
292
  /** The Checks as the conflict Stage is told about them: the pipeline's to run in full. */
252
293
  function conflictChecksLine(checks: readonly string[]): string {
@@ -284,7 +325,7 @@ export function implementPrompt(
284
325
  ): string {
285
326
  return sections([
286
327
  `/mattpocock-skills:implement ${issueUrl}`,
287
- implementGuidance(base, checks),
328
+ implementGuidance(issueUrl, base, checks),
288
329
  stageBoundary(selfHosted),
289
330
  notesGuidance(standingNotes),
290
331
  extraPrompt,
@@ -292,9 +333,9 @@ export function implementPrompt(
292
333
  }
293
334
 
294
335
  /**
295
- * A fresh session with no plugin skill, graded against the Verdict schema.
336
+ * A fresh session with no plugin skill, graded against the verdict schema.
296
337
  *
297
- * `unmetBefore` is the evidence of the Verdict a fix Stage was sent in for, in
338
+ * `unmetBefore` is the evidence of the verdict a fix Stage was sent in for, in
298
339
  * the same Run; a first verify has none. Without it the verify behind a fix
299
340
  * graded the fix on its own terms, and passed a caveat the first one had
300
341
  * counted as unmet.
@@ -355,15 +396,23 @@ export function fixPrompt(
355
396
  ]);
356
397
  }
357
398
 
358
- /** The failure, its kind and its evidence, under a heading naming the kind. */
399
+ /**
400
+ * The failure, its kind and its evidence, under a heading naming the kind. The
401
+ * unmet criteria's evidence is a verify Stage's prose rather than output, and
402
+ * may still propose a fix, so it is read as where to start looking.
403
+ */
359
404
  function failureSection({ kind, summary, evidence }: FixFailure, base: string): string {
360
405
  return outputSection(
361
406
  `## The failure: ${failureSentences(base)[kind]}`,
362
407
  evidence,
363
- summary,
408
+ kind === "unmet-criteria" ? `${summary}\n\n${UNMET_EVIDENCE_LEAD}` : summary,
364
409
  );
365
410
  }
366
411
 
412
+ /** How the fix Stage reads the unmet criteria's evidence, said beside it. */
413
+ const UNMET_EVIDENCE_LEAD =
414
+ "This is the verify Stage's evidence for each unmet criterion. A fix this evidence proposes is a lead, not the answer: find the cause yourself, starting from the failure it states.";
415
+
367
416
  /** The unmet criteria a fix Stage was sent in for, and what meeting them now takes. */
368
417
  function unmetBeforeSection(evidence: string): string {
369
418
  return outputSection(
package/src/readiness.ts CHANGED
@@ -15,13 +15,13 @@ import type { Workspace } from "./ports/workspace.js";
15
15
  * Target it was only asked to work in is the thing `init` exists to keep to one
16
16
  * place — so the refusal names the item and the command that fixes it.
17
17
  *
18
- * Presence and the Version stamp, never content. The conventions document and
18
+ * Presence and the version stamp, never content. The conventions document and
19
19
  * the Operator's skill are the pipeline's own text and change with it, so
20
20
  * comparing either at every start would refuse a Target for carrying last
21
21
  * week's copy, which is a thing the next `init` rewrites and nothing a Run is
22
- * worse for. The document's Version stamp is asked for, though never which
23
- * Version it names: an Operator installs the pipeline a cloud Host runs at that
24
- * Version, and a Target without one leaves it guessing (ADR-0008).
22
+ * worse for. The document's version stamp is asked for, though never which
23
+ * version it names: an Operator installs the pipeline a cloud Host runs at that
24
+ * version, and a Target without one leaves it guessing (ADR-0008).
25
25
  *
26
26
  * The checkout's files are read here rather than through a port, which every
27
27
  * external effect of a Run goes through. What a port buys is a fake to drive the
@@ -30,7 +30,7 @@ import type { Workspace } from "./ports/workspace.js";
30
30
  * from a temporary repository root, which is how the local state under
31
31
  * `.ticket-runner/` is tested too (ADR-0004).
32
32
  *
33
- * The same files on the remote's Base branch are the one exception, read
33
+ * The same files on the remote's base branch are the one exception, read
34
34
  * through `Workspace` like every other question about the remote: every
35
35
  * Ticket's worktree is made from that branch, so a file `init` wrote and nobody
36
36
  * pushed is in the checkout and in no Stage's worktree. The conventions
@@ -159,7 +159,7 @@ export interface ReadinessOptions {
159
159
  * next, so a Host without it is refused in words rather than with the spawn
160
160
  * error the first label lookup would crash on.
161
161
  *
162
- * What the remote's Base branch lacks is asked after all of these, by
162
+ * What the remote's base branch lacks is asked after all of these, by
163
163
  * {@link unpushedRefusal}, once the Run has resolved which branch that is: the
164
164
  * lookup may ask GitHub, which only a `gh` that runs can.
165
165
  */
@@ -184,17 +184,17 @@ export async function readinessRefusal({
184
184
 
185
185
  export interface UnpushedOptions {
186
186
  workspace: Pick<Workspace, "remote" | "readRemoteFile">;
187
- /** The Run's Base branch, resolved once and carried on into the Run. */
187
+ /** The Run's base branch, resolved once and carried on into the Run. */
188
188
  baseBranch: string;
189
189
  }
190
190
 
191
191
  /**
192
- * The message a Run is refused with when the remote's Base branch lacks a file
192
+ * The message a Run is refused with when the remote's base branch lacks a file
193
193
  * the checkout has, and nothing when it has them all.
194
194
  *
195
195
  * Asked once {@link readinessRefusal} has found nothing missing, so a Target
196
196
  * that never ran `init` is told to run it and only one that did is told to
197
- * push. A Base branch the remote does not have lacks every file. The remedy is
197
+ * push. A base branch the remote does not have lacks every file. The remedy is
198
198
  * a commit and a push, which `init` leaves to the human, so this names no
199
199
  * command of the pipeline's.
200
200
  */
@@ -224,7 +224,7 @@ async function missingFileMessage(repoRoot: string): Promise<string | undefined>
224
224
  }
225
225
 
226
226
  /**
227
- * Names the first of the items both the checkout and the remote's Base branch
227
+ * Names the first of the items both the checkout and the remote's base branch
228
228
  * must carry that `read` does not find, asking each the same question in both
229
229
  * places. Where it was asked is the refusal's to say.
230
230
  */
@@ -236,7 +236,7 @@ async function missingItemMessage(
236
236
  return `\`${CONVENTIONS_PATH}\` is not there`;
237
237
  }
238
238
  if (conventionsMark(conventions) === undefined) {
239
- return `\`${CONVENTIONS_PATH}\` carries no Version`;
239
+ return `\`${CONVENTIONS_PATH}\` carries no version`;
240
240
  }
241
241
 
242
242
  if (!hasClaudePointer(await read(CLAUDE_FILENAME))) {
package/src/remove.ts CHANGED
@@ -65,7 +65,7 @@ const FAIL = "✗";
65
65
 
66
66
  export interface RemoveOptions {
67
67
  repoRoot: string;
68
- /** The Version doing the removing, which the report's first line names (ADR-0007). */
68
+ /** The version doing the removing, which the report's first line names (ADR-0007). */
69
69
  version: string;
70
70
  /** Read before anything is removed, because it names the in-progress label. */
71
71
  config: Config;
@@ -131,11 +131,11 @@ export async function removeTarget(options: RemoveOptions): Promise<number> {
131
131
  if (nested !== undefined) return refuse(nested);
132
132
 
133
133
  // A cloud Host can delete no ref on the remote (ADR-0008), so it would leave
134
- // the lock and State branches behind whatever else it took out.
134
+ // the lock and state branches behind whatever else it took out.
135
135
  if (hostKind(env) === "cloud") {
136
136
  return refuse(
137
137
  "Refusing to remove on a cloud Host: it can delete no branch on the remote, so the Run" +
138
- " lock and State branches would stay. Run `ticket-runner remove` on a workstation instead.",
138
+ " lock and state branches would stay. Run `ticket-runner remove` on a workstation instead.",
139
139
  );
140
140
  }
141
141
 
@@ -145,14 +145,14 @@ export async function removeTarget(options: RemoveOptions): Promise<number> {
145
145
  return refuse(`Refusing to remove: ${failure} — ${remedy}, then \`ticket-runner remove\` again.`);
146
146
  }
147
147
 
148
- // A newer Version may have put things in the Target this one has never
148
+ // A newer version may have put things in the Target this one has never
149
149
  // heard of, and a removal that left them would report a Target it had not
150
150
  // emptied as done.
151
151
  const newer = newerSetUp(repoRoot, options.version);
152
152
  if (newer !== undefined) {
153
153
  return refuse(
154
154
  `Refusing to remove: ${newer.mark} set this Target up and this is ${newer.own}, so it may` +
155
- ` have left things this Version does not know to remove. Upgrade with \`${UPGRADE_COMMAND}\`,` +
155
+ ` have left things this version does not know to remove. Upgrade with \`${UPGRADE_COMMAND}\`,` +
156
156
  " then run `ticket-runner remove` again.",
157
157
  );
158
158
  }
@@ -406,7 +406,7 @@ interface Removal {
406
406
  /** What it left, and why, where it was one of the things it set out to remove. */
407
407
  left: string[];
408
408
  failed: number;
409
- /** The Tickets whose State files went with the state branch. */
409
+ /** The Tickets whose state files went with the state branch. */
410
410
  states: number[];
411
411
  }
412
412
 
@@ -654,7 +654,7 @@ async function leftForYou(
654
654
  if (states.length > 0) {
655
655
  lines.push(
656
656
  `${states.map((ticket) => `#${ticket}`).join(", ")}: no Run can resume ${states.length === 1 ? "it" : "them"}` +
657
- ` any more, because ${states.length === 1 ? "its State file" : "their State files"}, and any` +
657
+ ` any more, because ${states.length === 1 ? "its state file" : "their state files"}, and any` +
658
658
  ` hand-off transcripts kept beside ${states.length === 1 ? "it" : "them"}, went with \`${STATE_BRANCH}\``,
659
659
  );
660
660
  }