ticket-runner 0.6.4 → 0.6.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ko.md +5 -5
- package/README.md +4 -4
- package/docs/templates/operator-skill.md +81 -16
- package/package.json +1 -1
- package/src/acceptance-criteria.ts +99 -2
- package/src/adapters/claude-agent-runner.ts +5 -5
- package/src/adapters/exec.ts +32 -4
- package/src/adapters/gh-tracker.ts +276 -60
- package/src/adapters/git-workspace.ts +27 -10
- package/src/adapters/liveness.ts +77 -0
- package/src/adapters/process-tree.ts +4 -7
- package/src/adapters/version.ts +5 -5
- package/src/branch.ts +1 -1
- package/src/cli.ts +2 -2
- package/src/config.ts +22 -4
- package/src/conventions.ts +22 -19
- package/src/credential.ts +14 -13
- package/src/criteria.ts +102 -52
- package/src/failing-base.ts +7 -7
- package/src/failure-message.ts +72 -0
- package/src/guards.ts +21 -6
- package/src/handoff.ts +2 -2
- package/src/init.ts +8 -8
- package/src/landing.ts +1 -1
- package/src/lifecycle.ts +2 -2
- package/src/lock.ts +10 -2
- package/src/note-schema.ts +14 -11
- package/src/notes.ts +19 -7
- package/src/operator-skill.ts +2 -2
- package/src/orchestrator.ts +758 -275
- package/src/outside-fault.ts +103 -0
- package/src/ports/agent-runner.ts +1 -1
- package/src/ports/tracker.ts +29 -15
- package/src/ports/workspace.ts +52 -24
- package/src/progress.ts +42 -7
- package/src/prompts.ts +242 -34
- package/src/readiness.ts +11 -11
- package/src/remove.ts +7 -7
- package/src/resume.ts +28 -20
- package/src/run-log.ts +5 -5
- package/src/run.ts +55 -13
- package/src/staleness.ts +14 -14
- package/src/start.ts +29 -16
- package/src/stranded.ts +19 -19
- package/src/templates.ts +398 -149
- package/src/title.ts +106 -8
- package/src/transcript-home.ts +49 -0
- package/src/verdict.ts +132 -27
- package/src/version-number.ts +13 -13
- package/src/version-pr.ts +12 -12
package/src/prompts.ts
CHANGED
|
@@ -4,11 +4,12 @@
|
|
|
4
4
|
* (ADR-0002).
|
|
5
5
|
*/
|
|
6
6
|
|
|
7
|
-
import {
|
|
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
|
|
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
|
|
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
|
|
134
|
-
* Acceptance Criterion
|
|
135
|
-
*
|
|
136
|
-
* because a defect
|
|
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
|
|
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
|
|
141
|
-
- A defect
|
|
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
|
-
-
|
|
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
|
-
-
|
|
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
|
|
218
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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
|
|
242
|
-
* a Stage that left those red would spend the
|
|
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
|
|
420
|
+
* A fresh session with no plugin skill, graded against the verdict schema.
|
|
302
421
|
*
|
|
303
|
-
* `unmetBefore` is the evidence of the
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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
|
|
23
|
-
*
|
|
24
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
}
|