workorder 0.5.0__tar.gz
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.
- workorder-0.5.0/LICENSE +21 -0
- workorder-0.5.0/PKG-INFO +397 -0
- workorder-0.5.0/README.md +375 -0
- workorder-0.5.0/pyproject.toml +39 -0
- workorder-0.5.0/setup.cfg +4 -0
- workorder-0.5.0/tests/test_review_b.py +348 -0
- workorder-0.5.0/tests/test_v04.py +530 -0
- workorder-0.5.0/tests/test_v05.py +396 -0
- workorder-0.5.0/tests/test_workorder.py +2007 -0
- workorder-0.5.0/workorder/__init__.py +3 -0
- workorder-0.5.0/workorder/__main__.py +3 -0
- workorder-0.5.0/workorder/cli.py +198 -0
- workorder-0.5.0/workorder/gate.py +1292 -0
- workorder-0.5.0/workorder/store.py +1164 -0
- workorder-0.5.0/workorder.egg-info/PKG-INFO +397 -0
- workorder-0.5.0/workorder.egg-info/SOURCES.txt +18 -0
- workorder-0.5.0/workorder.egg-info/dependency_links.txt +1 -0
- workorder-0.5.0/workorder.egg-info/entry_points.txt +2 -0
- workorder-0.5.0/workorder.egg-info/requires.txt +3 -0
- workorder-0.5.0/workorder.egg-info/top_level.txt +1 -0
workorder-0.5.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Tom Bar-Haim
|
|
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.
|
workorder-0.5.0/PKG-INFO
ADDED
|
@@ -0,0 +1,397 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: workorder
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: The task record for coding agents: every task recorded, a clear history, agents always go back to it.
|
|
5
|
+
Author: Tom Bar-Haim
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/Argento17/workorder
|
|
8
|
+
Project-URL: Issues, https://github.com/Argento17/workorder/issues
|
|
9
|
+
Keywords: tasks,task-format,coding-agents,git,verification
|
|
10
|
+
Classifier: Development Status :: 3 - Alpha
|
|
11
|
+
Classifier: Environment :: Console
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Topic :: Software Development :: Quality Assurance
|
|
15
|
+
Classifier: Topic :: Software Development :: Version Control :: Git
|
|
16
|
+
Requires-Python: >=3.10
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
License-File: LICENSE
|
|
19
|
+
Provides-Extra: test
|
|
20
|
+
Requires-Dist: pytest>=7; extra == "test"
|
|
21
|
+
Dynamic: license-file
|
|
22
|
+
|
|
23
|
+
# Workorder: the task record for coding agents
|
|
24
|
+
|
|
25
|
+
**Every task recorded. A clear history. Agents always go back to it.**
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
pipx install workorder
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
No pipx? On Ubuntu or Debian: `sudo apt install pipx && pipx ensurepath`. Other systems: see the [pipx install guide](https://pipx.pypa.io/stable/how-to/install-pipx.html). Plain `pip install` outside a virtual environment is blocked on recent Ubuntu; the [quick start](#quick-start) uses one.
|
|
32
|
+
|
|
33
|
+
Workorder keeps each task as a record in your repository. A coding agent starts every session from the task, works within it, and leaves it up to date. The next session, or the next agent, picks up where the last one stopped.
|
|
34
|
+
|
|
35
|
+
- **Recorded:** each task is a Markdown file in `tasks/`. It holds the mission, scope, acceptance criteria, dependencies, the test that proves it, and progress notes, in a format people and agents both read and write.
|
|
36
|
+
- **A clear history:** receipts record what was implemented and tested, on which commit, with which command, by whom. Each receipt is a separate file, linked to the receipts it follows. Committed receipts stay unchanged. `workorder show` prints the task with that history as a timeline.
|
|
37
|
+
- **Agents go back to it:** a short block in `CLAUDE.md` / `AGENTS.md` makes the agent start each session with `workorder show` and end it with `workorder note` ([see below](#working-with-coding-agents)).
|
|
38
|
+
- **DONE is checked:** `status: DONE` is a claim. `workorder check` compares it with the history and says what is missing.
|
|
39
|
+
|
|
40
|
+
Workorder was called NotQuite up to version 0.2.0.
|
|
41
|
+
|
|
42
|
+
## Why
|
|
43
|
+
|
|
44
|
+
Coding agents get their work from chat. The goal, the scope and what "done" means live in a conversation that ends, and the next session or the next agent starts from a summary. And DONE is whatever the agent says it is.
|
|
45
|
+
|
|
46
|
+
Workorder moves the task into the repository, next to the code, and keeps its history there. The task file says what to build, how it will be accepted and which test proves it. The agent comes back to it at the start of every session, notes progress in it, and records evidence as it goes. When the task is marked DONE, Workorder checks that a passing run of the task's test was recorded on the code that was implemented, and says what is missing if not.
|
|
47
|
+
|
|
48
|
+
It runs on Git and Python's standard library. No server or database. Tested in CI on Linux and Windows (Python 3.10, 3.12, 3.13).
|
|
49
|
+
|
|
50
|
+
## A task
|
|
51
|
+
|
|
52
|
+
`workorder new --title "Sort items by due date" --owner alex --test "python -m pytest tests/test_list.py"` writes `tasks/TASK-<n>.md` with these fields and sections for you or the agent to fill in. A filled-in task:
|
|
53
|
+
|
|
54
|
+
```markdown
|
|
55
|
+
---
|
|
56
|
+
id: "TASK-4"
|
|
57
|
+
title: "Sort items by due date"
|
|
58
|
+
owner: "alex"
|
|
59
|
+
business_owner: "sam"
|
|
60
|
+
priority: "P2"
|
|
61
|
+
created_at: "2026-11-14"
|
|
62
|
+
mission: "Show what is due first"
|
|
63
|
+
depends_on: ["TASK-1"]
|
|
64
|
+
blocks: []
|
|
65
|
+
next: "Agree the order for items without a date"
|
|
66
|
+
summary: "A sort option on the list view"
|
|
67
|
+
status: "IN_PROGRESS"
|
|
68
|
+
ships: "repo"
|
|
69
|
+
waits_on: []
|
|
70
|
+
test: "python -m pytest tests/test_list.py"
|
|
71
|
+
contract: "none"
|
|
72
|
+
---
|
|
73
|
+
|
|
74
|
+
# TASK-4
|
|
75
|
+
|
|
76
|
+
## Context
|
|
77
|
+
|
|
78
|
+
Users scroll past finished items to find what is due. The list view is in app/list.py.
|
|
79
|
+
|
|
80
|
+
## Scope
|
|
81
|
+
|
|
82
|
+
In: a "due date" sort option on the list view.
|
|
83
|
+
Out: changing how dates are entered.
|
|
84
|
+
|
|
85
|
+
## Lanes
|
|
86
|
+
|
|
87
|
+
- Sorting logic and tests: the agent
|
|
88
|
+
- Wording of the sort option: sam
|
|
89
|
+
|
|
90
|
+
## Acceptance
|
|
91
|
+
|
|
92
|
+
- Items with a due date come first, earliest first.
|
|
93
|
+
- Items without a date keep their order, at the end.
|
|
94
|
+
|
|
95
|
+
## Progress
|
|
96
|
+
|
|
97
|
+
- 2026-11-14: sort implemented; undated items still to place.
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
- **For people and agents:** `mission`, `summary`, `next`, the owners, `priority` and the five sections say what the work is, what is in and out, who does what, and how it will be accepted. Workorder keeps them in the file and never treats them as evidence.
|
|
101
|
+
- **`status`** is the claim: `IN_PROGRESS`, `BLOCKED`, `DONE`, `CLOSED`, or `CANCELLED` for work that will not be done (it needs no evidence and leaves `ready`). You or the agent edit it. Workorder never edits it and never trusts it.
|
|
102
|
+
- **`test`** is the command that proves the task. A task needs one to be DONE: only a run of exactly that command counts, and `workorder receipt test --task <id>` runs it. For work no single command proves, `test: "any"` says so explicitly and accepts any recorded command. No shell runs it: words split on spaces, quotes group words, backslashes stay as written, and `&&` or pipes are refused (use a script).
|
|
103
|
+
- **`depends_on`** lists tasks this one needs. `waits_on` takes `task:TASK-2` or `person:alex` items (remove a person wait when it is answered). Both form one dependency list, and a task cannot be DONE while one is open. A dependency is finished when it says DONE or CLOSED, its evidence supports that, and its own dependencies are finished. `blocks` is informational: it is checked against the other tasks but never enforced.
|
|
104
|
+
- **`ships`** sets what CLOSED needs beyond DONE: `none` (the default), `repo` (the tested change on the target branch) or `live` (also deployment read-backs).
|
|
105
|
+
- **`contract`** is `none` or a path to a contract that maps each acceptance criterion to evidence Workorder can check ([see below](#contracts-and-evidence)). Without one, the Acceptance list is for the agent and the reviewer; Workorder does not read it.
|
|
106
|
+
- **Your own fields** start with `x-`, such as `x-issue: "#42"`. They are kept and never checked.
|
|
107
|
+
|
|
108
|
+
Front matter is a small, documented subset: single-line text (plain, quoted or JSON), lists, `>` and `|` blocks for `mission`, `next` and `summary`, `- TASK-1` lists and `#` comment lines. Other YAML, and unknown fields, are reported for that task, so a typo cannot quietly drop a dependency. The [reference](https://github.com/Argento17/workorder/blob/main/docs/reference.md#what-yaml-is-read) lists exactly what is read.
|
|
109
|
+
|
|
110
|
+
Markdown files in `tasks/` whose names are not task ids, such as a README or notes, are ignored. Any other file there (code, for example) is reported, because `tasks/` is outside the code fingerprint and changes to it would never be checked.
|
|
111
|
+
|
|
112
|
+
For small work, `workorder new --template simple` writes the seven required fields only (`id`, `title`, `owner`, `status`, `ships`, `waits_on`, `contract`), the format of version 0.1.0; add `test:` before claiming DONE. Both formats can sit in the same repository. Version 0.1.0 refuses task files that use the other fields, so upgrade every clone and CI pin before using them.
|
|
113
|
+
|
|
114
|
+
## Working with coding agents
|
|
115
|
+
|
|
116
|
+
Workorder reads task files and recorded evidence. It does not watch conversations, so a claim made only in chat is not caught. Tell the agent how to work with tasks. Add this to `CLAUDE.md` (Claude Code) or `AGENTS.md` (Codex):
|
|
117
|
+
|
|
118
|
+
```markdown
|
|
119
|
+
## Tasks
|
|
120
|
+
- Start every session with `workorder show --task <id>` and work from what it prints: the mission and Scope say what to do and what not to; the Acceptance list says how the work will be accepted; `test` is the command that proves it; the history and progress say where the last session stopped.
|
|
121
|
+
- Before starting, run `workorder claim --task <id>` (needs an origin remote you can push to). Run `workorder release --task <id>` when you stop working on it, finished or not.
|
|
122
|
+
- After committing code, run `workorder receipt implemented --task <id>`, then `workorder receipt test --task <id>` (it runs the task's `test`).
|
|
123
|
+
- Set status DONE only when every Acceptance item is met, then run `workorder check <id>`. If it reports NOT QUITE, set the status back and report its Missing lines instead of saying the task is done.
|
|
124
|
+
- Before you stop, record where you are with `workorder note --task <id> "<what was done; what is next>"`, keep `next` current, then commit tasks/ and .workorder/ with your work and push.
|
|
125
|
+
- If the task's `ships` is `repo` or `live`: after the change is merged, run `workorder check <id>` on main. It computes the merge from Git history. No merge receipt or extra commit is needed. If the merged change differs, run `workorder renew --task <id>` on main and test it again.
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
## Quick start
|
|
129
|
+
|
|
130
|
+
Requires Git and Python 3.10 or newer. This uses a throwaway folder and needs no remote. On Windows, run the commands in Git Bash and activate with `. .venv/Scripts/activate`.
|
|
131
|
+
|
|
132
|
+
```sh
|
|
133
|
+
python3 -m venv .venv && . .venv/bin/activate
|
|
134
|
+
python -m pip install workorder
|
|
135
|
+
|
|
136
|
+
mkdir demo && cd demo
|
|
137
|
+
git init -q -b main
|
|
138
|
+
git config user.name "Your Name"
|
|
139
|
+
git config user.email you@example.com
|
|
140
|
+
|
|
141
|
+
printf 'def add(a, b):\n return a + b\n' > calc.py
|
|
142
|
+
printf 'from calc import add\n\nassert add(2, 2) == 4\n' > test_calc.py
|
|
143
|
+
printf '__pycache__/\n' > .gitignore
|
|
144
|
+
git add . && git commit -qm "Add calc"
|
|
145
|
+
|
|
146
|
+
workorder new --title "Add calc" --owner you --test "python test_calc.py"
|
|
147
|
+
workorder receipt implemented --task TASK-1
|
|
148
|
+
workorder receipt test --task TASK-1
|
|
149
|
+
workorder note --task TASK-1 "add() works; next: subtraction"
|
|
150
|
+
workorder show --task TASK-1
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
`workorder show` prints the task as a record: its state (`recorded IN_PROGRESS; computed CLOSED`, because the evidence already supports it and this task ships nothing), what it still owes, its test, a timeline of the implementation and the passing test, and the progress note. The `status` line in `tasks/TASK-1.md` is the claim, and Workorder never edits it; setting `status: CLOSED` would now pass `workorder check`.
|
|
154
|
+
|
|
155
|
+
To see it refuse, change `calc.py`, commit, run `workorder receipt implemented --task TASK-1`, set `status: DONE` in `tasks/TASK-1.md`, and run `workorder check TASK-1`.
|
|
156
|
+
|
|
157
|
+
Run `workorder` at the root of your repository. Commit `tasks/` and `.workorder/` along with your code. Locally, `workorder check` reads the working tree (`--staged`: what is about to be committed); in CI it reads what was committed.
|
|
158
|
+
|
|
159
|
+
## When DONE is not done
|
|
160
|
+
|
|
161
|
+
A test passed on one commit. Then the code changed, and the task was marked DONE without testing again:
|
|
162
|
+
|
|
163
|
+
```text
|
|
164
|
+
$ workorder check TASK-1
|
|
165
|
+
NOT QUITE TASK-1
|
|
166
|
+
|
|
167
|
+
Claimed: DONE
|
|
168
|
+
Computed: IN_PROGRESS
|
|
169
|
+
Commit: 75e3c96
|
|
170
|
+
Test: no passing test for this commit; the last test ran on cc96932
|
|
171
|
+
Missing: a passing test on 75e3c96
|
|
172
|
+
Next: workorder receipt test --task TASK-1 -- python test_calc.py
|
|
173
|
+
|
|
174
|
+
Result: NOT DONE. The status says DONE; the evidence above does not support it.
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
The exit code is 1, so an agent, a hook or a script sees the refusal. Running the task's test through Workorder records what actually happened. In this case the change broke it:
|
|
178
|
+
|
|
179
|
+
```text
|
|
180
|
+
$ workorder receipt test --task TASK-1
|
|
181
|
+
Traceback (most recent call last):
|
|
182
|
+
...
|
|
183
|
+
AssertionError
|
|
184
|
+
TASK-1 test 75e3c96 exit 1 - recorded
|
|
185
|
+
command: python test_calc.py
|
|
186
|
+
TASK-1 still owes: a passing test on 75e3c96
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
## The record
|
|
190
|
+
|
|
191
|
+
- **`workorder show --task TASK-1`** prints the task as a record: recorded and computed status, what is still owed, title, mission, `next` and `test`, every section of the task (Context, Scope, Lanes, Acceptance), a dated timeline of every receipt (implemented, each test run with its command and result, merges and read-backs, and who recorded them), the Progress notes, and the next step.
|
|
192
|
+
- **`workorder note --task TASK-1 "..."`** adds a dated line at the end of the task's Progress section. It is the one change Workorder makes to a task file after `new`; every other byte is left alone.
|
|
193
|
+
- **Ids.** `workorder new` writes `tasks/TASK-<n>.md`. With an `origin` remote, it first reserves the id there, so two clones cannot take the same id. Without one, or with `--local`, it numbers tasks from the task files and says so; those ids are not coordinated with anyone else.
|
|
194
|
+
- **Claims.** `workorder claim --task TASK-1` pushes a tag to `origin`. If another clone already holds the task, Git rejects the push and the claim fails. It also fetches origin's main branch (master when main is absent) and refuses a task already DONE, CLOSED or CANCELLED there, even after its holder released it; pull to update your task files. `workorder claims` lists holders.
|
|
195
|
+
- **Ready.** `workorder ready` lists open tasks as free, held, blocked (with what they wait for) or waiting for delivery. It fetches upstream task status too: an outdated local task says `finished on origin/main; pull to update`. It still lists local tasks when `origin` cannot be reached, with the existing note and without remote claims or status, and shows a task file that cannot be read as such.
|
|
196
|
+
|
|
197
|
+
`workorder release` works in the clone that made the claim. That clone keeps a random token in its `.git` folder, and the claim tag stores only the token's SHA-256 hash. Release adds another tag, so the history stays on `origin`. If that clone or worktree is gone, `workorder release --task TASK-1 --force` releases the claim from anywhere and records that it was forced.
|
|
198
|
+
|
|
199
|
+
Ids, claims and releases live under `refs/tags/workorder/`. Hosting sites list them with your other tags, and `git fetch --tags` downloads them. The token is a courtesy between clones, not access control. Anyone with push access can push a release tag, force-push or delete tags. If that matters, protect `workorder/*` tags in your repository settings.
|
|
200
|
+
|
|
201
|
+
Claims always need `origin`. Without a remote there are no claims at all: Workorder refuses `claim` rather than keep a local claim that nobody else could see. If `origin` is configured but unreachable, `claim` refuses rather than guess, and `new` asks for `--local`.
|
|
202
|
+
|
|
203
|
+
## What counts as DONE
|
|
204
|
+
|
|
205
|
+
1. A declared `test` (or the explicit `test: "any"`).
|
|
206
|
+
2. `workorder receipt implemented` on a clean, committed tree. Uncommitted or untracked code is refused, so build output belongs in `.gitignore`.
|
|
207
|
+
3. The latest run of the task's test on that same code exited 0, and the tree and HEAD were unchanged when it finished. A later failure revokes DONE until a later run passes; once committed, every run stays in the receipts.
|
|
208
|
+
4. Every critical contract criterion met, if there is a contract.
|
|
209
|
+
5. Nothing left in `waits_on` or `depends_on`, and no `person:` wait.
|
|
210
|
+
|
|
211
|
+
"Code" is every tracked file outside `tasks/`, `.workorder/` and `.notquite/`, so committing the task file and receipts does not change it: a later run on the same code still counts, pass or fail. A test recorded before the latest implementation, on different code, or while files or HEAD changed does not count. A receipt that is recorded but cannot count, such as a test on code that changed since `receipt implemented`, says why and exits 1. `workorder check <id>` shows the command behind the deciding run.
|
|
212
|
+
|
|
213
|
+
A DONE is about the last recorded implementation:
|
|
214
|
+
|
|
215
|
+
- A DONE or CLOSED must be claimed on the implemented code. `workorder check` refuses a claim made, in the working tree or in a commit, on code that differs from the implementation it relies on, or over uncommitted code changes; the pre-commit hook and `workorder check --base` in CI apply the same rule.
|
|
216
|
+
- `workorder check <id>` adds a note when the code has changed since the implementation.
|
|
217
|
+
- Code that lands after a task is DONE does not reopen it.
|
|
218
|
+
|
|
219
|
+
## What counts as CLOSED
|
|
220
|
+
|
|
221
|
+
DONE, plus what the task ships:
|
|
222
|
+
|
|
223
|
+
| `ships` | Also needs |
|
|
224
|
+
|---|---|
|
|
225
|
+
| `none` | nothing |
|
|
226
|
+
| `repo` | the tested change is on the target branch, or a qualifying `merged` receipt |
|
|
227
|
+
| `live` | the merge, then `receipt deployed --target <name> -- <command>`, then a later `receipt live --target <name> -- <command>` |
|
|
228
|
+
|
|
229
|
+
Workorder chooses `merge_ref` when set, otherwise `origin/main`, `origin/master`, local `main`, then local `master`, in that order. It ignores `origin/HEAD`. A commit only on your local `main` does not count as merged when `origin/main` exists until it is pushed. Set `merge_ref: refs/heads/release` in the task to choose another target. Checks use local refs and do not fetch. Checks on feature branches and detached checkouts use that same target.
|
|
230
|
+
|
|
231
|
+
A recorded `merged` receipt still counts when its commit contains the implemented commit or holds exactly its code. A merge receipt that counted stays counted. Deployment read-backs can also name a commit containing the computed squash or rebase merge.
|
|
232
|
+
|
|
233
|
+
A deployment or live read-back counts when its command exits 0 and its output contains the expected full commit ID. Workorder reads back; it does not deploy. A passing read-back shows that the command returned that commit ID, nothing more. `receipt merged` reads from `origin` and needs a remote. Computed merges do not need one.
|
|
234
|
+
|
|
235
|
+
## Squash merges and rebases
|
|
236
|
+
|
|
237
|
+
Workorder computes the merge without writing a receipt. It checks whether the
|
|
238
|
+
target contains the implemented commit, holds the same code, has the same code
|
|
239
|
+
patch after a squash, or has a patch equivalent to every code commit after a
|
|
240
|
+
rebase. Changes to task files and receipts do not count as code patches.
|
|
241
|
+
`show` and `check` name the matching commit and how it matched, from any
|
|
242
|
+
checkout. A feature branch is never used as its own merge target.
|
|
243
|
+
|
|
244
|
+
A DONE or CLOSED claimed on a commit after the matched landing must preserve
|
|
245
|
+
the content of every code path changed by the implementation at that landing.
|
|
246
|
+
Reverting or overwriting those files before claiming completion is refused;
|
|
247
|
+
run `workorder renew --task TASK-1` on the claimed code. This applies to
|
|
248
|
+
ancestry, same-code, squash and rebase matches. Unrelated paths may change.
|
|
249
|
+
A transition from DONE to CLOSED is a new claim and is checked again.
|
|
250
|
+
A valid claim already made at or before the landing stays valid when later
|
|
251
|
+
commits change those files: later work does not reopen a finished task.
|
|
252
|
+
|
|
253
|
+
Rebasing a finished branch over unrelated changes keeps its DONE claim when
|
|
254
|
+
the claim and implementation have the same code patch relative to their own
|
|
255
|
+
merge bases with the target. Merging main into the branch also keeps the claim.
|
|
256
|
+
If a matching squash is on local main but not origin/main, the next step says
|
|
257
|
+
to push main.
|
|
258
|
+
|
|
259
|
+
A squash onto a main that changed other files can count. If main changed the
|
|
260
|
+
same lines and the resulting patch differs, it does not count. Run
|
|
261
|
+
`workorder renew --task TASK-1` on main to record and test the merged code,
|
|
262
|
+
or record `workorder receipt merged` when its commit carries the tested code.
|
|
263
|
+
|
|
264
|
+
Patch comparisons need the original commits in the clone. When they are gone,
|
|
265
|
+
the same-code check can still work. Otherwise fetch the original history or
|
|
266
|
+
renew the evidence. Searches examine at most 1,000 target commits and 1,000
|
|
267
|
+
implementation commits. Results are cached under `.git/workorder-digests/`.
|
|
268
|
+
|
|
269
|
+
## Receipt files
|
|
270
|
+
|
|
271
|
+
New receipts live in
|
|
272
|
+
`.workorder/receipts/<ID>/<UTC time>-<first 12 hash digits>.json`, one packed
|
|
273
|
+
JSON object per file. Each names its `parents`: all current heads for that task.
|
|
274
|
+
Two branches can add receipts for the same task without editing the same file.
|
|
275
|
+
After the branches merge, the next receipt names both heads.
|
|
276
|
+
|
|
277
|
+
Old `.workorder/receipts/<ID>.jsonl` and `.notquite/receipts/<ID>.jsonl` chains
|
|
278
|
+
still verify. New receipts follow their last hash and leave the old file alone.
|
|
279
|
+
Missing parents, changed hashes, wrong filenames, and changes or deletions to
|
|
280
|
+
committed receipts are refused. `check --base REF` also checks every commit
|
|
281
|
+
in `REF..HEAD` for removed or modified receipt files, including a receipt
|
|
282
|
+
added and then deleted, or changed and restored, after `REF`. It names each
|
|
283
|
+
affected path. Complete removal of a finished task with `--allow ID` retains
|
|
284
|
+
its exception for that task's receipts.
|
|
285
|
+
For an old append conflict, run `workorder repair --task ID`. It verifies both
|
|
286
|
+
sides, keeps the common prefix, and converts the extra lines into receipt files.
|
|
287
|
+
See the [reference](docs/reference.md#receipts) for the repair rules.
|
|
288
|
+
|
|
289
|
+
## Contracts and evidence
|
|
290
|
+
|
|
291
|
+
A contract maps each acceptance criterion to the evidence that counts for it:
|
|
292
|
+
|
|
293
|
+
```json
|
|
294
|
+
{
|
|
295
|
+
"task": "TASK-3",
|
|
296
|
+
"criteria": [
|
|
297
|
+
{
|
|
298
|
+
"id": "C1",
|
|
299
|
+
"ask": "Items remain after reloading the running app",
|
|
300
|
+
"critical": true,
|
|
301
|
+
"requires": "REAL",
|
|
302
|
+
"evidence": [{"provenance": "MOCK", "ref": "a simulated browser result"}]
|
|
303
|
+
}
|
|
304
|
+
]
|
|
305
|
+
}
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
| Label | Meaning | Can satisfy |
|
|
309
|
+
|---|---|---|
|
|
310
|
+
| `REAL` | a file in the repository and its `sha256` | `REAL`, `REAL_OR_TEST` |
|
|
311
|
+
| `TEST` | `receipt:<hash>` of a passing test on the implemented code | `REAL_OR_TEST` only |
|
|
312
|
+
| `MOCK`, `SYNTHETIC`, `UNKNOWN` | recorded for honesty | nothing |
|
|
313
|
+
|
|
314
|
+
Critical criteria must be met before DONE. This contract fails: a mock result cannot satisfy a request for real output. `REAL` is a label the author declares, so the file and its hash prove which file was meant, not where it came from. Keep contracts and evidence files under `.workorder/` (for example `.workorder/evidence/`): files there are outside the code fingerprint, so adding one does not change the implemented code. See [examples/](https://github.com/Argento17/workorder/tree/main/examples) for sample tasks and this contract.
|
|
315
|
+
|
|
316
|
+
## Hooks and CI
|
|
317
|
+
|
|
318
|
+
The hook and a local `workorder check` judge recorded evidence. Plain `check`
|
|
319
|
+
reads every task. The hook checks staged task files, receipts, contracts and
|
|
320
|
+
evidence, plus their dependents. In CI, `check --base <main> --run-tests` is
|
|
321
|
+
where each task's declared test is run again on the code being checked.
|
|
322
|
+
`--base` also includes tasks whose test files changed. A reviewer can accept
|
|
323
|
+
changes to a task's requirements with a `workorder-allow:<ID>` pull request
|
|
324
|
+
label, passed as `--allow` in the example below.
|
|
325
|
+
|
|
326
|
+
Pre-commit hook, to refuse committing a false DONE:
|
|
327
|
+
|
|
328
|
+
```sh
|
|
329
|
+
cat > .git/hooks/pre-commit <<'EOF'
|
|
330
|
+
#!/bin/sh
|
|
331
|
+
command -v workorder >/dev/null 2>&1 && exec workorder check --staged
|
|
332
|
+
echo "pre-commit: workorder is not on PATH (pipx install workorder)" >&2
|
|
333
|
+
exit 1
|
|
334
|
+
EOF
|
|
335
|
+
chmod +x .git/hooks/pre-commit
|
|
336
|
+
```
|
|
337
|
+
|
|
338
|
+
GitHub Actions (`.github/workflows/workorder.yml` in your project):
|
|
339
|
+
|
|
340
|
+
```yaml
|
|
341
|
+
name: Workorder
|
|
342
|
+
on:
|
|
343
|
+
pull_request:
|
|
344
|
+
types: [opened, synchronize, reopened, labeled, unlabeled]
|
|
345
|
+
permissions: {contents: read}
|
|
346
|
+
jobs:
|
|
347
|
+
check:
|
|
348
|
+
runs-on: ubuntu-latest
|
|
349
|
+
steps:
|
|
350
|
+
- uses: actions/checkout@v4
|
|
351
|
+
with: {fetch-depth: 0} # receipts refer to earlier commits
|
|
352
|
+
- uses: actions/setup-python@v5
|
|
353
|
+
with: {python-version: '3.12'}
|
|
354
|
+
- run: python -m pip install workorder==0.5.0
|
|
355
|
+
- name: Check tasks and run their tests
|
|
356
|
+
env:
|
|
357
|
+
BASE: origin/${{ github.base_ref }}
|
|
358
|
+
run: |
|
|
359
|
+
# task ids from pull request labels named workorder-allow:<ID>
|
|
360
|
+
allow=$(jq -r '[.pull_request.labels[].name | select(test("^workorder-allow:[A-Z][A-Z0-9]*-[1-9][0-9]*$")) | sub("^workorder-allow:"; "")] | join(",")' "$GITHUB_EVENT_PATH")
|
|
361
|
+
workorder check --base "$BASE" --run-tests ${allow:+--allow "$allow"}
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
What `--base` adds, beyond what the pre-commit hook can promise (`git commit --no-verify` skips the hook):
|
|
365
|
+
|
|
366
|
+
- Receipts already on the base branch must stay unchanged. Receipt files deleted or modified in any commit since the base are refused with their paths, even if absent at the base or restored at HEAD. With `--allow ID`, a task that was DONE, CLOSED or CANCELLED at the base may be removed with all its receipts.
|
|
367
|
+
- A commit since the base that marked a task DONE or CLOSED must carry its implemented code.
|
|
368
|
+
- A change to what a task requires (its `test`, its contract or its evidence, a removed dependency, or a removed or reworded line of its Scope or Acceptance) fails the check until a reviewer accepts it: `--allow TASK-4` (comma-separated ids) for a re-run started by a maintainer. Adding lines is not a change of requirement.
|
|
369
|
+
- Removing or changing lines in a task's test files needs `--allow ID`. Pure additions pass. Set `test_paths` to name files or folders; otherwise Workorder uses paths in the `test` command.
|
|
370
|
+
- A task created and claimed DONE or CLOSED in the same change needs `--allow ID` to accept its definition.
|
|
371
|
+
- With `--run-tests`, the check runs the declared tests of supported DONE or CLOSED claims in scope. It reports how many tasks it checked and how many tests actually ran. If none ran, it says so plainly.
|
|
372
|
+
|
|
373
|
+
Only reviewers who may accept these changes should apply the allow labels.
|
|
374
|
+
`--allow` accepts the named definition changes or complete task removal; it
|
|
375
|
+
does not waive missing evidence, changed receipts on a retained task, or a
|
|
376
|
+
failing test.
|
|
377
|
+
|
|
378
|
+
## Limitations
|
|
379
|
+
|
|
380
|
+
- Anyone who can write files and compute SHA-256 can create a receipt. Rewriting Git history also rewrites its record. `--run-tests` runs the declared tests during the check.
|
|
381
|
+
- A passing test is only as good as its assertions, and the task's `test` is part of the task file: `workorder check --base` refuses a change to it until a reviewer allows it.
|
|
382
|
+
- Committed receipt files stay unchanged; new files can be added. Legacy ledgers keep their committed prefix. The pre-commit hook enforces this against the previous commit, and `workorder check --base <branch>` also refuses receipt-file deletions and modifications anywhere in the intervening history. Without `--base`, a commit made with `git commit --no-verify` can remove receipts unnoticed.
|
|
383
|
+
- A DONE is about the code that was implemented and tested. Code that lands after a task is DONE does not reopen it; `workorder check <id>` notes the change.
|
|
384
|
+
- Only task files are checked. Claims made in chat, issues or pull request text are not.
|
|
385
|
+
- Receipts and claims record your Git `user.name`, and it is pushed. Receipts written by 0.2.0 or earlier also carry the computer's hostname, and keep it.
|
|
386
|
+
- Ids, claims and releases are Git tags, so they show up in tag lists; a `git tag` that picks the newest tag should filter out `workorder/*`.
|
|
387
|
+
- Tasks stay in `tasks/` until removed with reviewer acceptance through `check --base --allow`. Plain `workorder check` reads all current tasks, while the hook and `--base` read what a change touches.
|
|
388
|
+
|
|
389
|
+
## Contributing
|
|
390
|
+
|
|
391
|
+
Bug reports and small pull requests are welcome. See [CONTRIBUTING.md](https://github.com/Argento17/workorder/blob/main/CONTRIBUTING.md).
|
|
392
|
+
|
|
393
|
+
Feedback, issues and ideas welcome, and a star if you find it useful.
|
|
394
|
+
|
|
395
|
+
## License
|
|
396
|
+
|
|
397
|
+
MIT. See [LICENSE](https://github.com/Argento17/workorder/blob/main/LICENSE).
|