taskproof 0.3.0__py3-none-any.whl
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.
- taskproof/__init__.py +23 -0
- taskproof/__main__.py +8 -0
- taskproof/adapters/__init__.py +101 -0
- taskproof/adapters/base.py +228 -0
- taskproof/adapters/claude.py +46 -0
- taskproof/adapters/codex.py +140 -0
- taskproof/adapters/custom.py +61 -0
- taskproof/adapters/gemini.py +45 -0
- taskproof/adapters/opencode.py +46 -0
- taskproof/api/__init__.py +1 -0
- taskproof/api/server.py +822 -0
- taskproof/cli.py +1400 -0
- taskproof/concurrency.py +329 -0
- taskproof/dispatch.py +2289 -0
- taskproof/errors.py +55 -0
- taskproof/ledger.py +185 -0
- taskproof/models.py +155 -0
- taskproof/registry.py +1585 -0
- taskproof/schemas/result.json +58 -0
- taskproof/sql/schema.sql +70 -0
- taskproof/storage.py +372 -0
- taskproof/verify.py +615 -0
- taskproof/web/assets/MatrixView-BM8nu9s2.css +446 -0
- taskproof/web/assets/MatrixView-BM8nu9s2.css.gz +0 -0
- taskproof/web/assets/MatrixView-BMsawnxh.js +475 -0
- taskproof/web/assets/MatrixView-BMsawnxh.js.gz +0 -0
- taskproof/web/assets/ProjectsView-BcXcx5Gw.js +302 -0
- taskproof/web/assets/ProjectsView-BcXcx5Gw.js.gz +0 -0
- taskproof/web/assets/ProjectsView-CqNFL-fi.css +23 -0
- taskproof/web/assets/SettingsView-D_-waf0s.js +585 -0
- taskproof/web/assets/SettingsView-D_-waf0s.js.gz +0 -0
- taskproof/web/assets/SettingsView-aqTS3ubB.css +19 -0
- taskproof/web/assets/TaskDrawer-6JoGTH0s.js +597 -0
- taskproof/web/assets/TaskDrawer-6JoGTH0s.js.gz +0 -0
- taskproof/web/assets/TaskDrawer-N299VKzd.css +465 -0
- taskproof/web/assets/TaskDrawer-N299VKzd.css.gz +0 -0
- taskproof/web/assets/TasksView-BWhSHCHi.js +114 -0
- taskproof/web/assets/TasksView-BWhSHCHi.js.gz +0 -0
- taskproof/web/assets/TasksView-Bn08731V.css +30 -0
- taskproof/web/assets/icon-Dw-ohsdc.png +0 -0
- taskproof/web/assets/index-B-PLdDbR.js +75421 -0
- taskproof/web/assets/index-B-PLdDbR.js.gz +0 -0
- taskproof/web/assets/index-NKj7kbYl.css +1234 -0
- taskproof/web/assets/index-NKj7kbYl.css.gz +0 -0
- taskproof/web/index.html +23 -0
- taskproof-0.3.0.dist-info/METADATA +470 -0
- taskproof-0.3.0.dist-info/RECORD +51 -0
- taskproof-0.3.0.dist-info/WHEEL +5 -0
- taskproof-0.3.0.dist-info/entry_points.txt +2 -0
- taskproof-0.3.0.dist-info/licenses/LICENSE +201 -0
- taskproof-0.3.0.dist-info/top_level.txt +1 -0
|
Binary file
|
taskproof/web/index.html
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
<!doctype html>
|
|
2
|
+
<html lang="zh-CN" data-theme="dark" class="dark">
|
|
3
|
+
<head>
|
|
4
|
+
<meta charset="UTF-8" />
|
|
5
|
+
<title>Taskproof</title>
|
|
6
|
+
<!--
|
|
7
|
+
The renderer only ever talks to its own bundle and to the loopback API on
|
|
8
|
+
a port chosen at launch, so `connect-src` has to allow 127.0.0.1 on any
|
|
9
|
+
port. Without that clause every request to the API is blocked by the CSP
|
|
10
|
+
and the app looks like it simply has no data.
|
|
11
|
+
-->
|
|
12
|
+
<meta
|
|
13
|
+
http-equiv="Content-Security-Policy"
|
|
14
|
+
content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self' data:; connect-src 'self' http://127.0.0.1:*"
|
|
15
|
+
/>
|
|
16
|
+
<script type="module" crossorigin src="./assets/index-B-PLdDbR.js"></script>
|
|
17
|
+
<link rel="stylesheet" crossorigin href="./assets/index-NKj7kbYl.css">
|
|
18
|
+
</head>
|
|
19
|
+
|
|
20
|
+
<body>
|
|
21
|
+
<div id="app"></div>
|
|
22
|
+
</body>
|
|
23
|
+
</html>
|
|
@@ -0,0 +1,470 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: taskproof
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: A conveyor belt for AI coding agents: dispatch, independently verify, record.
|
|
5
|
+
Author-email: HaoHaoP <HaoHaoP@HaoHaoP.com>
|
|
6
|
+
License: Apache-2.0
|
|
7
|
+
Project-URL: Homepage, https://github.com/HaoHaoP/taskproof
|
|
8
|
+
Project-URL: Issues, https://github.com/HaoHaoP/taskproof/issues
|
|
9
|
+
Keywords: ai-agents,orchestration,verification,codex,claude-code,cli
|
|
10
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Software Development :: Build Tools
|
|
16
|
+
Requires-Python: >=3.11
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Dynamic: license-file
|
|
20
|
+
|
|
21
|
+
# taskproof
|
|
22
|
+
|
|
23
|
+
**English** · [简体中文](README.zh-CN.md)
|
|
24
|
+
|
|
25
|
+
<p align="center"><img src="docs/assets/icon.png" width="128" alt="taskproof"></p>
|
|
26
|
+
|
|
27
|
+
A conveyor belt for AI coding agents.
|
|
28
|
+
|
|
29
|
+
It does not decide *what* to do. It guarantees that whatever gets dispatched is
|
|
30
|
+
**independently verified** and **recorded** — so you never have to trust an
|
|
31
|
+
agent's own claim that it finished.
|
|
32
|
+
|
|
33
|
+
<p align="center"><img src="docs/assets/demo.gif" width="820" alt="A card is dispatched, the agent claims it is done, and the machine disagrees."></p>
|
|
34
|
+
|
|
35
|
+
*A card is dispatched. The agent says it finished. The record says it changed nothing — the acceptance command is what decides.*
|
|
36
|
+
|
|
37
|
+
**Status: stage 1 is usable, and the stage-2 desktop console is here.** The
|
|
38
|
+
engine, CLI, a browser board, a local read-only REST API, and an Electron console
|
|
39
|
+
in `desktop/` are implemented. See [`docs/DESIGN.md`](docs/DESIGN.md) for the
|
|
40
|
+
full design and the decision log, and
|
|
41
|
+
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for how each mechanism works today,
|
|
42
|
+
with diagrams.
|
|
43
|
+
|
|
44
|
+
## Install
|
|
45
|
+
|
|
46
|
+
Two ways in: the desktop console if you do not write code, the command line if
|
|
47
|
+
you do.
|
|
48
|
+
|
|
49
|
+
### Desktop console
|
|
50
|
+
|
|
51
|
+
Download the installer for your platform from the
|
|
52
|
+
[GitHub Releases](https://github.com/HaoHaoP/taskproof/releases) page:
|
|
53
|
+
|
|
54
|
+
- macOS arm64 (Apple silicon) — `.dmg`
|
|
55
|
+
- Windows x64 — `.exe`
|
|
56
|
+
- Linux x64 — `.AppImage` / `.deb`
|
|
57
|
+
|
|
58
|
+
The installers are **not signed and not notarised**:
|
|
59
|
+
|
|
60
|
+
- **macOS is arm64 only** (no Intel or Rosetta build): on first launch,
|
|
61
|
+
right-click the app → Open, or run
|
|
62
|
+
`xattr -d com.apple.quarantine /Applications/Taskproof.app`.
|
|
63
|
+
- **Windows 10+**: SmartScreen shows a warning on first launch.
|
|
64
|
+
|
|
65
|
+
Minimum versions are macOS 11+, Windows 10+, or a current mainstream Linux
|
|
66
|
+
distribution. Each installer **ships its own Python runtime**, so there is
|
|
67
|
+
nothing to `pip install` — but it does need a system **`git`** for worktrees and
|
|
68
|
+
the protected-path gate. Without git the settings page says so, and everything
|
|
69
|
+
else keeps working.
|
|
70
|
+
|
|
71
|
+
### Command line
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pipx install git+https://github.com/HaoHaoP/taskproof
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Or download the wheel from the same Release and install the local file:
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
pipx install ./taskproof-<version>-py3-none-any.whl
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The wheel's filename carries the version — take it from the Release you just
|
|
84
|
+
downloaded; there is no unpinned wheel name to copy.
|
|
85
|
+
|
|
86
|
+
Or run from a source checkout:
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
pip install -e .
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
**There is no `taskproof` package on PyPI.** Do not look for it there; use one of
|
|
93
|
+
the three installs above.
|
|
94
|
+
|
|
95
|
+
## Run a task
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
taskproof init
|
|
99
|
+
taskproof register /absolute/path/to/your/repo
|
|
100
|
+
taskproof run <project> "fix the failing test"
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
`run` is the whole lifecycle in one line: it **dispatches** the card to a
|
|
104
|
+
pluggable adapter (codex / claude / gemini / opencode, or `custom:<cmd>`), then
|
|
105
|
+
**independently runs the acceptance command** from the registry once the agent
|
|
106
|
+
exits, and finally **records** every step in the audit ledger. The agent's own
|
|
107
|
+
"done" is never the verdict.
|
|
108
|
+
|
|
109
|
+
`taskproof tasks` lists what is in flight; `taskproof show <id>` and
|
|
110
|
+
`taskproof log <id>` read one card back.
|
|
111
|
+
|
|
112
|
+
The desktop console shares the same ledger. On first launch it creates
|
|
113
|
+
`~/.taskproof` as an **empty workspace** — a `[defaults]` table and a commented
|
|
114
|
+
example, with **no sample projects and no sample tasks** — and the board's empty
|
|
115
|
+
state points you at the Projects page (or `taskproof register <path>`). Because
|
|
116
|
+
the console and the CLI read the same `~/.taskproof`, either one sees the other's
|
|
117
|
+
cards.
|
|
118
|
+
|
|
119
|
+
[`docs/WALKTHROUGH.md`](docs/WALKTHROUGH.md) runs this end to end on a throwaway
|
|
120
|
+
example — including the case where the agent reports success and the acceptance
|
|
121
|
+
command disagrees.
|
|
122
|
+
|
|
123
|
+
---
|
|
124
|
+
|
|
125
|
+
## Dispatching work
|
|
126
|
+
|
|
127
|
+
The usage this project is extracted from is a *discipline for the agent that
|
|
128
|
+
hands out the cards*, and it now ships in the repository as a skill:
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
skills/taskproof-dispatch/SKILL.md
|
|
132
|
+
skills/taskproof-dispatch/SKILL.zh-CN.md
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
It is the **operating manual for an AI coding agent** — the orchestrating one
|
|
136
|
+
that plans the work, registers the repositories, writes each card, and dispatches
|
|
137
|
+
it to a worker. Taskproof itself does not plan anything (see Non-goals); this
|
|
138
|
+
skill is the missing half: how to drive the tool without the failure modes the
|
|
139
|
+
hard way. Both languages ship: `SKILL.md` (English) and `SKILL.zh-CN.md`
|
|
140
|
+
(简体中文).
|
|
141
|
+
|
|
142
|
+
The rules in it are not invented; each is a lesson from breaking something.
|
|
143
|
+
`pkill -f` is the classic one, for instance: a card is passed as process argv, so
|
|
144
|
+
the pattern also matches the dispatcher itself and kills the run — exactly the
|
|
145
|
+
kind of practical rule the skill exists to record. It turns the
|
|
146
|
+
lessons of this build into steps you can copy: register a project,
|
|
147
|
+
put a card in a file and pass it with `$(cat …)`, fire it with an explicit
|
|
148
|
+
`--adapter` and `--timeout`, then read state back with `taskproof tasks --all`
|
|
149
|
+
and `taskproof log <id>`. Above all it pins four things that were learned by
|
|
150
|
+
breaking them:
|
|
151
|
+
|
|
152
|
+
- **Serialisation is a property of the group, not a habit.** Different groups
|
|
153
|
+
are meant to run in parallel up to the global cap; the only reason to serialise
|
|
154
|
+
is "same group *and* overlapping files".
|
|
155
|
+
- **The real registry is never a test target.** UI verification runs against a
|
|
156
|
+
throwaway profile and workspace under `/tmp`; a worker that deletes against the
|
|
157
|
+
live `~/.taskproof/projects.toml` takes a user's project with it.
|
|
158
|
+
- **Never `pkill -f`.** A card is passed as process argv, so its text is in the
|
|
159
|
+
dispatcher's own command line — `pkill -f` matches the dispatcher and kills the
|
|
160
|
+
run (exit -15, no task, empty log). Kill by PID.
|
|
161
|
+
- **Review is not a self-report.** The main agent reads the acceptance result the
|
|
162
|
+
machine already produced and asserts the dimensions it cannot see; re-running the
|
|
163
|
+
command is for the three exceptions only — `SKIPPED`, a coverage gap, a green that
|
|
164
|
+
smells false. "The worker said done" is not evidence.
|
|
165
|
+
|
|
166
|
+
## The problem
|
|
167
|
+
|
|
168
|
+
Every orchestration project on GitHub competes on *how many agents it can run*,
|
|
169
|
+
*how many CLIs it supports*, and *how pretty the UI is*. Almost none of them
|
|
170
|
+
talk about the thing that actually bites you in daily use:
|
|
171
|
+
|
|
172
|
+
**Agents lie.**
|
|
173
|
+
|
|
174
|
+
Real incidents from the workflow this project is extracted from:
|
|
175
|
+
|
|
176
|
+
| What the agent said | What actually happened |
|
|
177
|
+
|---|---|
|
|
178
|
+
| "Verified in browser, screenshots attached" | Event stream contained zero browser activity |
|
|
179
|
+
| (silently, beyond scope) | Attempted an HTTP login against a local app using a guessed weak credential |
|
|
180
|
+
| Task complete, result file written | The JSON had been wrapped in a markdown fence, so the structured parse failed and the run looked like it did nothing |
|
|
181
|
+
| Task complete | The acceptance command failed when run independently |
|
|
182
|
+
|
|
183
|
+
None of these are exotic. They are the normal failure mode of handing file-writing
|
|
184
|
+
work to an autonomous process.
|
|
185
|
+
|
|
186
|
+
## What taskproof is
|
|
187
|
+
|
|
188
|
+
A small, mechanical dispatch layer that wraps every agent invocation in
|
|
189
|
+
discipline:
|
|
190
|
+
|
|
191
|
+
- **Independent verification** — the agent's self-report never counts as success.
|
|
192
|
+
The acceptance command from the project registry is run afterwards, by taskproof.
|
|
193
|
+
- **Protected paths** — a registry entry can declare paths an agent must not touch.
|
|
194
|
+
- **Structured result contract** — a defined output shape, with documented
|
|
195
|
+
degradation for CLIs that cannot produce it.
|
|
196
|
+
- **Append-only audit trail** — every dispatch, verification, failure and retry is
|
|
197
|
+
recorded, so "what happened yesterday" is a query, not a memory exercise.
|
|
198
|
+
- **Meaningful exit codes** — callers can distinguish "the agent failed" from
|
|
199
|
+
"the agent succeeded but verification failed".
|
|
200
|
+
- **No LLM inside** — taskproof does not plan, decompose, or decide. Any agent
|
|
201
|
+
(or a human, or a script) can drive it.
|
|
202
|
+
|
|
203
|
+
## Shape
|
|
204
|
+
|
|
205
|
+
```
|
|
206
|
+
taskproof run <project> "<task>" # dispatch, then verify, then record
|
|
207
|
+
taskproof wait <id> # block until a card reaches a terminal state
|
|
208
|
+
taskproof tasks / show / log # inspect state
|
|
209
|
+
taskproof board # serve the board and open a browser (blocks)
|
|
210
|
+
taskproof board --serve 8788 # serve the board only, no browser (blocks)
|
|
211
|
+
taskproof api --port 8787 # local read-only REST API for clients
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
- Python, standard library only, `pipx install`-able
|
|
215
|
+
- SQLite for state (transactional claims, not lock files)
|
|
216
|
+
- JSONL audit stream, write-only, rotated monthly
|
|
217
|
+
- Pluggable adapters (codex / claude / gemini / opencode + any command)
|
|
218
|
+
|
|
219
|
+
## The concurrency cap
|
|
220
|
+
|
|
221
|
+
The global cap is workspace-level and is always reported as a **value plus where
|
|
222
|
+
it came from**, never a bare number. It has three sources, in precedence order:
|
|
223
|
+
|
|
224
|
+
1. `run --cap N` — a one-off for this dispatch only, never persisted;
|
|
225
|
+
2. `[defaults] concurrency` in the registry;
|
|
226
|
+
3. auto-detected from the machine.
|
|
227
|
+
|
|
228
|
+
The auto fallback is deliberately conservative — one slot is a whole extra
|
|
229
|
+
coding agent:
|
|
230
|
+
|
|
231
|
+
```
|
|
232
|
+
cap = clamp(2, cores // 4, 6) # at most one slot per four cores
|
|
233
|
+
if RAM < 8 GiB: cap = 2 # a small box cannot afford cores // 4
|
|
234
|
+
if the core count is unknown: cap = 3
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
Inspect the effective value and its source:
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
taskproof config --show
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Change the persisted value, comment-preserving:
|
|
244
|
+
|
|
245
|
+
```bash
|
|
246
|
+
taskproof config --concurrency N
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
`run --cap N` overrides it for one dispatch only. **Lowering the cap is not
|
|
250
|
+
retroactive**: it never touches a card already running — the CLI prints the cards
|
|
251
|
+
that now exceed the new cap and leaves the decision to you.
|
|
252
|
+
|
|
253
|
+
## Terminal states and the two gates
|
|
254
|
+
|
|
255
|
+
Two terminal states are deliberately different:
|
|
256
|
+
|
|
257
|
+
- **`blocked`** — a boundary breach: the run touched a path the registry forbids.
|
|
258
|
+
The acceptance may even have passed; the gate is what stopped it.
|
|
259
|
+
- **`failed`** — the acceptance ran and went red, or the adapter itself failed;
|
|
260
|
+
the work went wrong.
|
|
261
|
+
|
|
262
|
+
Both are cleared by `accept`, which is a human registration, not a fresh verdict:
|
|
263
|
+
|
|
264
|
+
```bash
|
|
265
|
+
taskproof accept <id> # blocked: a note is optional
|
|
266
|
+
taskproof accept <id> --note "why" # failed: a note is required
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
`accept` **never re-runs acceptance and never rewrites the recorded verdict** —
|
|
270
|
+
the run's own facts stay authoritative. Closing a `failed` card requires a note,
|
|
271
|
+
because that is a human sign-off and the reason has to survive in the ledger.
|
|
272
|
+
`taskproof rerun <id>` starts a fresh card from a terminal one and links the two
|
|
273
|
+
both ways (`rerun_of` / `rerun_as`).
|
|
274
|
+
|
|
275
|
+
On the board, `blocked` gets its own **Needs review** column, kept out of the
|
|
276
|
+
failure column.
|
|
277
|
+
|
|
278
|
+
## The desktop console
|
|
279
|
+
|
|
280
|
+
`desktop/` is the stage-2 console: an **Electron + Vue 3** app (Element Plus,
|
|
281
|
+
UnoCSS, Pinia, vue-i18n). It is the same renderer `taskproof board` serves in a
|
|
282
|
+
browser — one rendering layer with two hosts. It is bilingual — zh-CN and en, following the system locale with an
|
|
283
|
+
English fallback.
|
|
284
|
+
|
|
285
|
+
<p align="center"><img src="docs/assets/board.png" width="900" alt="The board: a not-passing column next to a done column."></p>
|
|
286
|
+
|
|
287
|
+
*The board — the run the agent called done sits under **not passing**; the run that really changed the file sits under **done**.*
|
|
288
|
+
|
|
289
|
+
The process model is the interesting part. The app spawns the local service
|
|
290
|
+
itself — `taskproof api --port 0` — reads the bound port from the child's stdout,
|
|
291
|
+
and terminates the child on exit. Data comes from that loopback, **read-only**
|
|
292
|
+
REST API; nothing leaves `127.0.0.1`.
|
|
293
|
+
|
|
294
|
+
The REST surface is **read-only**. Every mutation lives in the CLI — registering
|
|
295
|
+
a project, editing its registry entry, dispatching, cancelling, accepting and
|
|
296
|
+
removing. The API itself only serves reads: it mints no session token and exposes
|
|
297
|
+
no write endpoint, so a write-shaped request to an old path is a plain **404**.
|
|
298
|
+
|
|
299
|
+
What the console does today:
|
|
300
|
+
|
|
301
|
+
- **Columns** — running / verifying / done / cancelled / needs review / not
|
|
302
|
+
passing. A column header can be hidden with the `?hide=` query parameter.
|
|
303
|
+
- **Every column's display cap is yours to set**, in the column's own header
|
|
304
|
+
(`- 10 +`, five choices: 5 / 10 / 20 / 50 / All). The defaults are the board
|
|
305
|
+
you already know -- done and cancelled fold to the ten most recent, the live
|
|
306
|
+
columns stay unfolded. To show a whole column, choose **All**; there is no
|
|
307
|
+
separate expand switch.
|
|
308
|
+
- A **"acceptance passed"** badge on a blocked card whose acceptance went green.
|
|
309
|
+
- **Writes are CLI-only.** The console is a viewer over the read-only API:
|
|
310
|
+
dispatch, accept and registry edits all go through `taskproof`, never the UI.
|
|
311
|
+
- A settings page that shows the **effective cap and where it came from**, plus
|
|
312
|
+
the resolved launcher (bundled runtime / `taskproof` on PATH / a custom
|
|
313
|
+
command).
|
|
314
|
+
- A **tray icon**, a **Dock badge** (the not-passing count) and a
|
|
315
|
+
**launch-at-login** switch.
|
|
316
|
+
|
|
317
|
+
## Registry
|
|
318
|
+
|
|
319
|
+
Everything taskproof may dispatch is declared in one TOML file in the workspace
|
|
320
|
+
(`~/.taskproof/projects.toml`) in two layers: a **project** (the repository and
|
|
321
|
+
its default path) and one or more **taskgroups** (the lanes it dispatches onto,
|
|
322
|
+
each with its own acceptance command and lock).
|
|
323
|
+
|
|
324
|
+
A lane may also declare a **workspace of its own** (`workspace = "worktree"`):
|
|
325
|
+
one git worktree beside the repository, created the first time a card actually
|
|
326
|
+
fires into that lane and reused from then on, with dependency directories
|
|
327
|
+
symlinked in from the main checkout (`link = [...]`) so nothing is reinstalled.
|
|
328
|
+
`taskproof workspaces` lists them; `taskproof workspace-rm <lane>` prints the
|
|
329
|
+
evidence and deletes one. `--worktree` remains the one-off. The fields are in
|
|
330
|
+
`docs/REGISTRY.md`.
|
|
331
|
+
|
|
332
|
+
```toml
|
|
333
|
+
[[project]]
|
|
334
|
+
id = "my-app"
|
|
335
|
+
path = "/absolute/path/to/my-app"
|
|
336
|
+
|
|
337
|
+
[[taskgroup]]
|
|
338
|
+
id = "my-app"
|
|
339
|
+
project = "my-app"
|
|
340
|
+
verify = "npm run build" # run by taskproof, after the agent exits
|
|
341
|
+
verify_kind = "build" # check | build | none
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
A flat, older `[[project]]` block that carries the acceptance command still
|
|
345
|
+
works unchanged: it reads as a project plus a same-named lane. `taskproof
|
|
346
|
+
register <path>` appends a `[[taskgroup]]` (add `--project` to hang it off an
|
|
347
|
+
existing project). See
|
|
348
|
+
[`examples/projects.example.toml`](examples/projects.example.toml) for a
|
|
349
|
+
commented starting point, and [`docs/REGISTRY.md`](docs/REGISTRY.md) for the
|
|
350
|
+
field reference and the list of hard errors.
|
|
351
|
+
|
|
352
|
+
The board's left rail groups by **project** — one row per project,
|
|
353
|
+
with the lanes it owns shown on hover — and each task card names the lane it
|
|
354
|
+
ran on.
|
|
355
|
+
|
|
356
|
+
## Safety and hygiene
|
|
357
|
+
|
|
358
|
+
- **Protected paths are fingerprinted, not just diffed.** Forbidden paths are
|
|
359
|
+
snapshotted before and after a run, so a change inside `.git/` or an ignored
|
|
360
|
+
build/dependency directory is caught too, not only what `git status` happens to
|
|
361
|
+
report. A tree larger than 20000 entries is sampled, and the audit event records
|
|
362
|
+
`snapshot_truncated: true`.
|
|
363
|
+
- **An asset scan runs before every push** (`tools/scan_assets.py`, wired through
|
|
364
|
+
`core.hooksPath`). It ships generic **shape** rules only, so the scanner is
|
|
365
|
+
never a no-op.
|
|
366
|
+
- **The organisation-specific words live outside the repository**
|
|
367
|
+
(`~/.taskproof/asset-patterns.txt`, or `$TASKPROOF_ASSET_PATTERNS`). A scanner
|
|
368
|
+
that embedded the names it protects would leak exactly those names.
|
|
369
|
+
|
|
370
|
+
## The enum contract
|
|
371
|
+
|
|
372
|
+
Status words, `verify_kind` values and exit-code meanings are one generated
|
|
373
|
+
artefact — [`contract/enums.json`](contract/enums.json) — produced from the
|
|
374
|
+
Python constants by `tools/gen_contract.py`. The TypeScript side imports it
|
|
375
|
+
instead of re-typing it; a status that exists in Python but not in the frontend
|
|
376
|
+
is a task that silently vanishes from the board. CI runs the check, so the two
|
|
377
|
+
languages cannot drift:
|
|
378
|
+
|
|
379
|
+
```bash
|
|
380
|
+
PYTHONPATH=src python3 tools/gen_contract.py --check
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
## Development
|
|
384
|
+
|
|
385
|
+
Run the CLI from a source checkout:
|
|
386
|
+
|
|
387
|
+
```bash
|
|
388
|
+
pip install -e .
|
|
389
|
+
taskproof --version
|
|
390
|
+
```
|
|
391
|
+
|
|
392
|
+
Or, without installing:
|
|
393
|
+
|
|
394
|
+
```bash
|
|
395
|
+
PYTHONPATH=src python3 -m taskproof doctor
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
Two test suites, both green at the time of writing:
|
|
399
|
+
|
|
400
|
+
- **Python** — `PYTHONPATH=src python3 -m unittest discover -s tests` (448 tests).
|
|
401
|
+
- **Desktop** — `cd desktop && npm install && npm test` (258 tests). `npm run
|
|
402
|
+
build` runs the type-check and a production build of all three targets.
|
|
403
|
+
|
|
404
|
+
CI runs three checks: the asset scan (`tools/scan_assets.py`), the enum-contract
|
|
405
|
+
consistency check (`PYTHONPATH=src python3 tools/gen_contract.py --check`), and
|
|
406
|
+
the desktop build + tests.
|
|
407
|
+
|
|
408
|
+
The animation at the top of this page is reproducible: `tools/demo/` holds the
|
|
409
|
+
throwaway `/tmp` workspace builder and the `vhs` tape.
|
|
410
|
+
|
|
411
|
+
## Known limitations
|
|
412
|
+
|
|
413
|
+
- **Unsigned and not notarised.** macOS shows a Gatekeeper prompt on first launch
|
|
414
|
+
(right-click → Open, or clear the quarantine bit); Windows shows a SmartScreen
|
|
415
|
+
warning.
|
|
416
|
+
- **macOS is arm64 only.** There is no Intel build and no Rosetta path.
|
|
417
|
+
- **The gate needs `git`.** Without a system `git`, worktrees and the
|
|
418
|
+
protected-path gate are unavailable; the settings page says so and everything
|
|
419
|
+
else runs as usual.
|
|
420
|
+
- **The board fetches at most 2000 rows at a time.** At that ceiling it shows
|
|
421
|
+
**"fetch limit reached"** rather than implying it has everything.
|
|
422
|
+
- **Windows and Linux installers are built by CI's native runners.** A local
|
|
423
|
+
machine can only build the macOS package.
|
|
424
|
+
|
|
425
|
+
## Documentation
|
|
426
|
+
|
|
427
|
+
The docs ship in pairs, English and Simplified Chinese:
|
|
428
|
+
|
|
429
|
+
| English | 中文 |
|
|
430
|
+
|---|---|
|
|
431
|
+
| [`README.md`](README.md) | [`README.zh-CN.md`](README.zh-CN.md) |
|
|
432
|
+
| [`docs/DESIGN.md`](docs/DESIGN.md) | [`docs/DESIGN.zh-CN.md`](docs/DESIGN.zh-CN.md) |
|
|
433
|
+
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | [`docs/ARCHITECTURE.zh-CN.md`](docs/ARCHITECTURE.zh-CN.md) |
|
|
434
|
+
| [`docs/REGISTRY.md`](docs/REGISTRY.md) | [`docs/REGISTRY.zh-CN.md`](docs/REGISTRY.zh-CN.md) |
|
|
435
|
+
| [`docs/WALKTHROUGH.md`](docs/WALKTHROUGH.md) | [`docs/WALKTHROUGH.zh-CN.md`](docs/WALKTHROUGH.zh-CN.md) |
|
|
436
|
+
|
|
437
|
+
The dispatch discipline is a skill, in [`skills/taskproof-dispatch/SKILL.md`](skills/taskproof-dispatch/SKILL.md) (English) and [`skills/taskproof-dispatch/SKILL.zh-CN.md`](skills/taskproof-dispatch/SKILL.zh-CN.md) (简体中文).
|
|
438
|
+
|
|
439
|
+
## Icon
|
|
440
|
+
|
|
441
|
+
`docs/assets/icon.png` is a 256 px copy of the app icon, small enough to live in
|
|
442
|
+
the repository. The source was an AI-generated mark; the checkerboard that got
|
|
443
|
+
baked into the PNG was cut out, the artwork was laid on Apple's 824/1024 grid
|
|
444
|
+
(the mark occupies 824 of the 1024 px canvas so the rounded-corner margin is
|
|
445
|
+
correct), and `sips` produced the 256 px copy used at the top of this page.
|
|
446
|
+
|
|
447
|
+
## Non-goals
|
|
448
|
+
|
|
449
|
+
- No built-in LLM orchestration
|
|
450
|
+
- No agent-to-agent conversation layer
|
|
451
|
+
- No code generation or editing of its own
|
|
452
|
+
- No automated `git` write operations
|
|
453
|
+
|
|
454
|
+
## Exit codes
|
|
455
|
+
|
|
456
|
+
Exit codes are part of the contract for callers (scripts, agents, CI): they tell
|
|
457
|
+
you *why* a run ended without parsing stdout.
|
|
458
|
+
|
|
459
|
+
| Code | Meaning |
|
|
460
|
+
|---|---|
|
|
461
|
+
| 0 | success |
|
|
462
|
+
| 2 | registry problem (unknown project, missing/malformed registry, duplicate id) |
|
|
463
|
+
| 64 | usage error (bad flags, missing path, unknown task or adapter) |
|
|
464
|
+
| 70 | adapter (agent) failure — the CLI failed to run, or its result could not be parsed |
|
|
465
|
+
| 71 | verification or artifact self-check failure (acceptance command failed) |
|
|
466
|
+
| 75 | concurrency limit reached (same-group busy, or the global cap is full) |
|
|
467
|
+
|
|
468
|
+
## License
|
|
469
|
+
|
|
470
|
+
Apache-2.0. See [`LICENSE`](LICENSE).
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
taskproof/__init__.py,sha256=XwGFMDytboQpL3R3I46bkzu5SpRnNvY3KiFK52257U4,1051
|
|
2
|
+
taskproof/__main__.py,sha256=qqg34E6VF9b-KnFcZJJZ4OLHvyDWL00QDgDDmusq2d0,160
|
|
3
|
+
taskproof/cli.py,sha256=kN3vTHkMkvQuG1KuztwQz5o5CC2OF8SZcDYzosOjeXw,50572
|
|
4
|
+
taskproof/concurrency.py,sha256=-c3IvXTgZ7sJ4QFukJx2FakWy0Ju1OfSb2BvQ4AWLFg,12506
|
|
5
|
+
taskproof/dispatch.py,sha256=LUu_LIhyRvCMhNDLO_FR87fd06avtQ6vyek6wqZTF1o,88834
|
|
6
|
+
taskproof/errors.py,sha256=NTxb2sNFWP77SQklpAwGQtOffU8lu5RH0D0fAeR0wQE,1353
|
|
7
|
+
taskproof/ledger.py,sha256=Ou-BW5lVgxc2RIT2lBTNpSvBDJ-4_9_EUb74Ydd-Tk0,6477
|
|
8
|
+
taskproof/models.py,sha256=UGEo9RGenA0X98qS6mbOcbJb_M0cKZGxpx7fOYLgXBg,5352
|
|
9
|
+
taskproof/registry.py,sha256=Vjk1H4v55p34xzTsDpzbJ_g3Wf_WE7XKMZJ_sfAlaoM,60054
|
|
10
|
+
taskproof/storage.py,sha256=qMy_KroigNz_wLM5NN-13Wx9kkBodhHcER02G4viov8,14121
|
|
11
|
+
taskproof/verify.py,sha256=2cZ-P-J2z2XTZ3_Vj8Y-8cBxGlqZ1h4psM_sVOEJBKM,23060
|
|
12
|
+
taskproof/adapters/__init__.py,sha256=W0TNkDwpGF7Z7fSp7Qrl6DfeFArhEULWu978UySVxGk,3317
|
|
13
|
+
taskproof/adapters/base.py,sha256=M5zF4djyV8cw3A8zTcFPoMfYPOeH70-qBmHwJ4961xg,8031
|
|
14
|
+
taskproof/adapters/claude.py,sha256=oNSntmuo8QT_Mf_NjX0oSVc0Tbpobxt8CYhiXkdv8II,1617
|
|
15
|
+
taskproof/adapters/codex.py,sha256=lIRKjKlrXpLNZr30YpHNCC-dI3nLSfJUj-Duv9nI4xY,5294
|
|
16
|
+
taskproof/adapters/custom.py,sha256=9floY6Rvtjf-Q4xkxqOJquxZBm9M6c7lo19E7hyZmPg,2417
|
|
17
|
+
taskproof/adapters/gemini.py,sha256=RrmDaKa1xXByIkleHqWRYx8gi9IxeWohMH30-VtJ6Aw,1547
|
|
18
|
+
taskproof/adapters/opencode.py,sha256=wPFPmO-C19JoZZ1SABpgBt6BM49N04Xyr6aRTiPyGds,1494
|
|
19
|
+
taskproof/api/__init__.py,sha256=NE-f9BM82d3TNZEbi4M4ukXtBWEHqUj02U6lVk3tqoc,42
|
|
20
|
+
taskproof/api/server.py,sha256=qdOOAXEyU0GbQ3f2nWsumYCu71BG8ze_SzBZeWcrG5M,31655
|
|
21
|
+
taskproof/schemas/result.json,sha256=XgtR9mN1yMLuUQwR3erVnrtLt2WE1jXG-XZiex5qZSU,3421
|
|
22
|
+
taskproof/sql/schema.sql,sha256=RXePvz62JHRhQ-j6FdY8K9eEyG0hTiBWpiPJG60HhAI,2079
|
|
23
|
+
taskproof/web/index.html,sha256=J5GXE38nRKwUrUxZVVmvUWfiRGJ4BJz1ZxY_WnujS2E,891
|
|
24
|
+
taskproof/web/assets/MatrixView-BM8nu9s2.css,sha256=N4fc1vUmZ9WymYjdxYC_KKHOBHxYvqhj6i8ORqRKC9Y,12249
|
|
25
|
+
taskproof/web/assets/MatrixView-BM8nu9s2.css.gz,sha256=V4km9yoAbxRComZfCSvxXkrzxbthCGYebALtPHSPe04,3726
|
|
26
|
+
taskproof/web/assets/MatrixView-BMsawnxh.js,sha256=DUQcbitREyAIdxKm1uPO1K25KYOU8afFWXlfgy2HRLU,22316
|
|
27
|
+
taskproof/web/assets/MatrixView-BMsawnxh.js.gz,sha256=dYI7jRT-nzxwFm7u7D1sveTlNvhRuFCS1vnxc0dVxwk,4969
|
|
28
|
+
taskproof/web/assets/ProjectsView-BcXcx5Gw.js,sha256=dU3geqTdGzcdwrP9FcPQM1Pij4bnrrd74fKfMaefgA8,13245
|
|
29
|
+
taskproof/web/assets/ProjectsView-BcXcx5Gw.js.gz,sha256=E3cfRzUfby-2PlEDFx1RJoUB8E8K1OrBCSRo7lZlwEc,2249
|
|
30
|
+
taskproof/web/assets/ProjectsView-CqNFL-fi.css,sha256=SXGw9hBH-y9w53kvcTOuF8lfPG3M_ajZ4VqsyArJulE,658
|
|
31
|
+
taskproof/web/assets/SettingsView-D_-waf0s.js,sha256=lhpmAyuDNzcxdeG85DgZ-pKui3rQheW_GTYTKqz2DUM,27536
|
|
32
|
+
taskproof/web/assets/SettingsView-D_-waf0s.js.gz,sha256=KcmtpALKrT7AKqzL7KoQG5TdtRxMMTVY9-019WJf9lA,4249
|
|
33
|
+
taskproof/web/assets/SettingsView-aqTS3ubB.css,sha256=A71fy2QB6xvVr_meK7P4_hzCgCe486MGM4-hg9GH6u8,525
|
|
34
|
+
taskproof/web/assets/TaskDrawer-6JoGTH0s.js,sha256=-7qT47f2RexLCidRtPBGda1u4MjuFstOPn_sur6HA5o,26548
|
|
35
|
+
taskproof/web/assets/TaskDrawer-6JoGTH0s.js.gz,sha256=Lo0Vhe5wZR80JWHfW1f7nHeHPp_8PYuhEH42_gWJfg8,6287
|
|
36
|
+
taskproof/web/assets/TaskDrawer-N299VKzd.css,sha256=8hysYZhwea6U1964gKtVOxGKNfdB1NstGmJIUPNvW-s,10202
|
|
37
|
+
taskproof/web/assets/TaskDrawer-N299VKzd.css.gz,sha256=xio65R4wpgpznIddEqU9DYcISY7MMLT3D4WhnIqxf14,2274
|
|
38
|
+
taskproof/web/assets/TasksView-BWhSHCHi.js,sha256=0bli3djgL8uUdDitP1SKotWw9_oBtBrm4aEsqOQCjcY,5136
|
|
39
|
+
taskproof/web/assets/TasksView-BWhSHCHi.js.gz,sha256=PpiUkuEzFcGo7FC357gNB-IXnE9Npkn1hxfRryTwh0g,1334
|
|
40
|
+
taskproof/web/assets/TasksView-Bn08731V.css,sha256=v96ltPA4k-tUUehC-YkQaWKDOGXRJSl3ItJ26kKEels,616
|
|
41
|
+
taskproof/web/assets/icon-Dw-ohsdc.png,sha256=kfx6d1-7ySu4D6GwwYgTAqfl15Tv-ekS029Ed6e5X60,83263
|
|
42
|
+
taskproof/web/assets/index-B-PLdDbR.js,sha256=qMWx8mu7CPQf6zE4ffNEM796ATM7dI9d_o_w8B9-OvU,2628655
|
|
43
|
+
taskproof/web/assets/index-B-PLdDbR.js.gz,sha256=eRvQVO0eVsvaDdP9yc8UUVE4DHx94S8fKmSBOAoDkWk,567164
|
|
44
|
+
taskproof/web/assets/index-NKj7kbYl.css,sha256=nm-vgjTwhSUIlM6SgCUi7GOa9nEwmLNeT6wl2kbqiZM,396782
|
|
45
|
+
taskproof/web/assets/index-NKj7kbYl.css.gz,sha256=Ob75KcC85vU54FVb5bc4tfKtsQtKNkIiLmJjG8IXABQ,58788
|
|
46
|
+
taskproof-0.3.0.dist-info/licenses/LICENSE,sha256=KD6mzCmXoacNoASeCa35MXu2DKG1Enm2UZa4OmnhmWs,11323
|
|
47
|
+
taskproof-0.3.0.dist-info/METADATA,sha256=RVoB7XobiM7T78cb2T49fg4saaS5QZVAKM3hYhyGgpU,20001
|
|
48
|
+
taskproof-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
|
|
49
|
+
taskproof-0.3.0.dist-info/entry_points.txt,sha256=QLSQL0d2OBNbhu-n0d64TAvaL5Dij3v0YAAGKBcizbQ,49
|
|
50
|
+
taskproof-0.3.0.dist-info/top_level.txt,sha256=8RdIE9IU4e0-FpZTIc7xNfn1q-kTeSjoxy89cloz6NI,10
|
|
51
|
+
taskproof-0.3.0.dist-info/RECORD,,
|