ticket-runner 0.6.4 → 0.6.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.ko.md +4 -4
- package/README.md +3 -3
- package/docs/templates/operator-skill.md +7 -7
- package/package.json +1 -1
- package/src/acceptance-criteria.ts +2 -2
- package/src/adapters/claude-agent-runner.ts +3 -3
- package/src/adapters/exec.ts +19 -4
- package/src/adapters/gh-tracker.ts +17 -17
- package/src/adapters/git-workspace.ts +12 -8
- package/src/adapters/liveness.ts +77 -0
- package/src/adapters/process-tree.ts +4 -7
- package/src/adapters/version.ts +5 -5
- package/src/branch.ts +1 -1
- package/src/cli.ts +2 -2
- package/src/config.ts +4 -4
- package/src/conventions.ts +21 -18
- package/src/credential.ts +14 -13
- package/src/criteria.ts +107 -15
- package/src/failing-base.ts +7 -7
- package/src/failure-message.ts +72 -0
- package/src/guards.ts +2 -2
- package/src/handoff.ts +2 -2
- package/src/init.ts +8 -8
- package/src/landing.ts +1 -1
- package/src/lifecycle.ts +2 -2
- package/src/lock.ts +10 -2
- package/src/note-schema.ts +3 -3
- package/src/notes.ts +8 -6
- package/src/operator-skill.ts +2 -2
- package/src/orchestrator.ts +168 -128
- package/src/ports/agent-runner.ts +1 -1
- package/src/ports/tracker.ts +14 -13
- package/src/ports/workspace.ts +23 -22
- package/src/progress.ts +2 -2
- package/src/prompts.ts +67 -24
- package/src/readiness.ts +11 -11
- package/src/remove.ts +7 -7
- package/src/resume.ts +12 -12
- package/src/run-log.ts +5 -5
- package/src/run.ts +7 -7
- package/src/staleness.ts +14 -14
- package/src/start.ts +17 -12
- package/src/stranded.ts +19 -19
- package/src/templates.ts +147 -66
- package/src/title.ts +44 -8
- package/src/verdict.ts +7 -7
- package/src/version-number.ts +13 -13
- package/src/version-pr.ts +12 -12
|
@@ -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
|
|
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.
|
package/src/ports/tracker.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
135
|
-
* conflicting with the
|
|
136
|
-
* such a
|
|
137
|
-
* lets it through, and it has nothing a fix Stage could act
|
|
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
|
|
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
|
-
*
|
|
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
|
-
*
|
|
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
|
|
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
|
|
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
|
|
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>;
|
package/src/ports/workspace.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
59
|
+
/** The state a Ticket keeps while its branch carries work worth resuming. */
|
|
60
60
|
export interface TicketState {
|
|
61
|
-
/** Carried in the
|
|
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
|
|
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
|
|
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
|
|
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
|
|
89
|
+
* otherwise, and in state an earlier pipeline left.
|
|
90
90
|
*/
|
|
91
91
|
rebaseFirst?: boolean;
|
|
92
|
-
/** The Run that last wrote the
|
|
92
|
+
/** The Run that last wrote the state, and when — both for a human reading it. */
|
|
93
93
|
runId: string;
|
|
94
94
|
/**
|
|
95
|
-
* The
|
|
96
|
-
* optional when read:
|
|
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
|
|
105
|
+
* What one Ticket's recorded state turned out to be.
|
|
106
106
|
*
|
|
107
|
-
* Two cases, where no
|
|
108
|
-
*
|
|
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
|
|
116
|
+
/** Read off where the state was kept, which is the only part of it that parsed. */
|
|
117
117
|
ticket: number;
|
|
118
|
-
/** The
|
|
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
|
|
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
|
|
406
|
+
* The state `ticket` keeps, when a Run can resume from it.
|
|
406
407
|
*
|
|
407
|
-
* State nothing wrote, and
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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,7 +86,7 @@ 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
|
|
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
|
|
@@ -107,7 +112,7 @@ ${titleGuidance(base)}
|
|
|
107
112
|
${FINISH_GUIDANCE}
|
|
108
113
|
- Do not spawn nested review agents beyond what the skill itself does.
|
|
109
114
|
- 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
|
|
115
|
+
- Commit all of your work to the branch that is already checked out. ${NO_OTHER_BRANCH}`;
|
|
111
116
|
|
|
112
117
|
/**
|
|
113
118
|
* Appended to the two Stages that write code, which are the two that meet
|
|
@@ -130,14 +135,14 @@ ${noteEntryGuidance(standingNotes)}`;
|
|
|
130
135
|
*
|
|
131
136
|
* The guidance above is written for a Stage that could have fixed what it found
|
|
132
137
|
* 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. So this says which findings that
|
|
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
|
|
135
140
|
* carries — every judgement of a criterion — and gives the rest the Notes list,
|
|
136
141
|
* because a defect outside the criteria has no slot anywhere else.
|
|
137
142
|
*/
|
|
138
|
-
const verifyNotesGuidance = (standingNotes?: number) => `Notes for other Tickets: your
|
|
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.
|
|
139
144
|
|
|
140
|
-
- What you make of a criterion belongs in the
|
|
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.
|
|
141
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.
|
|
142
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.
|
|
143
148
|
- Writing the Note is all you do about it: fix nothing, commit nothing, stage nothing, exactly as the rest of your brief says.
|
|
@@ -195,6 +200,13 @@ const NEEDS_A_HUMAN =
|
|
|
195
200
|
* `unmet` with a human's decision as its evidence, rather than met on a
|
|
196
201
|
* workaround: the fix Stage it buys is told to commit nothing for it, which is
|
|
197
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.
|
|
198
210
|
*/
|
|
199
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.
|
|
200
212
|
|
|
@@ -204,7 +216,8 @@ const verifyInstructions = (checks: readonly string[]) => `You are the verify St
|
|
|
204
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.
|
|
205
217
|
- Mark a criterion \`unverifiable\` only when no evidence can be gathered, never as a substitute for looking.
|
|
206
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.
|
|
207
|
-
-
|
|
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.`;
|
|
208
221
|
|
|
209
222
|
/** The Checks as the verify Stage is told about them: passed, and not its to run. */
|
|
210
223
|
function verifyChecksLine(checks: readonly string[]): string {
|
|
@@ -214,9 +227,14 @@ function verifyChecksLine(checks: readonly string[]): string {
|
|
|
214
227
|
|
|
215
228
|
/**
|
|
216
229
|
* 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
|
-
*
|
|
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
|
|
219
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.
|
|
220
238
|
*/
|
|
221
239
|
const fixInstructions = (
|
|
222
240
|
base: string,
|
|
@@ -224,22 +242,39 @@ const fixInstructions = (
|
|
|
224
242
|
checks: readonly string[],
|
|
225
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.
|
|
226
244
|
|
|
227
|
-
- Commit your fix on the branch you are on, in this worktree. Do not
|
|
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.
|
|
228
246
|
- 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 : ""}
|
|
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}` : ""}
|
|
230
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)}
|
|
231
249
|
${FINISH_GUIDANCE}
|
|
232
|
-
- Write commit subjects in the
|
|
233
|
-
${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.`;
|
|
234
269
|
|
|
235
270
|
/** What the fix Stage sent in for unmet criteria does with one only a human can settle. */
|
|
236
271
|
const HUMAN_DECISION_LINE = `
|
|
237
|
-
- When any unmet criterion ${NEEDS_A_HUMAN}, as the verify Stage's evidence may already say, commit nothing and
|
|
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.`;
|
|
238
273
|
|
|
239
274
|
/**
|
|
240
275
|
* 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
|
|
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
|
|
243
278
|
* does may change behaviour the criteria cover, because verify does not run
|
|
244
279
|
* again after it.
|
|
245
280
|
*/
|
|
@@ -252,7 +287,7 @@ const conflictInstructions = (
|
|
|
252
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.
|
|
253
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.
|
|
254
289
|
- 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)}`;
|
|
290
|
+
- ${NO_OTHER_BRANCH} Do not push, do not open pull requests, and do not close the Ticket.${conflictChecksLine(checks)}`;
|
|
256
291
|
|
|
257
292
|
/** The Checks as the conflict Stage is told about them: the pipeline's to run in full. */
|
|
258
293
|
function conflictChecksLine(checks: readonly string[]): string {
|
|
@@ -298,9 +333,9 @@ export function implementPrompt(
|
|
|
298
333
|
}
|
|
299
334
|
|
|
300
335
|
/**
|
|
301
|
-
* A fresh session with no plugin skill, graded against the
|
|
336
|
+
* A fresh session with no plugin skill, graded against the verdict schema.
|
|
302
337
|
*
|
|
303
|
-
* `unmetBefore` is the evidence of the
|
|
338
|
+
* `unmetBefore` is the evidence of the verdict a fix Stage was sent in for, in
|
|
304
339
|
* the same Run; a first verify has none. Without it the verify behind a fix
|
|
305
340
|
* graded the fix on its own terms, and passed a caveat the first one had
|
|
306
341
|
* counted as unmet.
|
|
@@ -361,15 +396,23 @@ export function fixPrompt(
|
|
|
361
396
|
]);
|
|
362
397
|
}
|
|
363
398
|
|
|
364
|
-
/**
|
|
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
|
+
*/
|
|
365
404
|
function failureSection({ kind, summary, evidence }: FixFailure, base: string): string {
|
|
366
405
|
return outputSection(
|
|
367
406
|
`## The failure: ${failureSentences(base)[kind]}`,
|
|
368
407
|
evidence,
|
|
369
|
-
summary,
|
|
408
|
+
kind === "unmet-criteria" ? `${summary}\n\n${UNMET_EVIDENCE_LEAD}` : summary,
|
|
370
409
|
);
|
|
371
410
|
}
|
|
372
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
|
+
|
|
373
416
|
/** The unmet criteria a fix Stage was sent in for, and what meeting them now takes. */
|
|
374
417
|
function unmetBeforeSection(evidence: string): string {
|
|
375
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
|
|
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
|
}
|