ticket-runner 0.6.0
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/LICENSE +21 -0
- package/README.ko.md +97 -0
- package/README.md +98 -0
- package/bin/ticket-runner.js +6 -0
- package/docs/templates/operator-skill.md +87 -0
- package/package.json +42 -0
- package/src/acceptance-criteria.ts +44 -0
- package/src/adapters/claude-agent-runner.ts +389 -0
- package/src/adapters/exec.ts +169 -0
- package/src/adapters/gh-tracker.ts +955 -0
- package/src/adapters/git-workspace.ts +951 -0
- package/src/adapters/repo-root.ts +20 -0
- package/src/adapters/version.ts +118 -0
- package/src/base-branch.ts +21 -0
- package/src/branch.ts +33 -0
- package/src/cli.ts +135 -0
- package/src/command-line.ts +190 -0
- package/src/config.ts +277 -0
- package/src/conventions.ts +118 -0
- package/src/criteria.ts +106 -0
- package/src/frontier.ts +36 -0
- package/src/guards.ts +143 -0
- package/src/handoff.ts +82 -0
- package/src/host.ts +116 -0
- package/src/init.ts +405 -0
- package/src/labels.ts +42 -0
- package/src/landing.ts +75 -0
- package/src/lifecycle.ts +34 -0
- package/src/lock.ts +215 -0
- package/src/note-schema.ts +58 -0
- package/src/notes.ts +433 -0
- package/src/operator-skill.ts +24 -0
- package/src/orchestrator.ts +1816 -0
- package/src/ports/agent-runner.ts +105 -0
- package/src/ports/tracker.ts +334 -0
- package/src/ports/workspace.ts +422 -0
- package/src/progress.ts +231 -0
- package/src/prompts.ts +288 -0
- package/src/readiness.ts +256 -0
- package/src/remove.ts +732 -0
- package/src/resume.ts +145 -0
- package/src/run-log.ts +85 -0
- package/src/run.ts +331 -0
- package/src/self-hosting.ts +33 -0
- package/src/stage-guard.ts +32 -0
- package/src/staleness.ts +101 -0
- package/src/start.ts +284 -0
- package/src/startup.ts +34 -0
- package/src/stop.ts +178 -0
- package/src/stranded.ts +136 -0
- package/src/templates.ts +596 -0
- package/src/title.ts +97 -0
- package/src/verdict.ts +88 -0
- package/src/version-number.ts +67 -0
- package/src/version-pr.ts +103 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Ki-jong Song
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.ko.md
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
# ticket-runner
|
|
2
|
+
|
|
3
|
+
[English](https://github.com/jjongs2/ticket-runner/blob/main/README.md)
|
|
4
|
+
|
|
5
|
+
`ticket-runner`는 [`mattpocock-skills`](https://github.com/mattpocock/skills) 체인에서 사람이 지켜보지
|
|
6
|
+
않아도 되는 절반을 맡습니다. 계획은 그 skill들로 사람이 세우고, `ticket-runner`는 준비된 Ticket을 아무도
|
|
7
|
+
지켜보지 않는 사이 merge된 pull request까지 가져갑니다.
|
|
8
|
+
|
|
9
|
+
## 하는 일
|
|
10
|
+
|
|
11
|
+
체인은 둘로 나뉩니다. **Planning**은 사람 몫입니다. `/grilling`, `/to-spec`, `/to-tickets`(또는
|
|
12
|
+
`/triage`)로 기능 하나를 작은 GitHub 이슈 여러 개로 나눕니다. 이슈마다 `ready-for-agent` 라벨과
|
|
13
|
+
Acceptance Criteria 체크리스트가 달리고, blocker가 연결됩니다. **Execution**은 파이프라인 몫입니다.
|
|
14
|
+
그런 이슈 가운데 blocker가 모두 닫힌 것마다 다음을 합니다.
|
|
15
|
+
|
|
16
|
+
1. 이슈를 맡고, 그 이슈의 branch와 git worktree를 만듭니다.
|
|
17
|
+
2. headless `claude -p` 세션을 띄워 `/implement`로 구현합니다.
|
|
18
|
+
3. 테스트와 typecheck를 직접 돌립니다.
|
|
19
|
+
4. 새 세션을 하나 더 띄워, Acceptance Criteria가 충족되지 *않았음*을 증명해 보게 합니다.
|
|
20
|
+
5. rebase하고, pull request를 열고, CI를 기다린 뒤 squash merge합니다.
|
|
21
|
+
|
|
22
|
+
한 번 실패하면 고치는 세션 한 번과 두 번째 검사를 받습니다. 그래도 끝내지 못한 일은 사람에게 돌아옵니다.
|
|
23
|
+
`ready-for-human` 라벨과 draft pull request, 무엇이 실패했는지 적은 코멘트가 함께 남습니다. 구독의
|
|
24
|
+
rate limit에 걸려 멈춘 세션은 아무것도 잃지 않습니다. 이슈는 보드로 돌아가고, 다음 Run이 멈춘 곳부터
|
|
25
|
+
이어 합니다.
|
|
26
|
+
|
|
27
|
+
## 나에게 맞을까?
|
|
28
|
+
|
|
29
|
+
이런 저장소에 맞습니다.
|
|
30
|
+
|
|
31
|
+
- `mattpocock-skills`로 계획합니다. `/setup-matt-pocock-skills`로 GitHub Issues를 tracker로 한 번
|
|
32
|
+
설정해 두었고, Ticket 하나는 세션 하나로 끝낼 만큼 작습니다.
|
|
33
|
+
- pull request에서 도는 CI 워크플로가 있고, 파이프라인이 직접 돌릴 테스트나 typecheck 명령이 있습니다.
|
|
34
|
+
- 돌리는 머신에 Node 22 이상, `git`, 인증된 [`gh`](https://cli.github.com/), 그리고
|
|
35
|
+
[`mattpocock-skills`](https://github.com/mattpocock/skills) 플러그인 1.2.3 버전을 설치한 `claude`가
|
|
36
|
+
있습니다.
|
|
37
|
+
|
|
38
|
+
파이프라인은 묻지 않고 base branch에 merge합니다. 그걸 원하는 저장소에 쓰세요.
|
|
39
|
+
|
|
40
|
+
## 써 보기
|
|
41
|
+
|
|
42
|
+
파이프라인이 일할 저장소(**Target**)에서:
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
npx ticket-runner init # Target을 준비하고, 아직 빠진 것을 알려 줍니다
|
|
46
|
+
npx ticket-runner run # 준비된 이슈를 모두 처리합니다
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`init`은 검토하고 commit할 파일 몇 개를 씁니다. `.gitignore` 줄, conventions 문서, `CLAUDE.md`의 한
|
|
50
|
+
섹션, Claude skill 하나입니다. 또 triage 라벨을 만들고, squash merge와 merge 시 branch 삭제를 켭니다.
|
|
51
|
+
commit은 하지 않습니다.
|
|
52
|
+
|
|
53
|
+
계속 쓰려면 전역으로 설치하세요.
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npm install -g ticket-runner
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
| 명령 | 하는 일 |
|
|
60
|
+
|---|---|
|
|
61
|
+
| `ticket-runner init` | 이 저장소를 준비하고, 사람이 고쳐야 할 것을 알려 줍니다 |
|
|
62
|
+
| `ticket-runner run` | 준비된 이슈를 하나씩 모두 처리합니다 |
|
|
63
|
+
| `ticket-runner run 12 14` | 같은 일을 하되 #12와 #14만 맡습니다 |
|
|
64
|
+
| `ticket-runner run --lanes 2` | 이슈 두 개를 동시에 처리합니다 |
|
|
65
|
+
| `ticket-runner stop` | 진행 중인 Run에게 맡은 것만 끝내고 더 맡지 말라고 합니다 |
|
|
66
|
+
| `ticket-runner remove` | 이 저장소에서 파이프라인을 걷어 냅니다 |
|
|
67
|
+
| `ticket-runner -v` | Version을 출력합니다 |
|
|
68
|
+
|
|
69
|
+
Claude 앱에서도 Run을 시작할 수 있습니다. Target에서 Claude Code 클라우드 세션을 열고 "run it"이라고
|
|
70
|
+
말하면 됩니다.
|
|
71
|
+
|
|
72
|
+
## 다시 걷어 내기
|
|
73
|
+
|
|
74
|
+
```bash
|
|
75
|
+
ticket-runner remove # Target에서: init이 쓴 것과 Run이 남긴 것
|
|
76
|
+
npm uninstall -g ticket-runner # 전역 설치
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
`remove`는 먼저 묻고(`--yes`를 주면 묻지 않습니다), commit은 하지 않습니다. 열린 pull request나 코멘트를
|
|
80
|
+
단 이슈처럼 일부러 남겨 둔 것은 보고에 적어 줍니다. `npx`는 캐시 말고는 아무것도 남기지 않습니다.
|
|
81
|
+
|
|
82
|
+
## 더 알아보기
|
|
83
|
+
|
|
84
|
+
[프로젝트 wiki](https://jjongs2.github.io/ticket-runner/ko/)에서 파이프라인을 자세히 설명합니다.
|
|
85
|
+
|
|
86
|
+
- [설치와 제거](https://jjongs2.github.io/ticket-runner/ko/guide/installation)
|
|
87
|
+
- [일 계획하기](https://jjongs2.github.io/ticket-runner/ko/guide/planning)
|
|
88
|
+
- [실행하기](https://jjongs2.github.io/ticket-runner/ko/guide/running)
|
|
89
|
+
- [설정](https://jjongs2.github.io/ticket-runner/ko/guide/configuration)
|
|
90
|
+
- [Ticket 하나가 merge되기까지](https://jjongs2.github.io/ticket-runner/ko/guide/ticket-to-merge)
|
|
91
|
+
- [멈추고 이어 하기](https://jjongs2.github.io/ticket-runner/ko/guide/stopping-and-resuming)
|
|
92
|
+
- [내부 구조](https://jjongs2.github.io/ticket-runner/ko/guide/internals)
|
|
93
|
+
|
|
94
|
+
용어는 [`CONTEXT.md`](https://github.com/jjongs2/ticket-runner/blob/main/CONTEXT.md)에, 설계 결정은
|
|
95
|
+
[`docs/adr/`](https://github.com/jjongs2/ticket-runner/tree/main/docs/adr)에, 파이프라인 자체를 고칠
|
|
96
|
+
때의 규칙은 [`CONTRIBUTING.md`](https://github.com/jjongs2/ticket-runner/blob/main/CONTRIBUTING.md)에
|
|
97
|
+
있습니다. 모두 영어입니다.
|
package/README.md
ADDED
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# ticket-runner
|
|
2
|
+
|
|
3
|
+
[한국어](https://github.com/jjongs2/ticket-runner/blob/main/README.ko.md)
|
|
4
|
+
|
|
5
|
+
`ticket-runner` runs the unattended half of the
|
|
6
|
+
[`mattpocock-skills`](https://github.com/mattpocock/skills) chain. You plan with its skills; it
|
|
7
|
+
takes every ready Ticket to a merged pull request while nobody watches.
|
|
8
|
+
|
|
9
|
+
## What it does
|
|
10
|
+
|
|
11
|
+
The chain is split in two. **Planning** is yours: `/grilling`, `/to-spec` and `/to-tickets` (or
|
|
12
|
+
`/triage`) turn a feature into small GitHub issues, each labelled `ready-for-agent`, with a
|
|
13
|
+
checklist of Acceptance Criteria and its blockers linked. **Execution** is the pipeline's. For
|
|
14
|
+
every such issue whose blockers have closed, it:
|
|
15
|
+
|
|
16
|
+
1. claims the issue and creates a branch and a git worktree for it
|
|
17
|
+
2. runs a headless `claude -p` session that implements it with `/implement`
|
|
18
|
+
3. runs your tests and typecheck itself
|
|
19
|
+
4. runs a second, fresh session that tries to prove the Acceptance Criteria are *not* met
|
|
20
|
+
5. rebases, opens a pull request, waits for CI and squash-merges
|
|
21
|
+
|
|
22
|
+
One failure buys one fix session and a second pass. Anything it still cannot finish goes back
|
|
23
|
+
to you, labelled `ready-for-human`, with a draft pull request and a comment saying what failed.
|
|
24
|
+
A session stopped by your subscription's rate limit costs nothing: the issue goes back on the
|
|
25
|
+
board, and the next Run carries on from where it stopped.
|
|
26
|
+
|
|
27
|
+
## Is it for you?
|
|
28
|
+
|
|
29
|
+
It fits a repository where:
|
|
30
|
+
|
|
31
|
+
- you plan with `mattpocock-skills`, set up once with `/setup-matt-pocock-skills` and GitHub
|
|
32
|
+
Issues as the tracker, and each Ticket is small enough for one session
|
|
33
|
+
- a CI workflow runs on pull requests, and there is a test or typecheck command the pipeline can
|
|
34
|
+
run itself
|
|
35
|
+
- the machine running it has Node 22 or newer, `git`, an authenticated
|
|
36
|
+
[`gh`](https://cli.github.com/), and `claude` with the
|
|
37
|
+
[`mattpocock-skills`](https://github.com/mattpocock/skills) plugin, version 1.2.3
|
|
38
|
+
|
|
39
|
+
It merges to your base branch without asking. It is for repositories where that is what you want.
|
|
40
|
+
|
|
41
|
+
## Try it
|
|
42
|
+
|
|
43
|
+
In the repository you want it to work in (the **Target**):
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npx ticket-runner init # set the Target up and report what is still missing
|
|
47
|
+
npx ticket-runner run # work through every ready issue
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`init` writes a few files for you to review and commit: `.gitignore` lines, a conventions
|
|
51
|
+
document, a section in `CLAUDE.md` and a Claude skill. It also creates the triage labels and
|
|
52
|
+
turns on squash merging and branch deletion on merge. It commits nothing.
|
|
53
|
+
|
|
54
|
+
To keep it, install it globally:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
npm install -g ticket-runner
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
| Command | What it does |
|
|
61
|
+
|---|---|
|
|
62
|
+
| `ticket-runner init` | Set this repository up, and report what only you can put right |
|
|
63
|
+
| `ticket-runner run` | Work through every ready issue, one at a time |
|
|
64
|
+
| `ticket-runner run 12 14` | The same, taking only #12 and #14 |
|
|
65
|
+
| `ticket-runner run --lanes 2` | Two issues at once |
|
|
66
|
+
| `ticket-runner stop` | Ask the Run in progress to finish what it holds and take no more |
|
|
67
|
+
| `ticket-runner remove` | Take the pipeline out of this repository |
|
|
68
|
+
| `ticket-runner -v` | Print the Version |
|
|
69
|
+
|
|
70
|
+
A Run can also be started from the Claude app, in a Claude Code cloud session on the Target:
|
|
71
|
+
say "run it".
|
|
72
|
+
|
|
73
|
+
## Take it out again
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
ticket-runner remove # in the Target: what init wrote and what Runs left behind
|
|
77
|
+
npm uninstall -g ticket-runner # the global install
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`remove` asks first (`--yes` skips the question), commits nothing, and reports what it left
|
|
81
|
+
alone on purpose, such as open pull requests and the issues it commented on. `npx` leaves nothing
|
|
82
|
+
behind but its cache.
|
|
83
|
+
|
|
84
|
+
## Learn more
|
|
85
|
+
|
|
86
|
+
The [project wiki](https://jjongs2.github.io/ticket-runner/) explains the pipeline in depth:
|
|
87
|
+
|
|
88
|
+
- [Install and remove](https://jjongs2.github.io/ticket-runner/guide/installation)
|
|
89
|
+
- [Planning the work](https://jjongs2.github.io/ticket-runner/guide/planning)
|
|
90
|
+
- [Running](https://jjongs2.github.io/ticket-runner/guide/running)
|
|
91
|
+
- [Configuration](https://jjongs2.github.io/ticket-runner/guide/configuration)
|
|
92
|
+
- [From Ticket to merge](https://jjongs2.github.io/ticket-runner/guide/ticket-to-merge)
|
|
93
|
+
- [Stopping and resuming](https://jjongs2.github.io/ticket-runner/guide/stopping-and-resuming)
|
|
94
|
+
- [Internals](https://jjongs2.github.io/ticket-runner/guide/internals)
|
|
95
|
+
|
|
96
|
+
The vocabulary is defined in [`CONTEXT.md`](https://github.com/jjongs2/ticket-runner/blob/main/CONTEXT.md), the decisions in
|
|
97
|
+
[`docs/adr/`](https://github.com/jjongs2/ticket-runner/tree/main/docs/adr), and the conventions for working on the pipeline itself in
|
|
98
|
+
[`CONTRIBUTING.md`](https://github.com/jjongs2/ticket-runner/blob/main/CONTRIBUTING.md).
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ticket-runner
|
|
3
|
+
description: Operate ticket-runner on this repository from a Claude Code cloud session — ready the Host, start a Run in the background, narrowed to the Tickets the human names when they name any, report what it prints, pass on a Stop, and release a Run lock a vanished Host left behind. Use when the human asks to run the pipeline ("run it"), to work particular Tickets, to stop the Run, or to release its lock. Never from a Stage.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Operating ticket-runner
|
|
7
|
+
|
|
8
|
+
You are the Operator: the Claude session a human opened on this repository to run `ticket-runner` for them, and to watch and steer it from the app. You start the Run, report what it prints, pass on a Stop, and release a lock when asked. Nothing else. The Run does the work, and everything else a human wants of a Ticket goes through the board.
|
|
9
|
+
|
|
10
|
+
If `TICKET_RUNNER_STAGE` is set in your shell, you are a Stage of a Run, not an Operator. Stop here and use none of this.
|
|
11
|
+
|
|
12
|
+
## Ready the Host
|
|
13
|
+
|
|
14
|
+
Install only what this Host does not already have. What the cloud environment's setup script installed is used as it is, whichever Version it is.
|
|
15
|
+
|
|
16
|
+
1. The pipeline. If `ticket-runner --version` answers, use that copy. Otherwise read the Version on the first line of `docs/agents/pipeline-conventions.md`, the `<number>` in `<!-- ticket-runner:version <number> -->`, and install that Version:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
npm install -g "github:jjongs2/ticket-runner#v<number>"
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
If the first line carries no Version, install nothing and tell the human to run `ticket-runner init` on this repository from a workstation.
|
|
23
|
+
|
|
24
|
+
2. The skills plugin. If `claude plugin list` lists `mattpocock-skills`, it is there. Otherwise register the official marketplace first, then install the plugin from it:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
claude plugin marketplace add anthropics/claude-plugins-official
|
|
28
|
+
claude plugin install mattpocock-skills@claude-plugins-official
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
3. `gh`. If `command -v gh` finds it, use it. Otherwise install it from apt, as below when the shell runs as root and through `sudo -n` when it does not:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
apt-get update
|
|
35
|
+
apt-get install -y gh
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
The `gh` apt offers is older than GitHub's own, and enough: the pipeline reaches GitHub through `gh api` alone. If the install fails, start nothing and tell the human what apt printed: a Run started without `gh` is refused as a Target that is not set up, saying only that `gh` is not installed and must be installed first.
|
|
39
|
+
|
|
40
|
+
4. This repository's own dependencies, in this checkout. Every Ticket's worktree lives inside this checkout, and a Check that finds nothing installed in its worktree uses what is installed here, so without them every Check fails to start and spends its Ticket's fix budget on that. If they are installed here already, `node_modules/` beside a `package.json` for instance, use them as they are. Otherwise work out the install command from what this repository declares, its lockfile first and then its README or contributing guide, and run it at the root of this checkout: `npm ci` beside a `package-lock.json`, say. A repository that declares no dependencies needs nothing here. If the install fails, start nothing and tell the human what the install printed.
|
|
41
|
+
|
|
42
|
+
Tell the human in one line which of these you installed, this repository's dependencies included, or that nothing was missing.
|
|
43
|
+
|
|
44
|
+
## Start
|
|
45
|
+
|
|
46
|
+
Start what the human asked for as a background command, so the session stays free to answer them while it runs:
|
|
47
|
+
|
|
48
|
+
- `ticket-runner run` to work through every Ticket that is ready.
|
|
49
|
+
- `ticket-runner run <n>...` when the human names Tickets, one number each. The Run takes only those, lowest number first whatever order they were named in, and leaves every other Ticket alone.
|
|
50
|
+
- `ticket-runner run --lanes <count>` when the human asks for a number of Tickets at once, with or without numbers. Pass it only when they do; otherwise the repository's own config decides.
|
|
51
|
+
|
|
52
|
+
Start one at a time. While a Run of yours is running, start no other.
|
|
53
|
+
|
|
54
|
+
## Report
|
|
55
|
+
|
|
56
|
+
Report what the Run prints as it prints it, in a form a phone screen reads: one short line per Ticket that ended, saying which Ticket and whether it merged, was handed off, was released or was skipped, and why when the Run gives a reason. Pass on a refusal as it is worded: it names what to do.
|
|
57
|
+
|
|
58
|
+
When the Run ends, report its summary and what its exit code means: `1` at least one Ticket was handed off to a human, `2` nothing was taken at all, because the Run was refused or because it was given Ticket numbers and took none of them, every one skipped or blocked, and `0` otherwise.
|
|
59
|
+
|
|
60
|
+
## Stop
|
|
61
|
+
|
|
62
|
+
When the human asks for a Stop, send the Run SIGTERM by running `ticket-runner stop`, which signals the Run this Host holds the lock for. Report what it prints, then keep reporting the Run: a Stop finishes the Tickets the Run already holds and takes no more, so the Run ends by itself with its summary, whether or not it was given Ticket numbers. Never end a Run any other way. SIGINT or SIGKILL ends it in the middle of a Ticket.
|
|
63
|
+
|
|
64
|
+
## Release a lock another Host left
|
|
65
|
+
|
|
66
|
+
A Run is refused when a Run on another Host holds the lock on the `ticket-runner/lock` branch. Report the refusal, which names that Host, its Run and when it started, and wait. Release the lock only when the human asks you to and no Run of yours is running. Then commit a free `lock.json` on top of the tip you read, with a lease on that tip, so a Run that took the lock meanwhile keeps it:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
git fetch origin ticket-runner/lock
|
|
70
|
+
tip=$(git rev-parse FETCH_HEAD)
|
|
71
|
+
git show "$tip:lock.json"
|
|
72
|
+
index=$(mktemp -u)
|
|
73
|
+
GIT_INDEX_FILE=$index git read-tree "$tip"
|
|
74
|
+
blob=$(printf '{ "held": false }\n' | git hash-object -w --stdin)
|
|
75
|
+
GIT_INDEX_FILE=$index git update-index --add --cacheinfo "100644,$blob,lock.json"
|
|
76
|
+
tree=$(GIT_INDEX_FILE=$index git write-tree)
|
|
77
|
+
rm -f "$index"
|
|
78
|
+
free=$(git commit-tree --no-gpg-sign "$tree" -p "$tip" -m "Free")
|
|
79
|
+
git push --no-verify --force-with-lease="refs/heads/ticket-runner/lock:$tip" origin "$free:refs/heads/ticket-runner/lock"
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Check that the `lock.json` it shows names the Host the refusal named before you push. If the push is refused, the lock moved: read it again and tell the human who holds it now. Delete nothing, on the remote or here.
|
|
83
|
+
|
|
84
|
+
## What you leave alone
|
|
85
|
+
|
|
86
|
+
- While your Run holds this repository, leave the checkout and `.worktrees/` alone. Edit no file, and run no git command that changes them: no checkout, pull, commit, stash, reset or worktree command. The Run pulls this checkout after every merge, and an edit of yours breaks that pull.
|
|
87
|
+
- Relabel, comment on, close or edit no issue or pull request, and change no code. When the human asks for anything about a Ticket other than running it, stopping the Run or releasing the lock, tell them to do it on the board: a label, a comment or an edit to the issue is how a Run is steered.
|
package/package.json
ADDED
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "ticket-runner",
|
|
3
|
+
"version": "0.6.0",
|
|
4
|
+
"description": "Drives the mattpocock-skills chain unattended: humans plan, the pipeline executes.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/jjongs2/ticket-runner.git"
|
|
9
|
+
},
|
|
10
|
+
"type": "module",
|
|
11
|
+
"engines": {
|
|
12
|
+
"node": ">=22"
|
|
13
|
+
},
|
|
14
|
+
"bin": {
|
|
15
|
+
"ticket-runner": "./bin/ticket-runner.js"
|
|
16
|
+
},
|
|
17
|
+
"files": [
|
|
18
|
+
"bin",
|
|
19
|
+
"src",
|
|
20
|
+
"!src/**/*.test.ts",
|
|
21
|
+
"!src/testing",
|
|
22
|
+
"docs/templates/operator-skill.md"
|
|
23
|
+
],
|
|
24
|
+
"scripts": {
|
|
25
|
+
"ticket-runner": "tsx src/cli.ts",
|
|
26
|
+
"test": "vitest run",
|
|
27
|
+
"test:watch": "vitest",
|
|
28
|
+
"typecheck": "tsc --noEmit"
|
|
29
|
+
},
|
|
30
|
+
"dependencies": {
|
|
31
|
+
"tsx": "^4.20.6",
|
|
32
|
+
"zod": "^4.1.12"
|
|
33
|
+
},
|
|
34
|
+
"devDependencies": {
|
|
35
|
+
"@types/node": "^22.18.9",
|
|
36
|
+
"typescript": "^5.9.3",
|
|
37
|
+
"vitest": "^3.2.4"
|
|
38
|
+
},
|
|
39
|
+
"allowScripts": {
|
|
40
|
+
"esbuild@0.28.2": true
|
|
41
|
+
}
|
|
42
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What an Acceptance Criterion looks like, for everything that reads one.
|
|
3
|
+
*
|
|
4
|
+
* Readers recognise a criterion by its shape and would disagree about it if each
|
|
5
|
+
* carried its own pattern: the `no-criteria` guard counts one to decide a Ticket
|
|
6
|
+
* is usable, the merge ticks one a Verdict proved and then counts the boxes it
|
|
7
|
+
* ticked, and a Note has one escaped before it is posted. Drift between them is
|
|
8
|
+
* not a cosmetic bug — a criterion the guard sees but the escaper misses lets a
|
|
9
|
+
* Note read as work somebody promised, and one the merge ticks but the guard
|
|
10
|
+
* never counted merges a Ticket on a checkbox nobody graded. So the line head
|
|
11
|
+
* every criterion shares is written here once and every matcher derives from
|
|
12
|
+
* it.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* A task list item at the head of a line, up to its box: optional indent, then a
|
|
17
|
+
* `-`, `*` or `+` bullet and one space. Deliberately narrow — an item anywhere
|
|
18
|
+
* else on a line is prose, and widening this widens every reader at once.
|
|
19
|
+
*
|
|
20
|
+
* Group 1 is the indent and bullet, for the readers that rewrite a line and put
|
|
21
|
+
* it back untouched. A reader that only counts lines ignores it.
|
|
22
|
+
*/
|
|
23
|
+
const ITEM_HEAD = String.raw`^([ \t]*[-*+] )`;
|
|
24
|
+
|
|
25
|
+
/**
|
|
26
|
+
* An {@link ITEM_HEAD} whose box is empty: what every reader of a Ticket calls
|
|
27
|
+
* an Acceptance Criterion.
|
|
28
|
+
*
|
|
29
|
+
* A pattern source rather than a `RegExp`, because each reader needs different
|
|
30
|
+
* flags and captures around the same head.
|
|
31
|
+
*/
|
|
32
|
+
export const UNCHECKED_BOX = String.raw`${ITEM_HEAD}\[ \]`;
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* The ticked twin, for the merge alone: having ticked what a Verdict proved, it
|
|
36
|
+
* counts the boxes now ticked to tell whether a met criterion matched nothing.
|
|
37
|
+
*
|
|
38
|
+
* It shares {@link UNCHECKED_BOX}'s head so that count cannot drift from the
|
|
39
|
+
* tick — a head only one of the two recognised would have the merge announce a
|
|
40
|
+
* criterion matched no checkbox right after ticking its box. `[x]` only: the
|
|
41
|
+
* merge writes that, and a box this misses was ticked by a human, in both the
|
|
42
|
+
* before and the after of the same count.
|
|
43
|
+
*/
|
|
44
|
+
export const TICKED_BOX = String.raw`${ITEM_HEAD}\[x\]`;
|