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
package/src/prompts.ts CHANGED
@@ -4,11 +4,12 @@
4
4
  * (ADR-0002).
5
5
  */
6
6
 
7
- import { CONVENTIONS_PATH } from "./conventions.js";
7
+ import type { ListedCriterion } from "./acceptance-criteria.js";
8
8
  import type { FailureKind } from "./lifecycle.js";
9
- import { OWN_DEFECT } from "./note-schema.js";
9
+ import { BRANCH_DEFECT, OWN_DEFECT } from "./note-schema.js";
10
+ import { NOTE_PARTS, type WrittenNote } from "./notes.js";
10
11
  import { STAGE_ENV_VAR } from "./stage-guard.js";
11
- import { BRANCH_TITLE } from "./title.js";
12
+ import { BRANCH_PROSE_FIELDS, BRANCH_TITLE, type BranchProse, SUBJECT_SHAPE } from "./title.js";
12
13
 
13
14
  /**
14
15
  * Appended to every Stage prompt, the fix Stage included, in every Target. The
@@ -52,6 +53,12 @@ const FINISH_GUIDANCE = `- Never end your turn while uncommitted work waits on a
52
53
  - 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
54
  - 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
55
 
56
+ /**
57
+ * What every Stage that commits is told about branches, in one sentence: the
58
+ * pipeline pushes the branch it checked out, so work on any other is lost.
59
+ */
60
+ const NO_OTHER_BRANCH = "Do not create a branch, and do not switch to another.";
61
+
55
62
  /** The Check commands as a prompt names them. */
56
63
  function checkList(checks: readonly string[]): string {
57
64
  return checks.map((command) => `\`${command}\``).join(", ");
@@ -65,7 +72,7 @@ function checkList(checks: readonly string[]): string {
65
72
  * whole suite while it works, and again after each change, pays for runs the
66
73
  * pipeline is about to make anyway: in the logged Runs that was half of an
67
74
  * 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,
75
+ * failure before it spends the fix budget. implement's comes after the review,
69
76
  * because the review changes code in nearly every Stage.
70
77
  */
71
78
  function codeChecksLine(checks: readonly string[], afterReview: boolean): string {
@@ -81,7 +88,51 @@ function codeChecksLine(checks: readonly string[], afterReview: boolean): string
81
88
  * was already pushed without rewriting it.
82
89
  */
83
90
  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.`;
91
+ `- Answer a \`title\` beside your Notes: ${BRANCH_TITLE}, in the \`${SUBJECT_SHAPE}\` shape and without the \`(#<n>)\`. It titles the pull request and the squash commit on \`${base}\`, so each commit subject describes only its own commit.`;
92
+
93
+ /**
94
+ * Where the pull request body's shape comes from. A Target's own rules come
95
+ * first: a Stage reads its instructions anyway, so ignoring them would leave it
96
+ * two conflicting orders. The `pr` skill is named by its full name, because a
97
+ * short name may match a skill of the Target's own.
98
+ */
99
+ const BODY_SHAPE =
100
+ "in the shape this repository's contributing guide or its `.github/PULL_REQUEST_TEMPLATE.md` sets, when either sets a pull request body's sections or content beyond the `Closes` line; where neither does, invoke `/mattpocock-skills:pr` by that full name and write it in that skill's shape";
101
+
102
+ /**
103
+ * How the problem and the solution read. The shape is stated here rather than
104
+ * pointed at, because the skill it comes from is a personal one, not part of
105
+ * the plugin a Target installs.
106
+ */
107
+ const PROSE_SHAPE =
108
+ "as this repository's contributing guide sets a commit body, when it does; where it does not, the problem is the state before the change and its effect, and the solution is what the change does and why, each in at most two sentences, readable without opening the Ticket, leaving out what the diff and the body already show, such as side changes and individual names";
109
+
110
+ /**
111
+ * What none of the three may carry. They are published on the Target's
112
+ * repository, and the pipeline writes the one `Closes #<n>` itself, so a
113
+ * second closing keyword could close an issue nobody meant to.
114
+ */
115
+ const PROSE_LIMITS =
116
+ "None of the three carries a title, a closing keyword (`Closes`, `Fixes`, `Resolves`) before an issue reference, a screenshot or a local path: they are published on this repository, and the pipeline writes the one `Closes #<n>` itself.";
117
+
118
+ /**
119
+ * How the implement Stage is told to answer the body, the problem and the
120
+ * solution: once, for the whole branch, after the review that changes it.
121
+ */
122
+ const PROSE_GUIDANCE = `- Once the review's fixes are committed, answer a \`body\`, a \`problem\` and a \`solution\` beside \`title\`, each written for the whole branch. The \`body\` is the pull request's body below the \`Closes #<n>\` line the pipeline writes: write it ${BODY_SHAPE}. The \`problem\` and the \`solution\` open the squash commit's body, so \`git log\` says why without the Ticket: write them ${PROSE_SHAPE}. ${PROSE_LIMITS}`;
123
+
124
+ /**
125
+ * The language a Stage writes its answers in. A Stage left to itself wrote
126
+ * English on a Target whose issues and commits are in another language. The
127
+ * criterion's text is the exception: it is the Ticket's, quoted.
128
+ */
129
+ const languageLine = (answers: string) =>
130
+ `- Write ${answers} in the language this repository's contributing guide sets for issues and commits, and where it sets none, in the language the Ticket is written in. A criterion's text stays as the Ticket writes it.`;
131
+
132
+ /** What the two Stages that write code answer in the Target's language. */
133
+ const CODE_STAGE_LANGUAGE = languageLine(
134
+ "your Notes, `title`, `body`, `problem`, `solution` and `noCommitReason`",
135
+ );
85
136
 
86
137
  /**
87
138
  * Guidance appended to every implement Stage, working around known defects of
@@ -99,6 +150,8 @@ const implementGuidance = (
99
150
 
100
151
  - Make an initial commit before running \`/mattpocock-skills:code-review\`, so the reviewed diff is not empty.
101
152
  ${titleGuidance(base)}
153
+ ${PROSE_GUIDANCE}
154
+ ${CODE_STAGE_LANGUAGE}
102
155
  - The review the skill asks for is \`/mattpocock-skills:code-review\`. Invoke it by that full name: the short name also matches the CLI's own built-in review skill, which runs neither the Standards review nor the Spec review.
103
156
  - Pass the review this Ticket's URL, \`${issueUrl}\`, as the spec. It otherwise looks for the spec in the commit messages, which need not name the Ticket, and reviews with no spec without saying so.
104
157
  - Spawn its review sub-agents with \`run_in_background: false\` set explicitly, several in one message so they still run in parallel. Omitting \`run_in_background\` still runs them in the background, and you would then reach your answer before the review has come back.
@@ -107,7 +160,7 @@ ${titleGuidance(base)}
107
160
  ${FINISH_GUIDANCE}
108
161
  - Do not spawn nested review agents beyond what the skill itself does.
109
162
  - Do not open pull requests and do not close the issue; the pipeline does both.
110
- - Commit all of your work to the branch that is already checked out.`;
163
+ - Commit all of your work to the branch that is already checked out. ${NO_OTHER_BRANCH}`;
111
164
 
112
165
  /**
113
166
  * Appended to the two Stages that write code, which are the two that meet
@@ -130,15 +183,16 @@ ${noteEntryGuidance(standingNotes)}`;
130
183
  *
131
184
  * The guidance above is written for a Stage that could have fixed what it found
132
185
  * and is told not to. verify could not: it is told to fix nothing in the first
133
- * place, and what it has instead of a commit is a Verdict with a slot per
134
- * Acceptance Criterion. So this says which findings that Verdict already
135
- * carries — every judgement of a criterion — and gives the rest the Notes list,
136
- * because a defect outside the criteria has no slot anywhere else.
186
+ * place, and what it has instead of a commit is a verdict with a slot per
187
+ * Acceptance Criterion and a list of the defects the branch made. So this says
188
+ * which findings that verdict already carries and gives the rest the Notes
189
+ * list, because a defect that is not the branch's has no slot anywhere else.
137
190
  */
138
- 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.
191
+ const verifyNotesGuidance = (standingNotes?: number) => `Notes for other Tickets: your verdict carries what you make of each criterion and every defect this branch made, so anything else you find is lost unless you record it as a Note.
139
192
 
140
- - 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.
141
- - 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.
193
+ - What you make of a criterion belongs in the verdict. A criterion you judge \`unmet\` or \`unverifiable\` is reported in its own slot with the evidence you gathered, and never in a Note as well.
194
+ - A defect this branch made belongs in the verdict's \`defects\`, never in a Note, and so does one among the Notes this Ticket's implement and fix Stages wrote.
195
+ - Any other defect is a Note. Your structured output carries a \`notes\` list beside the criteria, and the pipeline posts each entry where a human will meet it.
142
196
  - A Note of yours carries the evidence that the defect is real in its \`evidence\` field, held to the standard you hold a criterion you judge \`unmet\` to. You have the branch and you can run it, so something you suspect but did not demonstrate is not a Note.
143
197
  - Writing the Note is all you do about it: fix nothing, commit nothing, stage nothing, exactly as the rest of your brief says.
144
198
  ${noteEntryGuidance(standingNotes)}`;
@@ -155,6 +209,7 @@ ${noteEntryGuidance(standingNotes)}`;
155
209
  * to write more.
156
210
  */
157
211
  const noteEntryGuidance = (standingNotes?: number) => `- A Note is a defect — something that behaves wrongly or breaks. A preference of yours, a refactor you would enjoy and a test that would be nice to have are not Notes, however right you are about them.
212
+ - What this Ticket's own deliverable already records is not a Note either, such as a finding in the report section the Ticket asks for.
158
213
  - Set \`ticket\` to the issue number the Note belongs to, and leave it out when you are not sure which one: a Note with no number becomes a comment on the issue the pipeline gathers Notes for triage on, where a wrong number lands on somebody else's Ticket.
159
214
  - Write each Note in its parts: \`summary\` is one short sentence naming the defect; \`evidence\` is where the defect is and what shows it is real, what you ran or read, what you expected and what came back; \`impact\` is what breaks, and for whom; \`next\` is the fix, or the decision a human has to take before anyone can fix it, and is left out when there is neither.
160
215
  - Write every part as plain sentences. No checkboxes: they would read as Acceptance Criteria.
@@ -195,16 +250,34 @@ const NEEDS_A_HUMAN =
195
250
  * `unmet` with a human's decision as its evidence, rather than met on a
196
251
  * workaround: the fix Stage it buys is told to commit nothing for it, which is
197
252
  * what hands the question to a human.
253
+ *
254
+ * An `unmet` criterion's evidence states the failure and proposes no fix. The
255
+ * fix Stage reads that evidence first, and in #292 it implemented the patch a
256
+ * verify had proposed word for word and tested only that verify's
257
+ * counterexample; the next verify broke the patch with the next input, while a
258
+ * fix of the cause was open within the Ticket's limit all along. A limit the
259
+ * evidence quotes is still the fix Stage's to know, so it may stay.
260
+ *
261
+ * The criteria are listed by the pipeline and answered by number, so the
262
+ * verdict never has to copy a criterion for anything to find it again.
263
+ *
264
+ * A defect the branch itself made is graded here too, beside the criteria,
265
+ * and fails the verdict as an unmet criterion does. Sent to a Note instead, it
266
+ * merged with the branch that made it, and triage opened a bug Ticket for it
267
+ * within hours.
198
268
  */
199
- const verifyInstructions = (checks: readonly string[]) => `You are the verify Stage of an unattended pipeline. Your job is adversarial: try to prove each Acceptance Criterion is NOT met.
269
+ const verifyInstructions = (checks: readonly string[]) => `You are the verify Stage of an unattended pipeline. Your job is adversarial: try to prove each Acceptance Criterion is NOT met, and find the defects this branch made.
200
270
 
201
- - Read the Ticket's Acceptance Criteria from its body and from its comments; the checkbox list may live in either.
271
+ - The pipeline lists the Ticket's Acceptance Criteria below, numbered, each with the indented lines under its checkbox. Read the Ticket for their context, and grade the criteria as listed: answer each by its number, every listed number once and no other.
202
272
  - Work in the checked-out branch, which already contains the implementation.
203
273
  - Attempt to falsify every criterion: run the code, run the tests that bear on it, and write throwaway tests where that is the only way to tell.${verifyChecksLine(checks)}
204
274
  - Judge the code as it is. Do not fix anything, and never commit, stage or push. Scratch files are fine; the pipeline discards them.
205
275
  - Mark a criterion \`unverifiable\` only when no evidence can be gathered, never as a substitute for looking.
206
276
  - When a criterion ${NEEDS_A_HUMAN}, mark it \`unmet\` and say in its evidence that a human decision is needed, naming what it collides with. A workaround that sidesteps the collision does not meet it.
207
- - End by emitting the Verdict: one entry per criterion with its status and the evidence you actually gathered.`;
277
+ - ${BRANCH_DEFECT}, is reported in the verdict's \`defects\`, beside the criteria and not as a Note, when you show it with the evidence an \`unmet\` criterion needs, unless the Ticket leaves it out of scope or a documented decision accepts it. It fails the verdict as an \`unmet\` criterion does, and its evidence follows the same rule.
278
+ - An \`unmet\` criterion's evidence states the failure: where it sits, what you ran or read, what you expected, what came back, and the counterexample. It proposes no fix and no direction for one, and neither does what you say about whether a human decision is needed. It may quote a limit the Ticket, a documented decision or another criterion sets, naming where it comes from. A fix written there is what the fix Stage behind you would implement in place of finding the cause. This holds for a criterion's evidence only: a Note's \`next\` still carries the fix.
279
+ - End by emitting the verdict: one entry per listed criterion, by its number, with its status and the evidence you actually gathered, and one entry in \`defects\` per defect of this branch you showed.
280
+ ${languageLine("your Notes and the verdict's evidence")}`;
208
281
 
209
282
  /** The Checks as the verify Stage is told about them: passed, and not its to run. */
210
283
  function verifyChecksLine(checks: readonly string[]): string {
@@ -214,9 +287,17 @@ function verifyChecksLine(checks: readonly string[]): string {
214
287
 
215
288
  /**
216
289
  * The fix Stage's brief. Sent in for unmet criteria, it is told what to do when
217
- * one of them needs a human decision: commit nothing, which hands the Ticket to
218
- * a human with the criteria and their evidence. Left to itself it worked around
290
+ * one of them needs a human decision: commit nothing and say why in
291
+ * `noCommitReason`, which hands the Ticket to a human with the criteria, their
292
+ * evidence and that reason. Left to itself it worked around
219
293
  * every such criterion it met, and the verify behind it passed the workaround.
294
+ *
295
+ * It is also told to fix the cause the evidence points at, not the patch the
296
+ * evidence may still propose, and to test that fix the way the next verify will
297
+ * attack it, for the reason {@link verifyInstructions} gives.
298
+ *
299
+ * It drives no plugin skill but the `pr` skill: the implement skill would
300
+ * re-read the Ticket and start over.
220
301
  */
221
302
  const fixInstructions = (
222
303
  base: string,
@@ -224,22 +305,52 @@ const fixInstructions = (
224
305
  checks: readonly string[],
225
306
  ) => `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.
226
307
 
227
- - 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.
308
+ - Commit your fix on the branch you are on, in this worktree. ${NO_OTHER_BRANCH} Do not open pull requests, and do not close the Ticket.
228
309
  - Start from the evidence: reproduce the failure, find what actually causes it, and fix that rather than the symptom.
229
- - 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 : ""}
310
+ - Where the failure is an unmet Acceptance Criterion or a defect this branch made, add the regression test that would have caught it and commit it with the fix.${kind === "unmet-criteria" ? `${UNMET_CAUSE_LINES}${HUMAN_DECISION_LINE}` : ""}
230
311
  - Stay inside this Ticket's Acceptance Criteria and the defects this branch introduced. Anything else you find belongs to another Ticket, not to this session; record it as a Note rather than mending it.${codeChecksLine(checks, false)}
231
312
  ${FINISH_GUIDANCE}
232
- - Write commit subjects in the convention \`${CONVENTIONS_PATH}\` states. The pipeline re-runs the Checks and the verify Stage as soon as you finish.
233
- ${titleGuidance(base)}`;
313
+ - Write commit subjects in the \`${SUBJECT_SHAPE}\` shape. The pipeline re-runs the Checks and the verify Stage as soon as you finish.
314
+ ${titleGuidance(base)}
315
+ ${FIX_PROSE_GUIDANCE}
316
+ ${CODE_STAGE_LANGUAGE}
317
+ - Invoke no plugin skill but \`/mattpocock-skills:pr\`: the implement skill would re-read the Ticket and start over.
318
+ ${NO_COMMIT_LINE}`;
319
+
320
+ /**
321
+ * How the fix Stage is told to answer the body, the problem and the solution:
322
+ * revised for the whole branch where its fix changes what one says, so the
323
+ * before an earlier Stage found is not lost, and blank otherwise, which keeps
324
+ * the earlier one.
325
+ */
326
+ const FIX_PROSE_GUIDANCE = `- The \`body\`, \`problem\` and \`solution\` answered for this branch so far are below, when there are any. When your fix changes what one of them says, answer that one revised for the whole branch, keeping whatever it says of the branch before your fix that still holds: the \`body\` ${BODY_SHAPE}; the \`problem\` and the \`solution\` ${PROSE_SHAPE}. Answer each one your fix leaves true as an empty string, which keeps it. ${PROSE_LIMITS}`;
327
+
328
+ /**
329
+ * What every fix Stage is told about ending without a new commit, whatever it
330
+ * was sent in for. Ending so hands the Ticket to a human, and the reason the
331
+ * Stage answers is the one thing of what it said that reaches the hand-off:
332
+ * under `--json-schema` a last message in prose stays in the transcript. The
333
+ * implement Stage is not told this: its prompt names the field only among the
334
+ * answers it writes in the Target's language, and the schema's description is
335
+ * all it reads of what the field is for, so its prompt does not invite it to
336
+ * end without committing.
337
+ */
338
+ const NO_COMMIT_LINE =
339
+ "- If you end without a new commit, say why in `noCommitReason`, in a few sentences: committing nothing hands the Ticket to a human, and the hand-off comment quotes your reason. Otherwise answer it empty.";
340
+
341
+ /** How the fix Stage sent in for unmet criteria reaches and tests a fix of the cause. */
342
+ const UNMET_CAUSE_LINES = `
343
+ - 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.
344
+ - 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.`;
234
345
 
235
346
  /** What the fix Stage sent in for unmet criteria does with one only a human can settle. */
236
347
  const HUMAN_DECISION_LINE = `
237
- - 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.`;
348
+ - When any unmet criterion ${NEEDS_A_HUMAN}, or any defect cannot be fixed without overturning one, as the verify Stage's evidence may already say, commit nothing and give your reason in \`noCommitReason\`: which criterion or defect, and what it collides with. Do not work around it: a fix Stage that commits nothing hands the Ticket to a human, with the unmet criteria, the defects, their evidence and your reason.`;
238
349
 
239
350
  /**
240
351
  * The conflict Stage's brief. It may reach past the conflicted files only to
241
- * repair what the merge broke there, such as a name the Base branch renamed:
242
- * a Stage that left those red would spend the Fix budget on them. Nothing it
352
+ * repair what the merge broke there, such as a name the base branch renamed:
353
+ * a Stage that left those red would spend the fix budget on them. Nothing it
243
354
  * does may change behaviour the criteria cover, because verify does not run
244
355
  * again after it.
245
356
  */
@@ -252,7 +363,7 @@ const conflictInstructions = (
252
363
  - 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.
253
364
  - 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.
254
365
  - Leave no conflict marker behind in any file, committed or not.
255
- - Do not push, do not open pull requests, and do not close the Ticket.${conflictChecksLine(checks)}`;
366
+ - ${NO_OTHER_BRANCH} Do not push, do not open pull requests, and do not close the Ticket.${conflictChecksLine(checks)}`;
256
367
 
257
368
  /** The Checks as the conflict Stage is told about them: the pipeline's to run in full. */
258
369
  function conflictChecksLine(checks: readonly string[]): string {
@@ -265,7 +376,7 @@ const failureSentences = (base: string): Record<FailureKind, string> => ({
265
376
  "uncommitted-work":
266
377
  "the Stage before you left changes in this worktree it never committed, listed below; commit what belongs to this Ticket and discard the rest",
267
378
  "failed-check": "a Check the pipeline runs itself failed",
268
- "unmet-criteria": "the verify Stage found unmet Acceptance Criteria",
379
+ "unmet-criteria": "the verify Stage found unmet Acceptance Criteria, or defects this branch made",
269
380
  "failed-ci": "a pull request check failed after the branch was pushed",
270
381
  "unresolved-conflict": `the branch conflicts with ${base}, and the session sent in to resolve the rebase did not finish it`,
271
382
  });
@@ -297,10 +408,18 @@ export function implementPrompt(
297
408
  ]);
298
409
  }
299
410
 
411
+ /** What the verify Stage is given to grade beside the Ticket's URL. */
412
+ export interface VerifyBrief {
413
+ /** The Ticket's unticked criteria, numbered, which the verdict answers by number. */
414
+ criteria?: readonly ListedCriterion[];
415
+ /** The Notes this Ticket's implement and fix Stages wrote in this Run. */
416
+ written?: readonly WrittenNote[];
417
+ }
418
+
300
419
  /**
301
- * A fresh session with no plugin skill, graded against the Verdict schema.
420
+ * A fresh session with no plugin skill, graded against the verdict schema.
302
421
  *
303
- * `unmetBefore` is the evidence of the Verdict a fix Stage was sent in for, in
422
+ * `unmetBefore` is the evidence of the verdict a fix Stage was sent in for, in
304
423
  * the same Run; a first verify has none. Without it the verify behind a fix
305
424
  * graded the fix on its own terms, and passed a caveat the first one had
306
425
  * counted as unmet.
@@ -312,11 +431,14 @@ export function verifyPrompt(
312
431
  checks: readonly string[],
313
432
  standingNotes?: number,
314
433
  unmetBefore?: string,
434
+ { criteria = [], written = [] }: VerifyBrief = {},
315
435
  ): string {
316
436
  return sections([
317
437
  `Ticket: ${issueUrl}`,
318
438
  verifyInstructions(checks),
439
+ criteriaSection(criteria),
319
440
  unmetBefore === undefined ? "" : unmetBeforeSection(unmetBefore),
441
+ writtenNotesSection(written),
320
442
  stageBoundary(selfHosted),
321
443
  verifyNotesGuidance(standingNotes),
322
444
  extraPrompt,
@@ -341,7 +463,10 @@ export function conflictPrompt(
341
463
  ]);
342
464
  }
343
465
 
344
- /** A fresh session with no plugin skill, given one failure and told to mend it. */
466
+ /**
467
+ * A fresh session with no plugin skill but the `pr` skill, given one failure
468
+ * and told to mend it, and the body, problem and solution answered so far.
469
+ */
345
470
  export function fixPrompt(
346
471
  issueUrl: string,
347
472
  failure: FixFailure,
@@ -350,35 +475,118 @@ export function fixPrompt(
350
475
  selfHosted: boolean,
351
476
  checks: readonly string[],
352
477
  standingNotes?: number,
478
+ prose: BranchProse = {},
353
479
  ): string {
354
480
  return sections([
355
481
  `Ticket: ${issueUrl}`,
356
482
  fixInstructions(base, failure.kind, checks),
357
483
  failureSection(failure, base),
484
+ proseSection(prose),
358
485
  stageBoundary(selfHosted),
359
486
  notesGuidance(standingNotes),
360
487
  extraPrompt,
361
488
  ]);
362
489
  }
363
490
 
364
- /** The failure, its kind and its evidence, under a heading naming the kind. */
491
+ /**
492
+ * The failure, its kind and its evidence, under a heading naming the kind. The
493
+ * unmet criteria's evidence is a verify Stage's prose rather than output, and
494
+ * may still propose a fix, so it is read as where to start looking.
495
+ */
365
496
  function failureSection({ kind, summary, evidence }: FixFailure, base: string): string {
366
497
  return outputSection(
367
498
  `## The failure: ${failureSentences(base)[kind]}`,
368
499
  evidence,
369
- summary,
500
+ kind === "unmet-criteria" ? `${summary}\n\n${UNMET_EVIDENCE_LEAD}` : summary,
370
501
  );
371
502
  }
372
503
 
373
- /** The unmet criteria a fix Stage was sent in for, and what meeting them now takes. */
504
+ /** How the fix Stage reads the unmet criteria's evidence, said beside it. */
505
+ const UNMET_EVIDENCE_LEAD =
506
+ "This is the verify Stage's evidence for each unmet criterion, given as its checkbox line reads, and for each defect this branch made. A fix this evidence proposes is a lead, not the answer: find the cause yourself, starting from the failure it states.";
507
+
508
+ /**
509
+ * The body, the problem and the solution answered for the branch so far, each
510
+ * under its field's name; nothing where none has been answered.
511
+ */
512
+ function proseSection(prose: BranchProse): string {
513
+ const answered = BRANCH_PROSE_FIELDS.flatMap((field) => {
514
+ const answer = prose[field];
515
+ return answer === undefined ? [] : [`### \`${field}\`\n\n${fenced(answer)}`];
516
+ });
517
+ if (answered.length === 0) return "";
518
+ return ["## What the branch's answers say now", ...answered].join("\n\n");
519
+ }
520
+
521
+ /**
522
+ * Text fenced with more backticks than any run inside it, so a body that
523
+ * carries a fence of its own reads as one block.
524
+ */
525
+ function fenced(text: string): string {
526
+ const longest = Math.max(0, ...(text.match(/`+/g) ?? []).map((run) => run.length));
527
+ const fence = "`".repeat(Math.max(3, longest + 1));
528
+ return `${fence}\n${text}\n${fence}`;
529
+ }
530
+
531
+ /** The unmet criteria and defects a fix Stage was sent in for, and what clearing them now takes. */
374
532
  function unmetBeforeSection(evidence: string): string {
375
533
  return outputSection(
376
534
  "## Judged unmet before the fix",
377
535
  evidence,
378
- "The verify Stage before you judged these criteria unmet, with this evidence, and a fix Stage has worked on the branch since. Such a criterion is met only when that counterexample is gone and the whole criterion holds: a fix that answers the evidence but not the rest of the criterion, or a caveat in place of the behaviour, leaves it `unmet`.",
536
+ "The verify Stage before you judged these criteria unmet, and these defects the branch's own, with this evidence, and a fix Stage has worked on the branch since. Such a criterion is met only when that counterexample is gone and the whole criterion holds: a fix that answers the evidence but not the rest of the criterion, or a caveat in place of the behaviour, leaves it `unmet`. Such a defect goes in your `defects` again until its counterexample is gone.",
379
537
  );
380
538
  }
381
539
 
540
+ /**
541
+ * The criteria the verdict answers, by number, each with the lines under its
542
+ * checkbox; fenced, because they are the Ticket's Markdown, quoted.
543
+ */
544
+ function criteriaSection(criteria: readonly ListedCriterion[]): string {
545
+ if (criteria.length === 0) return "";
546
+ const listed = criteria.flatMap(({ number, text, details }) => [
547
+ `${number}. ${text}`,
548
+ ...indented(details),
549
+ ]);
550
+ return [
551
+ "## The Acceptance Criteria, by number",
552
+ "",
553
+ "Each is an unticked checkbox on the Ticket, in the order the body and then its comments write them. A checkbox nested under another is a criterion of its own.",
554
+ "",
555
+ fenced(listed.join("\n")),
556
+ ].join("\n");
557
+ }
558
+
559
+ /** Lines under a numbered criterion, their own indent kept relative to each other. */
560
+ function indented(lines: readonly string[]): string[] {
561
+ const widths = lines
562
+ .filter((line) => line.trim() !== "")
563
+ .map((line) => (/^[ \t]*/.exec(line)?.[0] ?? "").length);
564
+ const common = Math.min(...widths);
565
+ return lines.map((line) => (line.trim() === "" ? "" : ` ${line.slice(common)}`));
566
+ }
567
+
568
+ /**
569
+ * The Notes this Ticket's code Stages wrote in this Run, which the verify Stage
570
+ * grades for a defect of the branch; nothing where they wrote none.
571
+ */
572
+ function writtenNotesSection(written: readonly WrittenNote[]): string {
573
+ if (written.length === 0) return "";
574
+ const lines = written.flatMap(({ stage, note }) => [
575
+ `- From the ${stage} Stage${note.ticket === undefined ? "" : `, for #${note.ticket}`}: ${note.summary}`,
576
+ ...NOTE_PARTS.flatMap((part) => {
577
+ const text = note[part];
578
+ return text === undefined ? [] : [` ${part}: ${text}`];
579
+ }),
580
+ ]);
581
+ return [
582
+ "## Notes this Ticket's implement and fix Stages wrote in this Run",
583
+ "",
584
+ "The pipeline has already posted these. One that is a defect this branch made is graded in your verdict's `defects`, held to the same evidence as one you found yourself.",
585
+ "",
586
+ fenced(lines.join("\n")),
587
+ ].join("\n");
588
+ }
589
+
382
590
  /**
383
591
  * A heading, an optional line of prose, and raw command output. The output is
384
592
  * fenced because it would otherwise be read as Markdown.
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
  }