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.
Files changed (48) hide show
  1. package/README.ko.md +4 -4
  2. package/README.md +3 -3
  3. package/docs/templates/operator-skill.md +7 -7
  4. package/package.json +1 -1
  5. package/src/acceptance-criteria.ts +2 -2
  6. package/src/adapters/claude-agent-runner.ts +3 -3
  7. package/src/adapters/exec.ts +19 -4
  8. package/src/adapters/gh-tracker.ts +17 -17
  9. package/src/adapters/git-workspace.ts +12 -8
  10. package/src/adapters/liveness.ts +77 -0
  11. package/src/adapters/process-tree.ts +4 -7
  12. package/src/adapters/version.ts +5 -5
  13. package/src/branch.ts +1 -1
  14. package/src/cli.ts +2 -2
  15. package/src/config.ts +4 -4
  16. package/src/conventions.ts +21 -18
  17. package/src/credential.ts +14 -13
  18. package/src/criteria.ts +107 -15
  19. package/src/failing-base.ts +7 -7
  20. package/src/failure-message.ts +72 -0
  21. package/src/guards.ts +2 -2
  22. package/src/handoff.ts +2 -2
  23. package/src/init.ts +8 -8
  24. package/src/landing.ts +1 -1
  25. package/src/lifecycle.ts +2 -2
  26. package/src/lock.ts +10 -2
  27. package/src/note-schema.ts +3 -3
  28. package/src/notes.ts +8 -6
  29. package/src/operator-skill.ts +2 -2
  30. package/src/orchestrator.ts +168 -128
  31. package/src/ports/agent-runner.ts +1 -1
  32. package/src/ports/tracker.ts +14 -13
  33. package/src/ports/workspace.ts +23 -22
  34. package/src/progress.ts +2 -2
  35. package/src/prompts.ts +67 -24
  36. package/src/readiness.ts +11 -11
  37. package/src/remove.ts +7 -7
  38. package/src/resume.ts +12 -12
  39. package/src/run-log.ts +5 -5
  40. package/src/run.ts +7 -7
  41. package/src/staleness.ts +14 -14
  42. package/src/start.ts +17 -12
  43. package/src/stranded.ts +19 -19
  44. package/src/templates.ts +147 -66
  45. package/src/title.ts +44 -8
  46. package/src/verdict.ts +7 -7
  47. package/src/version-number.ts +13 -13
  48. package/src/version-pr.ts +12 -12
package/src/templates.ts CHANGED
@@ -13,6 +13,7 @@ import {
13
13
  } from "./credential.js";
14
14
  import type { GuardReason } from "./guards.js";
15
15
  import type { HostKind } from "./host.js";
16
+ import { splitMessage } from "./failure-message.js";
16
17
  import type { FailurePoint } from "./lifecycle.js";
17
18
  import { logTail } from "./log-tail.js";
18
19
  import type { NoteText, NotingStage, RoutedNote } from "./notes.js";
@@ -116,7 +117,7 @@ export function guardComment(reason: GuardReason): string {
116
117
  ].join("\n");
117
118
  }
118
119
 
119
- /** The Verdict summary both the pull request body and the squash commit carry. */
120
+ /** The verdict summary both the pull request body and the squash commit carry. */
120
121
  function verdictCounts(verdict: Verdict): string {
121
122
  const counts = countStatuses(verdict);
122
123
  return `${counts.met} met · ${counts.unmet} unmet · ${counts.unverifiable} unverifiable`;
@@ -166,6 +167,10 @@ export function pullRequestBody({ ticket, verdict, runId, host }: PullRequestBod
166
167
  export interface DraftPullRequestBody {
167
168
  ticket: number;
168
169
  stage: FailurePoint;
170
+ /**
171
+ * As the hand-off comment's: one line, or an unexpected error's whole
172
+ * message, whose output the body shows as evidence the way the comment does.
173
+ */
169
174
  failure: string;
170
175
  runId: string;
171
176
  /** Where the hand-off kept the Stages' transcripts on the remote, when it kept any. */
@@ -173,9 +178,9 @@ export interface DraftPullRequestBody {
173
178
  }
174
179
 
175
180
  /**
176
- * The body of the draft PR a hand-off leaves behind, whether it opened the PR
177
- * or made an open one a draft: what a human needs from it is the hand-off, not
178
- * a Verdict.
181
+ * The body of the draft pull request a hand-off leaves behind, whether it
182
+ * opened the pull request or made an open one a draft: what a human needs from
183
+ * it is the hand-off, not a verdict.
179
184
  */
180
185
  export function draftPullRequestBody({
181
186
  ticket,
@@ -184,11 +189,13 @@ export function draftPullRequestBody({
184
189
  runId,
185
190
  transcripts,
186
191
  }: DraftPullRequestBody): string {
192
+ const shown = failureShown(failure, "");
187
193
  return [
188
194
  `Closes #${ticket}`,
189
195
  "",
190
- `**Handed off at ${stage}.** ${failure}`,
196
+ `**Handed off at ${stage}.** ${shown.line}`,
191
197
  "",
198
+ ...evidenceBlock(shown.evidence),
192
199
  `See the hand-off comment on #${ticket} for the branch, worktree and evidence.`,
193
200
  "",
194
201
  runLine(runId, transcripts === undefined ? undefined : keptPlace(transcripts)),
@@ -196,6 +203,31 @@ export function draftPullRequestBody({
196
203
  ].join("\n");
197
204
  }
198
205
 
206
+ /**
207
+ * A hand-off's failure as one line, and the evidence that goes with it.
208
+ *
209
+ * The failures the pipeline expects already come as one line and their output
210
+ * as evidence. An unexpected error comes as its message whole — the command,
211
+ * how it exited, and everything it printed — so its first line is the failure
212
+ * and the rest is evidence, ahead of any the hand-off carried already.
213
+ */
214
+ function failureShown(failure: string, evidence: string): { line: string; evidence: string } {
215
+ const { line, output } = splitMessage(failure);
216
+ return {
217
+ line,
218
+ evidence: [output, evidence.trim()].filter((part) => part !== "").join("\n\n"),
219
+ };
220
+ }
221
+
222
+ /**
223
+ * Evidence folded away and fenced, because it is raw output that would
224
+ * otherwise be read as Markdown; nothing at all when there is none.
225
+ */
226
+ function evidenceBlock(evidence: string): string[] {
227
+ if (evidence === "") return [];
228
+ return ["<details><summary>Evidence</summary>", "", "```", evidence, "```", "", "</details>", ""];
229
+ }
230
+
199
231
  /**
200
232
  * The line both pull request bodies end with: the Run, and where its
201
233
  * transcripts are when there is somewhere that outlives the Host to point at.
@@ -227,7 +259,7 @@ export interface SquashCommitMessage {
227
259
  * The commit a merged Ticket leaves on the base branch.
228
260
  *
229
261
  * `git log` renders no HTML, so this is the one template with nothing folded
230
- * away: the Verdict is counts only, and the per-criterion evidence stays in the
262
+ * away: the verdict is counts only, and the per-criterion evidence stays in the
231
263
  * pull request body where a browser can collapse it.
232
264
  */
233
265
  export function squashCommit({
@@ -256,7 +288,10 @@ export function squashCommit({
256
288
 
257
289
  export interface HandoffComment {
258
290
  stage: FailurePoint;
259
- /** One line a human can read in a notification. */
291
+ /**
292
+ * One line a human can read in a notification, or an unexpected error's
293
+ * whole message, whose first line is shown here and the rest as evidence.
294
+ */
260
295
  failure: string;
261
296
  branch: string;
262
297
  /**
@@ -277,6 +312,12 @@ export interface HandoffComment {
277
312
  fixUsed?: boolean;
278
313
  /** Where the Stages' transcripts were kept on the remote, when any were. */
279
314
  transcripts?: KeptTranscripts;
315
+ /**
316
+ * Why the Stage this hand-off is for committed nothing, as it answered it in
317
+ * `noCommitReason`. Set only for an implement or fix Stage that finished and
318
+ * left no new commit, which is the one hand-off the reason explains.
319
+ */
320
+ reason?: string;
280
321
  }
281
322
 
282
323
  export function handoffComment(handoff: HandoffComment): string {
@@ -290,33 +331,33 @@ export function handoffComment(handoff: HandoffComment): string {
290
331
  // pipeline already had a second go at, which is what a human needs to know.
291
332
  const budget = handoff.fixUsed ? ", after the fix budget was used" : "";
292
333
 
293
- const lines = [
334
+ const shown = failureShown(handoff.failure, handoff.evidence);
335
+ return [
294
336
  HANDOFF_MARKER,
295
337
  `**Handed off.** Failed at **${handoff.stage}**${budget}.`,
296
338
  "",
297
- `- Failure: ${handoff.failure}`,
339
+ `- Failure: ${shown.line}`,
298
340
  `- ${location}`,
299
341
  ...(handoff.transcripts === undefined
300
342
  ? []
301
343
  : [`- Transcripts: ${keptPlace(handoff.transcripts)}`]),
302
344
  "",
303
- ];
304
-
305
- const evidence = handoff.evidence.trim();
306
- if (evidence !== "") {
307
- lines.push(
308
- "<details><summary>Evidence</summary>",
309
- "",
310
- "```",
311
- evidence,
312
- "```",
313
- "",
314
- "</details>",
315
- "",
316
- );
317
- }
345
+ ...stageSaid(handoff.stage, handoff.reason),
346
+ ...evidenceBlock(shown.evidence),
347
+ ].join("\n");
348
+ }
318
349
 
319
- return lines.join("\n");
350
+ /**
351
+ * The reason a Stage gave for committing nothing, as a paragraph of its own
352
+ * between the hand-off's lines and its folded evidence, so a human reads it
353
+ * without unfolding anything; nothing when it gave none.
354
+ *
355
+ * The Stage's prose is posted on the Ticket, whose comments are read for
356
+ * Acceptance Criteria, so its checkboxes are defused as a Note's are.
357
+ */
358
+ function stageSaid(stage: FailurePoint, reason: string | undefined): string[] {
359
+ if (reason === undefined || reason.trim() === "") return [];
360
+ return [`**The ${stage} Stage said:** ${escapeCheckboxes(reason.trim())}`, ""];
320
361
  }
321
362
 
322
363
  /**
@@ -368,21 +409,22 @@ export interface NoteSubject {
368
409
  because?: string;
369
410
  }
370
411
 
371
- /** {@link UNCHECKED_BOX}, over every line of a Note rather than the first. */
372
- const NOTE_CHECKBOX = new RegExp(UNCHECKED_BOX, "gm");
412
+ /** {@link UNCHECKED_BOX}, over every line of a Stage's prose rather than the first. */
413
+ const PROSE_CHECKBOX = new RegExp(UNCHECKED_BOX, "gm");
373
414
 
374
415
  /**
375
- * One part of a Note's prose, with every checkbox defused.
416
+ * A Stage's prose — one part of a Note, or the reason it gave for committing
417
+ * nothing — with every checkbox defused.
376
418
  *
377
419
  * `- [ ]` is Acceptance Criteria to everything that reads a Ticket: the
378
420
  * `no-criteria` guard counts one as a usable Ticket, verify grades it, and the
379
- * merge ticks it. A Note is prose a human should read, not work anyone
421
+ * merge ticks it. A Stage's prose is for a human to read, not work anyone
380
422
  * promised, so its boxes are escaped into the text they were meant to be.
381
423
  * Brackets anywhere but at the head of a list item are left alone, because that
382
424
  * is the only shape those readers recognise.
383
425
  */
384
- function escapeCheckboxes(note: string): string {
385
- return note.replaceAll(NOTE_CHECKBOX, (_, bullet: string) => `${bullet}\\[ \\]`);
426
+ function escapeCheckboxes(prose: string): string {
427
+ return prose.replaceAll(PROSE_CHECKBOX, (_, bullet: string) => `${bullet}\\[ \\]`);
386
428
  }
387
429
 
388
430
  /**
@@ -426,14 +468,28 @@ export function noteComment(subject: NoteSubject): string {
426
468
  return [NOTE_MARKER, noteProvenance(subject), "", paragraphs.join("\n\n"), ""].join("\n");
427
469
  }
428
470
 
429
- /** A Check the Base branch fails, as the pipeline's own Note reports it. */
471
+ /**
472
+ * How the Ticket's own branch failed, before the merge-base was graded: a Check
473
+ * in its worktree, or CI on its pull request.
474
+ */
475
+ export type BranchFailure =
476
+ | { point: "checks"; command: string; output: string; timedOut: boolean }
477
+ | {
478
+ point: "ci";
479
+ /** Which checks went red, as CI reported them. */
480
+ summary: string;
481
+ /** The tail of the failing jobs' logs, which a fix Stage would be handed; empty when none had one. */
482
+ excerpt: string;
483
+ };
484
+
485
+ /** A Check the base branch fails, as the pipeline's own Note reports it. */
430
486
  export interface FailingBaseNote {
431
487
  /** The Ticket the failure released. */
432
488
  origin: number;
433
- /** Where the Ticket's branch failed: its Checks, or CI on its pull request. */
434
- point: "checks" | "ci";
489
+ /** How the Ticket's branch failed, which the Note quotes beside the merge-base's output. */
490
+ onBranch: BranchFailure;
435
491
  baseBranch: string;
436
- /** The Ticket's branch, whose merge-base with the Base branch `commit` is. */
492
+ /** The Ticket's branch, whose merge-base with the base branch `commit` is. */
437
493
  branch: string;
438
494
  /** The merge-base, in full, so it can be checked out as it is. */
439
495
  commit: string;
@@ -444,43 +500,72 @@ export interface FailingBaseNote {
444
500
 
445
501
  /** The pipeline's Note's summary, which is also the Run summary's `noted` row. */
446
502
  export function failingBaseSummary(baseBranch: string, command: string): string {
447
- return `The Base branch \`${baseBranch}\` fails \`${command}\`.`;
503
+ return `The base branch \`${baseBranch}\` fails \`${command}\`.`;
448
504
  }
449
505
 
450
506
  /**
451
- * The one Note no Stage writes: a Ticket was released because the Base branch
452
- * fails the Check its branch failed, so the defect is the Base branch's and a
507
+ * The one Note no Stage writes: a Ticket was released because the base branch
508
+ * fails the Check its branch failed, so the defect is the base branch's and a
453
509
  * human has to mend it there.
454
510
  *
455
511
  * Signed and laid out as a Stage's Note is, so triage reads it the same way,
456
512
  * with the provenance naming the pipeline rather than a Stage. The tail of the
457
513
  * output is the one a CI log excerpt keeps, so long lines cannot push the Note
458
- * past what GitHub takes in a comment. It is fenced with more backticks than
459
- * any run of them inside it, so a fence the output prints cannot close it early.
514
+ * past what GitHub takes in a comment.
515
+ *
516
+ * The branch's own failure is quoted beside it, because only the command is
517
+ * compared: a branch that fails the command differently is released all the
518
+ * same, and its failure would otherwise be nowhere a human can read it. For CI
519
+ * that is the failing jobs' logs as a fix Stage would be handed them, which are
520
+ * tails already.
460
521
  */
461
522
  export function failingBaseNote(note: FailingBaseNote): string {
462
- const { baseBranch, branch, commit, command } = note;
463
- const tail = logTail(note.output);
523
+ const { baseBranch, branch, commit, command, onBranch } = note;
464
524
  const where = `\`${command}\` ${note.timedOut ? "timed out" : "failed"} in a clean worktree at ${commit}, the merge-base of \`${branch}\` with \`${baseBranch}\`.`;
465
- const fence = "`".repeat(Math.max(3, ...[...tail.matchAll(/`+/g)].map(([run]) => run.length + 1)));
466
- const evidence =
467
- tail === ""
468
- ? `**Evidence**: ${where} It printed nothing.`
469
- : `**Evidence**: ${where} The tail of its output:\n\n${fence}\n${escapeCheckboxes(tail)}\n${fence}`;
525
+ const opening = "The branch's own failure, which need not be the same:";
526
+ const branchPart =
527
+ onBranch.point === "checks"
528
+ ? quoted(
529
+ `${opening} \`${onBranch.command}\` ${onBranch.timedOut ? "timed out" : "failed"} on \`${branch}\`.`,
530
+ "The tail of the branch's output:",
531
+ logTail(onBranch.output),
532
+ "It printed nothing.",
533
+ )
534
+ : quoted(
535
+ `${opening} CI on the pull request from \`${branch}\` reported ${onBranch.summary}.`,
536
+ "The tail of the failing jobs' logs:",
537
+ onBranch.excerpt.trim(),
538
+ "No failing job had a log to quote.",
539
+ );
470
540
  return [
471
541
  NOTE_MARKER,
472
- `From the pipeline, releasing #${note.origin} at ${note.point}`,
542
+ `From the pipeline, releasing #${note.origin} at ${onBranch.point}`,
473
543
  "",
474
544
  [
475
545
  `**${failingBaseSummary(baseBranch, command)}**`,
476
- evidence,
477
- `**Impact**: every Ticket whose branch inherits ${commit} fails the same Check. #${note.origin} was released with its Fix budget as it was, and the Run claimed no more Tickets.`,
478
- `**Next**: mend \`${command}\` on \`${baseBranch}\`. The next Run takes the released Tickets up again from their State files, rebased onto \`${baseBranch}\` before their Checks.`,
546
+ `**Evidence**: ${quoted(where, "The tail of its output:", logTail(note.output), "It printed nothing.")}`,
547
+ branchPart,
548
+ `**Impact**: every Ticket whose branch inherits ${commit} fails the same Check. #${note.origin} was released with its fix budget as it was, and the Run claimed no more Tickets.`,
549
+ `**Next**: mend \`${command}\` on \`${baseBranch}\`. The next Run takes the released Tickets up again from their state files, rebased onto \`${baseBranch}\` before their Checks.`,
479
550
  ].join("\n\n"),
480
551
  "",
481
552
  ].join("\n");
482
553
  }
483
554
 
555
+ /**
556
+ * A sentence of the pipeline's own and the output it introduces, or `ifEmpty`
557
+ * in place of the introduction when there was no output.
558
+ *
559
+ * The output is fenced with more backticks than any run of them inside it, so a
560
+ * fence the output prints cannot close it early, and only the output has its
561
+ * checkboxes escaped, since the words around it are the pipeline's.
562
+ */
563
+ function quoted(sentence: string, introduction: string, output: string, ifEmpty: string): string {
564
+ if (output === "") return `${sentence} ${ifEmpty}`;
565
+ const fence = "`".repeat(Math.max(3, ...[...output.matchAll(/`+/g)].map(([run]) => run.length + 1)));
566
+ return `${sentence} ${introduction}\n\n${fence}\n${escapeCheckboxes(output)}\n${fence}`;
567
+ }
568
+
484
569
  /** Whether an issue's body says it is the standing Notes issue. */
485
570
  export function isNotesIssue(body: string): boolean {
486
571
  return carriesMarker(body, NOTES_ISSUE_MARKER);
@@ -503,7 +588,7 @@ export function notesIssue(): { title: string; body: string } {
503
588
  "**Notes from the pipeline.** Every finding a Stage could not post on a " +
504
589
  "Ticket arrives here as a comment: one that named no Ticket, one whose " +
505
590
  "Ticket would have buried it, and one whose Ticket refused the comment. " +
506
- "So does the pipeline's own Note about a Base branch that fails a Check. " +
591
+ "So does the pipeline's own Note about a base branch that fails a Check. " +
507
592
  "Each comment says which Ticket and Stage, or the pipeline, found it.",
508
593
  "",
509
594
  "Triage empties this issue by hand: promote what deserves a Ticket, record " +
@@ -516,7 +601,7 @@ export function notesIssue(): { title: string; body: string } {
516
601
  }
517
602
 
518
603
  export interface RunSummary {
519
- /** The Version the Run ran, which is what its transcripts are stamped with. */
604
+ /** The version the Run ran, which is what its transcripts are stamped with. */
520
605
  version: string;
521
606
  runId: string;
522
607
  durationMs: number;
@@ -524,13 +609,13 @@ export interface RunSummary {
524
609
  credential: Credential;
525
610
  outcomes: TicketOutcome[];
526
611
  /**
527
- * What the Run's Stages said they were billed: the Spend or extra usage its
612
+ * What the Run's Stages said they were billed: the spend or extra usage its
528
613
  * header gives, and every Stage that said it ran on something else, each
529
614
  * named in a row after its own Ticket's.
530
615
  */
531
616
  billing?: Billing;
532
617
  /**
533
- * The line saying a newer Version is out, where one is. Above the header
618
+ * The line saying a newer version is out, where one is. Above the header
534
619
  * rather than below it: the Run already said this hours ago, at the top of a
535
620
  * log this summary is the bottom of (ADR-0007).
536
621
  */
@@ -542,14 +627,14 @@ export interface RunSummary {
542
627
  /**
543
628
  * What a Release is put down to, in the words the Run summary and the log
544
629
  * share: the rate limit, a transient API failure, an API key out of credit or
545
- * past its spend limit, or a Base branch that fails the Check the Ticket's
630
+ * past its spend limit, or a base branch that fails the Check the Ticket's
546
631
  * branch failed.
547
632
  */
548
633
  export const RELEASE_WORDS: Record<ReleaseCause, string> = {
549
634
  "rate-limited": "rate limit",
550
635
  "api-error": "API failure",
551
636
  "out-of-budget": "out of API budget",
552
- "failing-base": "failing Base branch",
637
+ "failing-base": "failing base branch",
553
638
  };
554
639
 
555
640
  /**
@@ -569,7 +654,7 @@ const VERB_WIDTH = 9;
569
654
  /**
570
655
  * What a Run prints when it ends. One line per Ticket, then why the Run
571
656
  * stopped — the Frontier is empty, everything left on it is blocked, the rate
572
- * limit, a transient API failure, the API key's budget or a failing Base branch
657
+ * limit, a transient API failure, the API key's budget or a failing base branch
573
658
  * released a Ticket and the Run went no further, or a human stopped it.
574
659
  */
575
660
  export function runSummary({
@@ -607,7 +692,7 @@ export function runSummary({
607
692
 
608
693
  /**
609
694
  * What the header says the Run's Stages were billed to. An `--api-key` Run
610
- * adds its Spend, ending `+` where a Stage on the key reported no figure, so it
695
+ * adds its spend, ending `+` where a Stage on the key reported no figure, so it
611
696
  * is at least that much. A subscription Run adds no amount, since its figure
612
697
  * is an estimate at API prices and not money spent, only whether a Stage ran
613
698
  * on the plan's extra usage.
@@ -694,11 +779,6 @@ function ticketRows(outcome: TicketOutcome, credential: Credential): string[] {
694
779
  ];
695
780
  }
696
781
 
697
- /** A Note summary's opening line, which is as much of it as a Run summary has room for. */
698
- function firstLine(text: string): string {
699
- return (text.split("\n").find((line) => line.trim() !== "") ?? "").trim();
700
- }
701
-
702
782
  /** `text`, or as much of it as fits with an ellipsis standing in for the rest. */
703
783
  function truncate(text: string, limit: number): string {
704
784
  return text.length <= limit ? text : `${text.slice(0, limit - 1).trimEnd()}\u2026`;
@@ -717,7 +797,7 @@ function noteRow({ origin, stage, issue, opened, summary }: RoutedNote): string
717
797
  return row(
718
798
  "noted",
719
799
  issue,
720
- `${destination} · from #${origin} ${stage} · ${truncate(firstLine(summary), NOTE_WIDTH)}`,
800
+ `${destination} · from #${origin} ${stage} · ${truncate(splitMessage(summary).line, NOTE_WIDTH)}`,
721
801
  );
722
802
  }
723
803
 
@@ -730,7 +810,8 @@ function ticketRow(outcome: TicketOutcome, credential: Credential): string {
730
810
  return row(
731
811
  "handed",
732
812
  outcome.ticket,
733
- `${outcome.title} · ${outcome.stage} · ${outcome.failure}`,
813
+ // The one line of an unexpected error; its output is the hand-off's.
814
+ `${outcome.title} · ${outcome.stage} · ${splitMessage(outcome.failure).line}`,
734
815
  );
735
816
  case "released":
736
817
  // Nothing for a human to do, so the row says only what stopped the Stage
package/src/title.ts CHANGED
@@ -19,7 +19,15 @@ import { CODE_STAGE_NOTES_LIST_SCHEMA } from "./note-schema.js";
19
19
  export const BRANCH_TITLE =
20
20
  "one line summarising the whole branch as it stands when you finish, the work of any Stage before you included";
21
21
 
22
- /** Any `<type>(<scope>): <summary>`; the repo's own types and scopes are CONTRIBUTING.md's business. */
22
+ /**
23
+ * The shape a commit subject and a title take, as the prompts of the code
24
+ * Stages and the schema state it: one declaration, so they cannot drift apart.
25
+ * The conventions document a Target carries states it to the readers the
26
+ * pipeline does not brief.
27
+ */
28
+ export const SUBJECT_SHAPE = "<type>(<scope>): <summary>";
29
+
30
+ /** Any {@link SUBJECT_SHAPE}; the repo's own types and scopes are CONTRIBUTING.md's business. */
23
31
  const CONVENTIONAL_SUBJECT = /^[a-z]+(\([a-z0-9._-]+\))?: \S/;
24
32
 
25
33
  /** The `(#<n>)` a commit may carry, which the squash commit's `Closes #<n>` replaces. */
@@ -27,23 +35,35 @@ const TICKET_REFERENCE = /\s*\(#\d+\)$/;
27
35
 
28
36
  /**
29
37
  * The `--json-schema` the implement and fix Stages are invoked with: the title
30
- * of the whole branch, and the Notes channel beside it.
38
+ * of the whole branch, the Notes channel beside it, and why the Stage ended
39
+ * with no new commit when it did.
31
40
  *
32
- * Both are required, so a Stage always says something about each: an empty
33
- * Notes list when it found nothing, and a title however little it did. The
34
- * parsers forgive either one on its own ({@link parseTitle} and `parseNotes`),
35
- * so a bad title never costs the Notes and bad Notes never cost the title.
41
+ * All three are required, so a Stage always says something about each: an
42
+ * empty Notes list when it found nothing, a title however little it did, and an
43
+ * empty reason when it committed. The parsers forgive each one on its own
44
+ * ({@link parseTitle}, `parseNotes` and {@link parseNoCommitReason}), so a bad
45
+ * answer to one never costs the others.
46
+ *
47
+ * The reason is asked for in its own field because, under `--json-schema`, the
48
+ * answer is all of the session the pipeline reads: a last message in prose is
49
+ * only an earlier turn of the transcript. A Stage that ends with no new commit
50
+ * hands the Ticket to a human, and the hand-off quotes the reason (#306).
36
51
  */
37
52
  export const CODE_STAGE_JSON_SCHEMA = {
38
53
  type: "object",
39
54
  properties: {
40
55
  title: {
41
56
  type: "string",
42
- description: `Write ${BRANCH_TITLE}: \`<type>(<scope>): <summary>\`, without the \`(#<n>)\`. It titles the pull request and the squash commit that lands.`,
57
+ description: `Write ${BRANCH_TITLE}: \`${SUBJECT_SHAPE}\`, without the \`(#<n>)\`. It titles the pull request and the squash commit that lands.`,
43
58
  },
44
59
  notes: CODE_STAGE_NOTES_LIST_SCHEMA,
60
+ noCommitReason: {
61
+ type: "string",
62
+ description:
63
+ "When you end with no new commit on the branch, say why in a few sentences: ending so hands the Ticket to a human, and the hand-off comment quotes this. Otherwise an empty string.",
64
+ },
45
65
  },
46
- required: ["title", "notes"],
66
+ required: ["title", "notes", "noCommitReason"],
47
67
  additionalProperties: false,
48
68
  } as const;
49
69
 
@@ -73,6 +93,22 @@ export function parseTitle(result: unknown): string | undefined {
73
93
  return typeof raw === "string" ? asTitle(raw) : undefined;
74
94
  }
75
95
 
96
+ /**
97
+ * Why a code Stage ended with no new commit, as it answered it, or nothing
98
+ * when it gave no reason.
99
+ *
100
+ * Forgiving, as the title and the Notes beside it are: output that is not an
101
+ * object and a missing, blank or non-string reason each cost the reason alone.
102
+ * The lines are kept as the Stage wrote them; only the ends are trimmed.
103
+ */
104
+ export function parseNoCommitReason(result: unknown): string | undefined {
105
+ if (typeof result !== "object" || result === null) return undefined;
106
+ const raw = (result as { noCommitReason?: unknown }).noCommitReason;
107
+ if (typeof raw !== "string") return undefined;
108
+ const reason = raw.trim();
109
+ return reason === "" ? undefined : reason;
110
+ }
111
+
76
112
  /**
77
113
  * The pull request title, in this order of preference: the latest title a
78
114
  * Stage answered, whether in this Run or recorded by the one before it; the
package/src/verdict.ts CHANGED
@@ -22,7 +22,7 @@ export type Verdict = z.infer<typeof verdictSchema>;
22
22
  export type CriterionStatus = Criterion["status"];
23
23
 
24
24
  /**
25
- * The `--json-schema` the verify Stage is invoked with: the Verdict, and the
25
+ * The `--json-schema` the verify Stage is invoked with: the verdict, and the
26
26
  * Notes channel beside it.
27
27
  *
28
28
  * The `notes` list has to be declared here even though {@link parseVerdict}
@@ -31,11 +31,11 @@ export type CriterionStatus = Criterion["status"];
31
31
  * parsing, is what would otherwise leave the most adversarial reader in the
32
32
  * pipeline with nowhere to put a finding outside the criteria.
33
33
  *
34
- * It is not required, where the criteria and the flag are. The Verdict is the
34
+ * It is not required, where the criteria and the flag are. The verdict is the
35
35
  * Stage's product and a session that graded nothing has done none of its job,
36
- * so every required key here is a way for a Ticket to lose its Verdict — and a
37
- * side channel may never cost one. A Verdict that leaves the list out is a
38
- * Verdict from a session that found nothing beside the criteria.
36
+ * so every required key here is a way for a Ticket to lose its verdict — and a
37
+ * side channel may never cost one. A verdict that leaves the list out is a
38
+ * verdict from a session that found nothing beside the criteria.
39
39
  */
40
40
  export const VERDICT_JSON_SCHEMA = {
41
41
  type: "object",
@@ -49,7 +49,7 @@ export const VERDICT_JSON_SCHEMA = {
49
49
  status: { type: "string", enum: ["met", "unmet", "unverifiable"] },
50
50
  evidence: {
51
51
  type: "string",
52
- description: "What you ran or read, and what it showed",
52
+ description: "What you ran or read, and what it showed. It proposes no fix",
53
53
  },
54
54
  },
55
55
  required: ["text", "status", "evidence"],
@@ -70,7 +70,7 @@ export function parseVerdict(result: unknown): Verdict {
70
70
 
71
71
  /**
72
72
  * The pipeline's own pass decision: no criterion is unmet and at least one is
73
- * met. A Verdict of nothing but `unverifiable` is zero evidence, so it fails.
73
+ * met. A verdict of nothing but `unverifiable` is zero evidence, so it fails.
74
74
  */
75
75
  export function passes(verdict: Verdict): boolean {
76
76
  const counts = countStatuses(verdict);
@@ -1,49 +1,49 @@
1
1
  /**
2
- * Arithmetic on Version numbers: which of two is higher, and which number a tag
3
- * or a Version string carries.
2
+ * Arithmetic on version numbers: which of two is higher, and which number a tag
3
+ * or a version string carries.
4
4
  *
5
5
  * Three readers share it and would otherwise each have a comparison of their
6
- * own: the check on a Version PR, the notice a Run prints when a newer Version
6
+ * own: the check on a release PR, the notice a Run prints when a newer version
7
7
  * has been published, and the mark a Target's conventions document bears
8
8
  * (ADR-0007). Nothing here reads a file or asks GitHub — a number against a
9
- * number — so the one thing every Version question turns on is proved once.
9
+ * number — so the one thing every version question turns on is proved once.
10
10
  */
11
11
 
12
- /** A number on its own: the three parts every Version tag is cut at. */
12
+ /** A number on its own: the three parts every version tag is cut at. */
13
13
  const NUMBER = /^\d+\.\d+\.\d+$/;
14
14
 
15
15
  /**
16
- * The number a Version string reports, without the commit a development
16
+ * The number a version string reports, without the commit a development
17
17
  * checkout adds: `0.4.0+331d79c.dirty` is `0.4.0`.
18
18
  *
19
19
  * Undefined where the string carries no number at all, which is what a copy
20
20
  * with no package to read calls itself. Comparing by number is what lets a
21
- * checkout running a commit past the latest Version count as current rather
22
- * than as stale: between two Versions the commit says nothing either way.
21
+ * checkout running a commit past the latest version count as current rather
22
+ * than as stale: between two versions the commit says nothing either way.
23
23
  */
24
24
  export function versionNumber(version: string): string | undefined {
25
25
  const [number = ""] = version.split("+");
26
26
  return NUMBER.test(number) ? number : undefined;
27
27
  }
28
28
 
29
- /** The number a Version tag names: `v0.4.0` is `0.4.0`, and nothing else is one. */
29
+ /** The number a version tag names: `v0.4.0` is `0.4.0`, and nothing else is one. */
30
30
  export function tagNumber(tag: string): string | undefined {
31
31
  return tag.startsWith("v") ? versionNumber(tag.slice(1)) : undefined;
32
32
  }
33
33
 
34
- /** A Version tag, in both halves its readers want: `v0.4.0` and `0.4.0`. */
34
+ /** A version tag, in both halves its readers want: `v0.4.0` and `0.4.0`. */
35
35
  export interface VersionTag {
36
36
  tag: string;
37
37
  number: string;
38
38
  }
39
39
 
40
40
  /**
41
- * The highest Version among tags shaped `v<x.y.z>`, and undefined where there
42
- * is no Version tag at all — the first Version, which nothing can be measured
41
+ * The highest version among tags shaped `v<x.y.z>`, and undefined where there
42
+ * is no version tag at all — the first version, which nothing can be measured
43
43
  * against.
44
44
  *
45
45
  * Every other tag is ignored rather than refused: a repository is free to tag
46
- * whatever else it likes, and only the Versions say what has been cut. The tag
46
+ * whatever else it likes, and only the versions say what has been cut. The tag
47
47
  * comes back beside its number because a message names the tag as it was cut
48
48
  * and the comparison is on the number.
49
49
  */