workorder 0.5.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.
workorder/gate.py ADDED
@@ -0,0 +1,1292 @@
1
+ """Derive completion from receipts; a status line never supplies missing proof."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import posixpath
7
+ import subprocess
8
+ import uuid
9
+
10
+ from . import store as s
11
+
12
+
13
+ def contract_debt(root, record, history, implemented, staged=False):
14
+ path = record["contract"]
15
+ if path == "none":
16
+ return []
17
+ try:
18
+ contract = json.loads(s.read_text(root, path, staged))
19
+ except json.JSONDecodeError as error:
20
+ raise s.Refused(f"{record['id']}: contract {path} is not valid JSON"
21
+ f" ({error.msg}, line {error.lineno})") from None
22
+ if not isinstance(contract, dict) or contract.get("task") != record["id"]:
23
+ raise s.Refused("contract must name its task")
24
+ criteria = contract.get("criteria")
25
+ if not isinstance(criteria, list) or not criteria:
26
+ raise s.Refused("contract needs a nonempty criteria list")
27
+ debts, seen = [], set()
28
+ for item in criteria:
29
+ if not isinstance(item, dict):
30
+ raise s.Refused("criterion must be an object")
31
+ cid = item.get("id")
32
+ if not isinstance(cid, str) or not cid or cid in seen:
33
+ raise s.Refused("criterion ids must be distinct nonempty strings")
34
+ seen.add(cid)
35
+ if (not isinstance(item.get("ask"), str) or not item["ask"].strip()
36
+ or type(item.get("critical")) is not bool
37
+ or item.get("requires") not in {"REAL", "REAL_OR_TEST"}
38
+ or not isinstance(item.get("evidence"), list)):
39
+ raise s.Refused(f"{cid}: need ask, critical, requires and evidence")
40
+ proved = False
41
+ for evidence in item["evidence"]:
42
+ if (not isinstance(evidence, dict)
43
+ or evidence.get("provenance") not in {"REAL", "TEST", "MOCK", "SYNTHETIC", "UNKNOWN"}
44
+ or not isinstance(evidence.get("ref"), str) or not evidence["ref"]):
45
+ raise s.Refused(f"{cid}: every evidence item needs provenance and ref")
46
+ provenance = evidence["provenance"]
47
+ if provenance == "REAL":
48
+ try:
49
+ artifact = s.read_bytes(root, evidence["ref"], staged)
50
+ except (OSError, s.Refused):
51
+ continue # a missing evidence file proves nothing; the criterion stays owed
52
+ proved |= s.digest(artifact) == evidence.get("sha256")
53
+ elif provenance == "TEST" and item["requires"] != "REAL":
54
+ proved |= any(evidence["ref"] in {"receipt:" + entry["hash"],
55
+ "receipt:" + entry.get("legacy", {}).get("hash", "")}
56
+ and entry["kind"] == "test" and entry["exit_code"] == 0
57
+ and entry["valid"] and implemented is not None and not entry["missing"]
58
+ and entry["code"] == implemented["code"] for entry in history)
59
+ if item["critical"] and not proved:
60
+ debts.append(f"contract {cid}: {item['requires']} evidence")
61
+ return debts
62
+
63
+
64
+ ANY_TEST = "any"
65
+
66
+
67
+ def declared_test(record):
68
+ """The task's own test command as an argument list, or None when any command counts: no test
69
+ declared (which DONE refuses) or the explicit opt-out test: any."""
70
+ value = record.get("test", "").strip()
71
+ return s.split_command(value) if value and value != ANY_TEST else None
72
+
73
+
74
+ def counting_runs(record, current, implemented):
75
+ """Test runs that can decide: on the implemented code, on a commit in this clone, and the task's
76
+ declared test command when it has one."""
77
+ declared = declared_test(record)
78
+ return [e for e in current if e["kind"] == "test" and not e["missing"]
79
+ and e["code"] == implemented["code"] and (declared is None or e["command"] == declared)]
80
+
81
+
82
+ def carries(root, implemented, item):
83
+ """A merge or deployment carries the tested code when it holds exactly that code, or when its commit
84
+ contains the implemented commit (a merge commit or fast-forward, with other work beside it)."""
85
+ return (implemented is not None and not implemented["missing"] and not item["missing"]
86
+ and (item["code"] == implemented["code"]
87
+ or s.contains(root, implemented["commit"], item["commit"])))
88
+
89
+
90
+ def code_seen(root, tid, code, staged=False):
91
+ """A commit in this clone that holds exactly this code: HEAD, or a commit that touched the task or
92
+ its receipts (a squash merge does). None when there is none."""
93
+ candidates = ["HEAD"] + s.git(root, "log", "--format=%H", "-n", "50", "HEAD", "--", f"tasks/{tid}.md",
94
+ s.ledger_path(tid), f".workorder/receipts/{tid}",
95
+ f".notquite/receipts/{tid}.jsonl", required=False).stdout.split()
96
+ for commit in candidates:
97
+ found = s.git(root, "rev-parse", "--verify", "--quiet", f"{commit}^{{commit}}", required=False)
98
+ if found.returncode == 0 and s.code_digest(root, found.stdout.strip()) == code:
99
+ return found.stdout.strip()
100
+ return None
101
+
102
+
103
+ def recognise_squashed(root, tid, history, staged=False):
104
+ """Receipts whose commits are gone (squash, rebase, amend) count again when a commit in this clone
105
+ holds exactly the code they recorded: the evidence is about that code, and the code is here."""
106
+ implemented = newest_implementation(history)
107
+ if implemented is None or not implemented["missing"]:
108
+ return
109
+ seen = code_seen(root, tid, implemented["code"], staged)
110
+ if not seen:
111
+ merged = computed_merge(root, s.record(root, tid, staged), implemented)
112
+ if merged and merged["method"] == "same code":
113
+ seen = merged["commit"]
114
+ if seen:
115
+ for item in history:
116
+ if item["missing"] and item["code"] == implemented["code"]:
117
+ item["missing"], item["seen_on"] = False, seen
118
+
119
+
120
+ # Limit both sides of a patch comparison. An incomplete search never proves a rebase.
121
+ MERGE_SEARCH_LIMIT = 1000
122
+
123
+
124
+ def merge_target(root, record):
125
+ # The pushed branch first: a commit only on local main is not merged for anyone else yet.
126
+ override = record.get("merge_ref")
127
+ refs = [override] if override else ["refs/remotes/origin/main", "refs/remotes/origin/master",
128
+ "refs/heads/main", "refs/heads/master"]
129
+ for ref in refs:
130
+ found = s.git(root, "rev-parse", "--verify", "--quiet", f"{ref}^{{commit}}", required=False)
131
+ if found.returncode == 0:
132
+ return ref, found.stdout.strip()
133
+ return None
134
+
135
+
136
+ def patch_ids(root, revision, commits=None):
137
+ """git cherry semantics, restricted to code, in two Git calls for the whole range."""
138
+ selection = (["--no-walk=unsorted", "--diff-merges=first-parent", *commits] if commits is not None
139
+ else ["--no-merges", f"--max-count={MERGE_SEARCH_LIMIT + 1}", revision])
140
+ if commits == []:
141
+ return {}
142
+ patches = s.git(root, "log", *selection, "--format=commit %H", "-p", "--binary", "--no-renames",
143
+ "--no-ext-diff", "--no-textconv", "--", *s.CODE_PATHS).stdout
144
+ result = s.git(root, "patch-id", "--stable", data=patches).stdout
145
+ return {commit: patch for patch, commit in (line.split() for line in result.splitlines())}
146
+
147
+
148
+ def merge_match(root, implemented, target):
149
+ """Evidence from immutable commits, cached independently of branch names and HEAD."""
150
+ original = implemented["commit"]
151
+ key = s.digest(s.packed(["merge-v4", original, s.has_commit(root, original), implemented["code"],
152
+ target, MERGE_SEARCH_LIMIT]).encode())
153
+ folder = s._cache_dir(root)
154
+ cached = folder / ("merge-" + key + ".json") if folder else None
155
+ try:
156
+ if cached and cached.is_file():
157
+ value = json.loads(cached.read_text(encoding="utf-8"))
158
+ if value is None or (isinstance(value, dict) and value.get("method") in
159
+ {"ancestry", "same code", "squash", "rebase"} and s.has_commit(root, value.get("commit", ""))):
160
+ return value
161
+ except (OSError, ValueError):
162
+ pass
163
+ result = _merge_match(root, implemented, target)
164
+ try:
165
+ if cached:
166
+ folder.mkdir(exist_ok=True)
167
+ # Atomic replacement keeps concurrent checks from reading a partial cache file.
168
+ temporary = cached.with_suffix("." + uuid.uuid4().hex)
169
+ temporary.write_text(s.packed(result), encoding="utf-8")
170
+ temporary.replace(cached)
171
+ except OSError:
172
+ pass
173
+ return result
174
+
175
+
176
+ def _merge_match(root, implemented, target):
177
+ original = implemented["commit"]
178
+ present = s.has_commit(root, original)
179
+ if present and s.contains(root, original, target):
180
+ # Name the landing, not a moving tip that may have undone the tested code.
181
+ mainline = s.git(root, "rev-list", "--first-parent", target).stdout.split()
182
+ if original in mainline:
183
+ landing = original
184
+ else:
185
+ descendants = set(s.git(root, "rev-list", "--ancestry-path", f"{original}..{target}").stdout.split())
186
+ landing = next(commit for commit in reversed(mainline) if commit in descendants)
187
+ return {"method": "ancestry", "commit": landing}
188
+ base = s.git(root, "merge-base", original, target, required=False).stdout.strip() if present else ""
189
+ revision = f"{base}..{target}" if base else target
190
+ # Only code-changing commits can supply a same-code or patch match.
191
+ candidates = s.git(root, "rev-list", f"--max-count={MERGE_SEARCH_LIMIT}", revision).stdout.split()
192
+ target_patches = patch_ids(root, revision, candidates)
193
+ for commit in reversed(target_patches):
194
+ if s.code_digest(root, commit) == implemented["code"]:
195
+ return {"method": "same code", "commit": commit}
196
+ if not base:
197
+ return None
198
+ combined = s.git(root, "diff", "--binary", "--no-renames", "--no-ext-diff", "--no-textconv",
199
+ base, original, "--", *s.CODE_PATHS).stdout
200
+ combined_id = s.git(root, "patch-id", "--stable", data=combined).stdout.split()
201
+ if combined_id:
202
+ for commit, patch in reversed(list(target_patches.items())):
203
+ if patch == combined_id[0]:
204
+ return {"method": "squash", "commit": commit}
205
+ # Count all commits (including merges and metadata) so truncation cannot look complete.
206
+ feature = s.git(root, "rev-list", f"--max-count={MERGE_SEARCH_LIMIT + 1}", f"{base}..{original}").stdout.split()
207
+ if len(feature) > MERGE_SEARCH_LIMIT:
208
+ return None
209
+ feature_patches = patch_ids(root, f"{base}..{original}")
210
+ # A merge's own resolution is not represented by git cherry; do not silently skip it.
211
+ merges = s.git(root, "rev-list", "--merges", f"{base}..{original}", "--", *s.CODE_PATHS).stdout.split()
212
+ available = set(target_patches.values())
213
+ if not merges and feature_patches and set(feature_patches.values()) <= available:
214
+ representatives = {patch: commit for commit, patch in target_patches.items()
215
+ if patch in set(feature_patches.values())}
216
+ matched = next(commit for commit in target_patches if commit in set(representatives.values()))
217
+ if not all(s.contains(root, representatives[patch], matched) for patch in feature_patches.values()):
218
+ matched = target # patches on separate merged branches must all be present in a deployment
219
+ return {"method": "rebase", "commit": matched}
220
+ return None
221
+
222
+
223
+ def computed_merge(root, record, implemented):
224
+ if record["ships"] == "none" or implemented is None:
225
+ return None
226
+ target = merge_target(root, record)
227
+ if target is None:
228
+ return None
229
+ ref, commit = target
230
+ # Always inspect the selected target. HEAD on a feature branch is never a fallback target.
231
+ match = merge_match(root, implemented, commit)
232
+ if match:
233
+ return {**match, "ref": ref, "target": commit}
234
+ return None
235
+
236
+
237
+ def merge_line(merged):
238
+ ref = merged["ref"].removeprefix("refs/heads/").removeprefix("refs/remotes/")
239
+ return f"merged into {ref} by {merged['method']} {merged['commit'][:7]}, computed"
240
+
241
+
242
+ def delivered_code(root, implemented, item, computed=None):
243
+ return carries(root, implemented, item) or bool(
244
+ computed and not item["missing"] and s.contains(root, computed["commit"], item["commit"]))
245
+
246
+
247
+ def verdict(root, record, staged=False):
248
+ tid = record["id"]
249
+ history = s.entries(root, tid, staged)
250
+ recognise_squashed(root, tid, history, staged)
251
+ index = max((i for i, e in enumerate(history) if e["kind"] == "implemented"), default=-1)
252
+ implemented = history[index] if index >= 0 else None
253
+ current = history[index + 1:] if implemented else []
254
+ done = []
255
+ if not record.get("test", "").strip():
256
+ done.append("a declared test") # the command that proves the task, or test: any
257
+ if not implemented:
258
+ done.append("implementation")
259
+ elif implemented["missing"]:
260
+ done.append(f"implementation (commit {implemented['commit'][:7]} is not in this clone)")
261
+ else:
262
+ # The latest test run on the implemented code decides; a later failure revokes an earlier pass.
263
+ # Code leaves out tasks/ and .workorder/, so committing the receipts does not hide later runs.
264
+ runs = counting_runs(record, current, implemented)
265
+ if not runs or runs[-1]["exit_code"] != 0 or not runs[-1]["valid"]:
266
+ done.append(f"a passing test on {implemented['commit'][:7]}")
267
+ done += contract_debt(root, record, current, implemented, staged)
268
+ delivery = []
269
+ computed = computed_merge(root, record, implemented)
270
+ if record["ships"] != "none":
271
+ # Any merge receipt that carries the tested code counts; a later one that does not, cannot undo it.
272
+ merges = [i for i, e in enumerate(current) if e["kind"] == "merged" and carries(root, implemented, e)]
273
+ merge_index = merges[-1] if merges else -1
274
+ merged = current[merge_index] if merges else computed
275
+ if not merged:
276
+ delivery.append("merge of the tested code")
277
+ if record["ships"] == "live":
278
+ after_merge = current if computed else current[merge_index + 1:] if merged else []
279
+ deploy_index = max((i for i, e in enumerate(after_merge) if e["kind"] == "deployed"), default=-1)
280
+ deployed = after_merge[deploy_index] if deploy_index >= 0 else None
281
+ if (not deployed or not deployed["valid"] or deployed["exit_code"] != 0
282
+ or not delivered_code(root, implemented, deployed, computed)):
283
+ delivery.append("deployment read-back of the tested code")
284
+ after_deploy = after_merge[deploy_index + 1:] if deployed else []
285
+ if not deployed or not any(e["kind"] == "live" and e["valid"] and e["exit_code"] == 0
286
+ and not e["missing"] and e["commit"] == deployed["commit"]
287
+ and e["target"] == deployed["target"] for e in after_deploy):
288
+ delivery.append("live read-back after deployment")
289
+ computed = "IN_PROGRESS" if done else "DONE" if delivery else "CLOSED"
290
+ return computed, done, delivery
291
+
292
+
293
+ def task_names(root, staged=False):
294
+ """Ids of the task files: tasks/<ID>.md. Other files there (a README, notes, subfolders) are not tasks."""
295
+ names = []
296
+ for path in s.files(root, "tasks", staged):
297
+ name = path.removeprefix("tasks/")
298
+ if name.endswith(".md") and "/" not in name and s.ID.fullmatch(name[:-3]):
299
+ names.append(name[:-3])
300
+ return names
301
+
302
+
303
+ def records(root, staged=False, errors=None):
304
+ """Task records by id. With errors (a dict), a task file that cannot be read is reported there and
305
+ left out, so one bad file does not stop the others; without it, the first bad file is refused."""
306
+ result = {}
307
+ for tid in task_names(root, staged):
308
+ try:
309
+ result[tid] = s.record(root, tid, staged)
310
+ except s.Refused as error:
311
+ if errors is None:
312
+ raise
313
+ errors[tid] = str(error)
314
+ return result
315
+
316
+
317
+ def waits(record, all_records, views, seen=frozenset()):
318
+ """Open dependencies: person waits, and tasks that are not finished."""
319
+ result = []
320
+ for wait in s.dependencies(record):
321
+ kind, value = wait.split(":", 1)
322
+ if kind == "person" or not finished(value, all_records, views, seen):
323
+ result.append(wait)
324
+ return result
325
+
326
+
327
+ def finished(tid, all_records, views, seen=frozenset()):
328
+ """A dependency is finished when its evidence computes DONE or CLOSED and its own dependencies are
329
+ finished, all the way down. A cycle never counts as finished."""
330
+ # Finished means the task says DONE or CLOSED and its evidence supports that: a reopened task
331
+ # (status set back to IN_PROGRESS) holds back the tasks that depend on it, as does a cancelled one.
332
+ if (tid not in all_records or tid in seen or views[tid][0] not in {"DONE", "CLOSED"}
333
+ or all_records[tid]["status"] not in {"DONE", "CLOSED"}):
334
+ return False
335
+ return not waits(all_records[tid], all_records, views, seen | {tid})
336
+
337
+
338
+ @s.cached_read
339
+ def fields_at(root, tid, rev="HEAD"):
340
+ """The front matter of tasks/<tid>.md at a revision, or None if it has no readable record there."""
341
+ text = s.metadata_texts(root, rev, tid if rev != "HEAD" else None, False).get(f"tasks/{tid}.md")
342
+ if text is None:
343
+ return None
344
+ lines = text.splitlines()
345
+ try:
346
+ return s.front_matter(tid, lines[1:lines.index("---", 1)])
347
+ except (s.Refused, ValueError):
348
+ return None
349
+
350
+
351
+ def committed_status(root, tid, rev="HEAD"):
352
+ """The status line of tasks/<tid>.md at a revision, or None if it has no readable record there."""
353
+ fields = fields_at(root, tid, rev)
354
+ return fields.get("status") if fields else None
355
+
356
+
357
+ def newest_implementation(history):
358
+ index = max((i for i, e in enumerate(history) if e["kind"] == "implemented"), default=-1)
359
+ return history[index] if index >= 0 else None
360
+
361
+
362
+ def base_problems(root, base, staged=False, retired=frozenset()):
363
+ """Receipts committed on the base revision must still be there, unchanged, as a prefix."""
364
+ found = s.git(root, "rev-parse", "--verify", "--quiet", f"{base}^{{commit}}", required=False)
365
+ if found.returncode:
366
+ raise s.Refused(f"base {base} is not in this clone; fetch it"
367
+ " (in GitHub Actions: actions/checkout with fetch-depth: 0)")
368
+ commit = found.stdout.strip()
369
+ problems = []
370
+ tids = {s.receipt_task(p) for p in s.receipt_paths(root, rev=commit)} - {None}
371
+ for tid in sorted(tids):
372
+ if tid in retired:
373
+ continue
374
+ before = s.receipt_texts(root, tid, rev=commit)
375
+ after = s.receipt_texts(root, tid, staged)
376
+ try:
377
+ history = s.ordered_entries(root, tid, after)
378
+ except (s.Refused, ValueError):
379
+ history = None
380
+ if s.receipt_changes(root, tid, before, after, history):
381
+ problems.append(f"{tid}: receipts recorded on {base} were removed or changed")
382
+ # Endpoints miss a receipt added and then hidden, or edited and restored, in this range.
383
+ changed = s.git(root, "log", "--format=", "--name-only", "-z", "--diff-filter=DMT",
384
+ "--no-renames", "-m", "--full-history", f"{commit}..HEAD", "--",
385
+ *s.RECEIPT_DIRS).stdout
386
+ for path in sorted(set(changed.split("\0")) - {""}):
387
+ tid = s.receipt_task(path)
388
+ if tid and tid not in retired:
389
+ problems.append(f"{tid}: committed receipt file removed or changed since {base}: {path}")
390
+ return problems
391
+
392
+
393
+ def implementation_at(root, rev, tid):
394
+ """Use the same receipt order for historical claims as for current verdicts."""
395
+ return newest_implementation(s.entries(root, tid, rev=rev))
396
+
397
+
398
+ FINISHED = {"DONE", "CLOSED"}
399
+ ACCEPTANCE_NOTE = ("the evidence covers the task's test only, not its Acceptance list;"
400
+ " finish every Acceptance item before claiming DONE")
401
+ UNCLAIMED_OWES = "its Acceptance items, then status DONE (the evidence for its test is in place)"
402
+
403
+
404
+ def owes(record, owed, delivery=()):
405
+ """What a task still owes. A task nobody has claimed finished is never 'owing nothing'."""
406
+ items = list(owed)
407
+ if not items and record["status"] not in FINISHED | {"CANCELLED"}:
408
+ items.append(UNCLAIMED_OWES)
409
+ return ", ".join(items + list(delivery)) or "nothing"
410
+
411
+
412
+ @s.cached_read
413
+ def task_history(root, base=None):
414
+ """One history walk for a linear task history. Merge histories keep Git's per-path simplification."""
415
+ log = s.git(root, "log", "--full-history", "--format=commit %H %P", "--raw", "--no-abbrev",
416
+ "--no-renames", f"{base}..HEAD" if base else "HEAD", "--", "tasks").stdout
417
+ changes, commit = {}, None
418
+ for line in log.splitlines():
419
+ if line.startswith("commit "):
420
+ words = line.split()
421
+ if len(words) > 3:
422
+ return None # a merge needs the same path-specific history used by earlier releases
423
+ commit = words[1]
424
+ elif line.startswith(":") and "\t" in line:
425
+ info, path = line.split("\t", 1)
426
+ tid = path.removeprefix("tasks/").removesuffix(".md")
427
+ if path == f"tasks/{tid}.md" and s.ID.fullmatch(tid):
428
+ oid = info.split()[3]
429
+ changes.setdefault(tid, []).append((commit, oid))
430
+ blobs = s.read_blobs(root, {oid for items in changes.values() for _, oid in items if set(oid) != {"0"}})
431
+ result = {}
432
+ for tid, items in changes.items():
433
+ statuses = []
434
+ for commit, oid in items:
435
+ lines = blobs.get(oid, "").splitlines()
436
+ try:
437
+ fields = s.front_matter(tid, lines[1:lines.index("---", 1)])
438
+ except (ValueError, s.Refused):
439
+ fields = {}
440
+ statuses.append((commit, fields.get("status")))
441
+ result[tid] = statuses
442
+ return result
443
+
444
+
445
+ def stale_claim(root, record, staged=False, base=None):
446
+ """A DONE or CLOSED claim must be made on the code of the implementation it relies on.
447
+
448
+ An uncommitted claim is compared with the code being committed (the index under --staged, HEAD
449
+ otherwise). A committed claim is found in the task file's history (since base, when given) and
450
+ compared with the code of the commit that made it, unless the evidence was renewed after it.
451
+ """
452
+ tid, status = record["id"], record["status"]
453
+ if status not in FINISHED:
454
+ return None
455
+ current = newest_implementation(s.entries(root, tid, staged))
456
+ if current is None or current["missing"]:
457
+ return None # the verdict already reports these
458
+ short = current["commit"][:7]
459
+ if committed_status(root, tid) != status:
460
+ dirty = [] if staged else s.dirty_paths(root)
461
+ if dirty:
462
+ return (f"NOT QUITE {tid} is being marked {status} with uncommitted code changes; "
463
+ + s.describe_dirty(dirty) + f". Commit, record workorder receipt implemented --task {tid}"
464
+ " and test again.")
465
+ tree = s.git(root, "write-tree").stdout.strip() if staged else s.head(root)
466
+ if claim_matches(root, record, current, s.head(root), tree):
467
+ return None
468
+ where = "in this commit" if staged else "now"
469
+ return (f"NOT QUITE {tid} is being marked {status}, but the code {where} differs from the"
470
+ f" implemented commit {short}. Record workorder receipt implemented --task {tid} and test again.")
471
+ histories = task_history(root, base)
472
+ if histories is None:
473
+ commits = s.git(root, "log", "--format=%H", f"{base}..HEAD" if base else "HEAD", "--",
474
+ f"tasks/{tid}.md").stdout.split()
475
+ statuses = ((commit, committed_status(root, tid, commit)) for commit in commits)
476
+ else:
477
+ statuses = histories.get(tid, [])
478
+ claim = None
479
+ for commit, status_at_commit in statuses: # newest first: find the commit that made the claim
480
+ if status_at_commit != status:
481
+ break
482
+ claim = commit
483
+ else:
484
+ if base and committed_status(root, tid, base) == status:
485
+ claim = None # claimed before the base
486
+ if claim is None:
487
+ return None
488
+ relied_on = implementation_at(root, claim, tid)
489
+ if relied_on is None or current["hash"] != relied_on.get("hash"):
490
+ return None
491
+ if claim_matches(root, record, current, claim):
492
+ return None
493
+ return (f"NOT QUITE {tid} was marked {status} in {claim[:7]} on code other than the implemented"
494
+ f" commit {short}. Run workorder renew --task {tid} on that code, or record"
495
+ f" workorder receipt implemented --task {tid} and test again.")
496
+
497
+
498
+ def claim_matches(root, record, implemented, claim, tree=None):
499
+ tree = tree or claim
500
+ # This concerns the claim's history, even when the task ships nothing.
501
+ target = merge_target(root, record)
502
+ merged = merge_match(root, implemented, target[1]) if target else None
503
+ if merged and s.contains(root, merged["commit"], claim):
504
+ return unchanged_implementation_paths(root, implemented, merged, tree)
505
+ if s.code_digest(root, tree) == implemented["code"]:
506
+ return True
507
+ if merged and s.contains(root, claim, merged["commit"]):
508
+ # Landing must not invalidate a claim whose patch matched before it landed.
509
+ before = s.git(root, "rev-parse", "--verify", "--quiet", f"{merged['commit']}^1",
510
+ required=False).stdout.strip()
511
+ if before and equivalent_claim(root, record, implemented, tree, before):
512
+ return True
513
+ return tree == claim and equivalent_claim(root, record, implemented, claim)
514
+
515
+
516
+ def unchanged_implementation_paths(root, implemented, merged, claim):
517
+ """Only changes on implementation paths can invalidate a claim after its landing."""
518
+ original, landing = implemented["commit"], merged["commit"]
519
+ if claim == landing:
520
+ return True
521
+ changed = s.git(root, "diff", "--name-only", "-z", "--no-renames", landing, claim,
522
+ "--", *s.CODE_PATHS).stdout
523
+ if not changed:
524
+ return True
525
+ reference = landing
526
+ if merged["method"] == "ancestry":
527
+ reference = s.git(root, "rev-parse", "--verify", "--quiet", f"{landing}^1",
528
+ required=False).stdout.strip()
529
+ base = (s.git(root, "merge-base", original, reference, required=False).stdout.strip()
530
+ if reference and s.has_commit(root, original) else "")
531
+ if landing == original:
532
+ # A fast-forward has no merge commit recording the branch boundary. Use the
533
+ # task's current open period, or the implementation's parent when the task
534
+ # was introduced later. This includes earlier commits of a multi-commit task.
535
+ commits = s.git(root, "log", "--format=%H", original, "--", f"tasks/{implemented['task']}.md").stdout.split()
536
+ for commit in commits:
537
+ status = committed_status(root, implemented["task"], commit)
538
+ if status is None or status in FINISHED | {"CANCELLED"}:
539
+ break
540
+ base = commit
541
+ if base and base != original:
542
+ paths = s.git(root, "diff", "--name-only", "-z", "--no-renames", base, original,
543
+ "--", *s.CODE_PATHS).stdout
544
+ else:
545
+ # Without a branch boundary (or the original history), the recorded tree is the
546
+ # evidence available. Include deleted paths too, so restoring one cannot escape.
547
+ paths = s.git(root, "ls-tree", "-r", "--name-only", "-z", landing).stdout
548
+ paths = "\0".join(p for p in paths.split("\0")
549
+ if not p.startswith(("tasks/", ".workorder/", ".notquite/")))
550
+ paths += s.git(root, "diff-tree", "--root", "--no-commit-id", "-r", "--name-only", "-z",
551
+ "--no-renames", landing, "--", *s.CODE_PATHS).stdout
552
+ return not ((set(paths.split("\0")) - {""}) & (set(changed.split("\0")) - {""}))
553
+
554
+
555
+ def equivalent_claim(root, record, implemented, claim, target_commit=None):
556
+ """A rebase preserves the code patch relative to each commit's own target merge base."""
557
+ if target_commit is None:
558
+ target = merge_target(root, record)
559
+ if target is None:
560
+ return False
561
+ target_commit = target[1]
562
+ patches = []
563
+ for commit in (implemented["commit"], claim):
564
+ base = s.git(root, "merge-base", commit, target_commit, required=False).stdout.strip()
565
+ if not base:
566
+ return False
567
+ diff = s.git(root, "diff", "--binary", "--no-renames", "--no-ext-diff", "--no-textconv",
568
+ base, commit, "--", *s.CODE_PATHS).stdout
569
+ patch = s.git(root, "patch-id", "--stable", data=diff).stdout.split()
570
+ if not patch:
571
+ return False # an empty change cannot excuse a claim on different code
572
+ patches.append(patch[0])
573
+ return patches[0] == patches[1]
574
+
575
+
576
+ def unpushed_target(root, record):
577
+ target = merge_target(root, record)
578
+ if target is None or not target[0].startswith("refs/remotes/"):
579
+ return None
580
+ remote, branch = target[0].removeprefix("refs/remotes/").split("/", 1)
581
+ local = s.git(root, "rev-parse", "--verify", "--quiet", f"refs/heads/{branch}^{{commit}}",
582
+ required=False)
583
+ implemented = newest_implementation(s.entries(root, record["id"]))
584
+ if (local.returncode == 0 and implemented and not merge_match(root, implemented, target[1])
585
+ and merge_match(root, implemented, local.stdout.strip())):
586
+ return f"push {branch} to {remote}: git push {remote} {branch}"
587
+ return None
588
+
589
+
590
+ def changed_paths(root, reference, staged=False):
591
+ """Paths that differ between reference and what is being checked (the index under --staged, the
592
+ working tree otherwise, which in CI is the commit being checked), untracked task files included."""
593
+ args = ["diff", "--name-only", "-z", "--no-renames"] + (["--cached"] if staged else []) + [reference]
594
+ paths = set(s.git(root, *args).stdout.split("\0")) - {""}
595
+ if not staged:
596
+ paths |= set(s.git(root, "ls-files", "-z", "--others", "--exclude-standard").stdout.split("\0")) - {""}
597
+ return paths
598
+
599
+
600
+ def evidence_paths(root, record, staged=False):
601
+ """The contract file of a task and the REAL evidence files it names."""
602
+ path = record.get("contract", "none")
603
+ if path == "none":
604
+ return set()
605
+ found = {path}
606
+ try:
607
+ contract = json.loads(s.read_text(root, path, staged))
608
+ for item in contract.get("criteria", []) if isinstance(contract, dict) else []:
609
+ for evidence in item.get("evidence", []) if isinstance(item, dict) else []:
610
+ if isinstance(evidence, dict) and evidence.get("provenance") == "REAL":
611
+ found.add(str(evidence.get("ref", "")))
612
+ except (OSError, ValueError, s.Refused, AttributeError):
613
+ pass
614
+ return found
615
+
616
+
617
+ @s.cached_read
618
+ def repository_files(root, rev=None):
619
+ args = ["ls-tree", "-r", "--name-only", "-z", rev] if rev else ["ls-files", "-z"]
620
+ return set(s.git(root, *args).stdout.split("\0")) - {""}
621
+
622
+
623
+ def test_files(root, record, base, staged=False):
624
+ """Expand current and base definitions, so deleting a test or changing its path cannot hide it."""
625
+ before = fields_at(root, record["id"], base)
626
+ candidates = repository_files(root, base) | repository_files(root)
627
+ candidates |= changed_paths(root, base, staged)
628
+ found = set()
629
+ for definition in (before, record):
630
+ if definition is None:
631
+ continue
632
+ paths = definition.get("test_paths")
633
+ if paths is None:
634
+ paths = declared_test(definition) or []
635
+ if not isinstance(paths, list):
636
+ continue
637
+ for path in paths:
638
+ if not isinstance(path, str):
639
+ continue
640
+ if "test_paths" not in definition:
641
+ path = path.split("::", 1)[0] # pytest node selection
642
+ try:
643
+ path = posixpath.normpath(s.local_path(root, path).relative_to(root).as_posix())
644
+ except (s.Refused, ValueError):
645
+ continue
646
+ found |= {p for p in candidates if path == "." or p == path or p.startswith(path + "/")}
647
+ return found
648
+
649
+
650
+ def test_file_changes(root, base, record, staged=False):
651
+ paths = sorted(test_files(root, record, base, staged) & changed_paths(root, base, staged))
652
+ if not paths:
653
+ return None
654
+ # Disabling rename detection makes a rename remove the old file's lines, even when identical.
655
+ args = ["diff", "--numstat", "-z", "--no-renames", "--no-ext-diff", "--no-textconv"]
656
+ if staged:
657
+ args.append("--cached")
658
+ delta = s.git(root, *args, base, "--", *(f":(literal){p}" for p in paths)).stdout
659
+ lost, affected, binary = 0, [], False
660
+ for entry in delta.split("\0"):
661
+ if not entry:
662
+ continue
663
+ added, removed, path = entry.split("\t", 2)
664
+ if path not in repository_files(root, base):
665
+ continue # new files, including binary fixtures, are pure additions
666
+ exists = path in repository_files(root) if staged else s.local_path(root, path).is_file()
667
+ if removed == "-" or int(removed) or not exists:
668
+ lost += int(removed) if removed != "-" else 0
669
+ binary |= removed == "-"
670
+ affected.append(path)
671
+ if affected:
672
+ change = "changed binary content" if binary else f"lost or changed {lost} lines"
673
+ return f"{record['id']}: its test files {change} since {base} ({', '.join(affected)})"
674
+ return None
675
+
676
+
677
+ def scope(root, reference, staged, names, all_records, include_tests=False):
678
+ """The tasks a change touches (task file, receipts, contract or its evidence), and every task that
679
+ depends on one of them, directly or not."""
680
+ changed = changed_paths(root, reference, staged)
681
+ touched = {path[6:-3] for path in changed if path.startswith("tasks/") and path.endswith(".md")
682
+ and s.ID.fullmatch(path[6:-3])}
683
+ touched |= {s.receipt_task(path) for path in changed} - {None}
684
+ touched |= {tid for tid, record in all_records.items() if evidence_paths(root, record, staged) & changed}
685
+ if include_tests:
686
+ touched |= {tid for tid, record in all_records.items()
687
+ if test_files(root, record, reference, staged) & changed}
688
+ growing = True
689
+ while growing:
690
+ growing = False
691
+ for tid, record in all_records.items():
692
+ if tid not in touched and any(w[5:] in touched for w in s.dependencies(record) if w.startswith("task:")):
693
+ touched.add(tid)
694
+ growing = True
695
+ return touched, changed
696
+
697
+
698
+ def requirement_changes(root, base, record):
699
+ """Changes since base to what a task requires: its test, its contract, its dependencies."""
700
+ tid, found = record["id"], []
701
+ before = fields_at(root, tid, base)
702
+ if before is None:
703
+ return found
704
+ if before.get("test", "") != record.get("test", ""):
705
+ found.append(f"test changed: {before.get('test', '') or '(none)'!r} -> {record.get('test', '') or '(none)'!r}")
706
+ if before.get("test_paths") != record.get("test_paths"):
707
+ found.append("test_paths changed")
708
+ if before.get("contract") != record.get("contract"):
709
+ found.append(f"contract changed: {before.get('contract')} -> {record.get('contract')}")
710
+ elif record.get("contract", "none") != "none":
711
+ old = s.git(root, "show", f"{base}:{record['contract']}", required=False)
712
+ try:
713
+ now = s.read_text(root, record["contract"])
714
+ except (OSError, s.Refused):
715
+ now = None
716
+ if old.returncode == 0 and now is not None and now != old.stdout.replace("\r\n", "\n"):
717
+ found.append(f"contract {record['contract']} edited")
718
+ try:
719
+ dropped = sorted(set(s.dependencies({"waits_on": before.get("waits_on", []),
720
+ "depends_on": s.task_refs(tid, "depends_on", before.get("depends_on", []))}))
721
+ - set(s.dependencies(record)))
722
+ except (s.Refused, TypeError):
723
+ dropped = []
724
+ if dropped:
725
+ found.append(f"dependencies removed: {', '.join(dropped)}")
726
+ # The written ask: removing or rewording a Scope or Acceptance line changes what DONE means.
727
+ # Adding lines does not (that is how a task gets filled in).
728
+ old = s.git(root, "show", f"{base}:tasks/{tid}.md", required=False)
729
+ if old.returncode == 0:
730
+ def section_lines(text, name):
731
+ return {line.strip() for heading, body in s.task_body_sections(text) if heading == name
732
+ for line in body if line.strip() and not line.strip().startswith("<!--")}
733
+ try:
734
+ now_text = s.read_text(root, f"tasks/{tid}.md")
735
+ except (OSError, s.Refused):
736
+ now_text = ""
737
+ before_text = old.stdout.replace("\r\n", "\n")
738
+ for name in ("Scope", "Acceptance"):
739
+ removed = section_lines(before_text, name) - section_lines(now_text, name)
740
+ if removed:
741
+ found.append(f"{name} lines removed or changed: {len(removed)}")
742
+ return found
743
+
744
+
745
+ def run_declared_test(root, record, counts=None):
746
+ """Run a task's declared test here (CI), without a shell; return a problem line, or None if it passed."""
747
+ tid, declared = record["id"], declared_test(record)
748
+ if declared is None:
749
+ return f"NOT QUITE {tid} says {record['status']} but declares no test for this check to run"
750
+ try:
751
+ code = subprocess.run(declared, cwd=root).returncode
752
+ if counts is not None:
753
+ counts["tests"] += 1
754
+ except OSError as error:
755
+ code = f"not started: {error.strerror}"
756
+ finally:
757
+ s.invalidate_reads() # a declared command may have changed files or refs
758
+ if code == 0:
759
+ return None
760
+ return f"NOT QUITE {tid} says {record['status']}, but its test failed when this check ran it (exit {code})"
761
+
762
+
763
+ class Views(dict):
764
+ """Verdicts worked out on first use, so a scoped check reads only the tasks it needs."""
765
+
766
+ def __init__(self, root, all_records, staged=False):
767
+ super().__init__()
768
+ self.root, self.all_records, self.staged = root, all_records, staged
769
+
770
+ def __missing__(self, tid):
771
+ self[tid] = verdict(self.root, self.all_records[tid], self.staged)
772
+ return self[tid]
773
+
774
+
775
+ def dependency_cycles(all_records):
776
+ """Strongly connected components: only participants get a cycle problem."""
777
+ indices, low, stack, active, cycles = {}, {}, [], set(), {}
778
+
779
+ def visit(tid):
780
+ indices[tid] = low[tid] = len(indices)
781
+ stack.append(tid)
782
+ active.add(tid)
783
+ children = [w[5:] for w in s.dependencies(all_records[tid])
784
+ if w.startswith("task:") and w[5:] in all_records]
785
+ for other in children:
786
+ if other not in indices:
787
+ visit(other)
788
+ low[tid] = min(low[tid], low[other])
789
+ elif other in active:
790
+ low[tid] = min(low[tid], indices[other])
791
+ if low[tid] == indices[tid]:
792
+ group = []
793
+ while True:
794
+ other = stack.pop()
795
+ active.remove(other)
796
+ group.append(other)
797
+ if other == tid:
798
+ break
799
+ if len(group) > 1 or tid in children:
800
+ for other in group:
801
+ cycles[other] = "dependency cycle: " + ", ".join(sorted(group))
802
+
803
+ for tid in all_records:
804
+ if tid not in indices:
805
+ visit(tid)
806
+ return cycles
807
+
808
+
809
+ def removals(root, base, names, allow, staged=False):
810
+ before = s.metadata_texts(root, base, None, False)
811
+ old_tasks = {p[6:-3] for p in before if p.startswith("tasks/") and p.endswith(".md")
812
+ and s.ID.fullmatch(p[6:-3])}
813
+ retired, problems = set(), []
814
+ for tid in sorted(old_tasks - set(names)):
815
+ if (tid in allow and committed_status(root, tid, base) in FINISHED | {"CANCELLED"}
816
+ and not s.receipt_paths(root, staged, tid=tid)):
817
+ retired.add(tid)
818
+ else:
819
+ problems.append(f"{tid}: task file removed since {base}; removing a DONE, CLOSED or CANCELLED"
820
+ f" task requires all its receipts removed and --allow {tid}")
821
+ return retired, problems
822
+
823
+
824
+ def check_summary(counts, run_tests=False):
825
+ line = f"checked {counts['tasks']} tasks ({counts['claimed']} claimed DONE or CLOSED)"
826
+ if run_tests:
827
+ line += f"; ran {counts['tests']} declared tests"
828
+ return line
829
+
830
+
831
+ @s.read_session()
832
+ def check(root, staged=False, base=None, notes=None, allow=(), run_tests=False, counts=None):
833
+ """Problems that refuse the check.
834
+
835
+ Plain check reads every task. With --staged (the pre-commit hook) or --base REF (CI) it judges the
836
+ change: the tasks it touches and the tasks that depend on them. A task file that cannot be read is
837
+ a problem for that task only. With base, a change to what a task requires (its test, contract or
838
+ dependencies) fails unless the task is in allow; with run_tests, CI runs each claimed task's test.
839
+ """
840
+ notes = [] if notes is None else notes
841
+ counts = {} if counts is None else counts
842
+ errors = {}
843
+ all_records = records(root, staged, errors)
844
+ names = task_names(root, staged)
845
+ reference = base or ("HEAD" if staged else None)
846
+ if reference and s.git(root, "rev-parse", "--verify", "--quiet", f"{reference}^{{commit}}",
847
+ required=False).returncode:
848
+ if base:
849
+ raise s.Refused(f"base {base} is not in this clone; fetch it"
850
+ " (in GitHub Actions: actions/checkout with fetch-depth: 0)")
851
+ reference = None # the first commit: nothing to compare with, check everything
852
+ if reference:
853
+ selected, changed = scope(root, reference, staged, names, all_records, include_tests=bool(base))
854
+ else:
855
+ selected, changed = set(names), None
856
+ counts.update(tasks=len(selected), claimed=sum(r["status"] in FINISHED for tid, r in all_records.items()
857
+ if tid in selected), tests=0)
858
+ problems = [f"{tid}: {message.removeprefix(tid + ': ')}" for tid, message in sorted(errors.items())
859
+ if tid in selected]
860
+ stray = [path for path in s.files(root, "tasks", staged) if not path.endswith(".md")
861
+ and (changed is None or path in changed)]
862
+ problems += [f"{path}: only task files belong in tasks/; a file here is outside the code fingerprint,"
863
+ " so changes to it are never checked" for path in stray]
864
+ retired = set()
865
+ if base:
866
+ retired, removed_problems = removals(root, base, names, allow, staged)
867
+ problems += removed_problems + base_problems(root, base, staged, retired)
868
+ notes += [f"{tid}: task and all receipts removed (allowed)" for tid in sorted(retired)]
869
+ views = Views(root, all_records, staged)
870
+ # Include removed receipts and ledgers whose task file was also removed.
871
+ paths = set(s.receipt_paths(root, rev="HEAD")) | set(s.receipt_paths(root, staged))
872
+ tids = {s.receipt_task(path) for path in paths
873
+ if changed is None or path in changed or s.receipt_task(path) in selected} - {None}
874
+ for tid in sorted(tids):
875
+ if tid in retired:
876
+ continue
877
+ try:
878
+ s.entries(root, tid, staged)
879
+ except s.Refused as error:
880
+ problems.append(f"{tid}: {str(error).removeprefix(tid + ': ')}")
881
+ errors.setdefault(tid, str(error))
882
+ continue
883
+ if tid not in all_records and tid not in errors:
884
+ problems.append(f"{tid}: receipt ledger has no task record")
885
+ visiting, visited = set(), set()
886
+ cycles = dependency_cycles(all_records)
887
+ problems += [f"{tid}: {message}" for tid, message in sorted(cycles.items()) if tid in selected]
888
+
889
+ def walk(tid):
890
+ if tid in visiting:
891
+ return
892
+ if tid in visited:
893
+ return
894
+ visiting.add(tid)
895
+ for wait in s.dependencies(all_records[tid]):
896
+ if wait.startswith("task:"):
897
+ other = wait[5:]
898
+ if other not in all_records:
899
+ if other not in errors:
900
+ problems.append(f"{tid}: missing dependency {other}")
901
+ else:
902
+ walk(other)
903
+ visiting.remove(tid)
904
+ visited.add(tid)
905
+
906
+ for tid, record in sorted(all_records.items()):
907
+ if tid not in selected or tid in errors:
908
+ continue
909
+ try:
910
+ views[tid] # read the task's receipts and contract now, so their errors belong to this task
911
+ except s.Refused as error:
912
+ problems.append(f"{tid}: {str(error).removeprefix(tid + ': ')}")
913
+ continue
914
+ walk(tid)
915
+ # blocks is informational: it is checked for consistency but never enforced.
916
+ for other in record.get("blocks", []):
917
+ if other not in all_records and other not in errors:
918
+ problems.append(f"{tid}: blocks unknown task {other}")
919
+ elif other in all_records and tid in all_records[other].get("blocks", []) and tid < other:
920
+ problems.append(f"{tid} and {other} each say they block the other")
921
+ try:
922
+ debt = claim_debt(record, all_records, views)
923
+ found = (f"NOT QUITE {tid} says {record['status']} but owes: {', '.join(debt)}."
924
+ f" Details: workorder check {tid}") if debt else stale_claim(root, record, staged, base)
925
+ except s.Refused as error: # a dependency that cannot be read
926
+ found = f"{tid}: {error}"
927
+ merged = computed_merge(root, record, newest_implementation(s.entries(root, tid, staged)))
928
+ if merged:
929
+ notes.append(f"{tid}: {merge_line(merged)}")
930
+ if found:
931
+ problems.append(found)
932
+ if base:
933
+ if fields_at(root, tid, base) is None and record["status"] in FINISHED:
934
+ line = f"{tid} was created and claimed {record['status']} in the same change"
935
+ if tid in allow:
936
+ notes.append(line + " (definition allowed)")
937
+ else:
938
+ problems.append(line + f"; a reviewer accepts its definition with --allow {tid}")
939
+ changed_tests = test_file_changes(root, base, record, staged)
940
+ if changed_tests:
941
+ if tid in allow:
942
+ notes.append(changed_tests + " (allowed)")
943
+ else:
944
+ problems.append(changed_tests + f"; a reviewer accepts it with --allow {tid}")
945
+ for change in requirement_changes(root, base, record):
946
+ line = f"{tid}: {change} since {base}"
947
+ if tid in allow:
948
+ notes.append(line + " (allowed)")
949
+ else:
950
+ problems.append(f"{line}; a reviewer accepts it with --allow {tid}")
951
+ elif staged:
952
+ for change in requirement_changes(root, "HEAD", record):
953
+ notes.append(f"{tid}: {change} in this commit")
954
+ if run_tests and not found and record["status"] in FINISHED:
955
+ failed = run_declared_test(root, record, counts)
956
+ if failed:
957
+ problems.append(failed)
958
+ else:
959
+ notes.append(f"{tid}: its test passed when this check ran it")
960
+ return problems
961
+
962
+
963
+ def claim_debt(record, all_records, views):
964
+ """What a DONE or CLOSED status line claims but the evidence does not yet support."""
965
+ claimed = record["status"]
966
+ if claimed not in {"DONE", "CLOSED"}:
967
+ return []
968
+ _, done, delivery = views[record["id"]]
969
+ return done + (delivery if claimed == "CLOSED" else []) + waits(record, all_records, views)
970
+
971
+
972
+ def next_step(item, record, code_changed=False, root=None):
973
+ tid = record["id"]
974
+ command = record.get("test", "").strip() or "<your test command>"
975
+ if item == "implementation":
976
+ return f"commit the code, then: workorder receipt implemented --task {tid}"
977
+ if item == "a declared test":
978
+ return (f'add the command that proves it to tasks/{tid}.md, e.g. test: "python -m pytest",'
979
+ ' or test: any to accept any recorded command')
980
+ if item.startswith("implementation (commit"):
981
+ return ("fetch the full history; after a squash or rebase merge, record it again on the merged"
982
+ f" code: workorder receipt implemented --task {tid}")
983
+ if item == "evidence for the uncommitted code changes":
984
+ return (f"commit the code, then: workorder receipt implemented --task {tid}, then"
985
+ f" workorder receipt test --task {tid} -- {command}")
986
+ if item.startswith("a passing test on the code marked"):
987
+ return (f"workorder receipt implemented --task {tid}, then"
988
+ f" workorder receipt test --task {tid} -- {command}; or workorder renew --task {tid}")
989
+ if item.startswith("a passing test on"):
990
+ if code_changed:
991
+ return (f"workorder receipt implemented --task {tid}, then"
992
+ f" workorder receipt test --task {tid} -- {command}")
993
+ return f"workorder receipt test --task {tid} -- {command}"
994
+ if item.startswith("contract "):
995
+ return f"add qualifying evidence to {record['contract']}"
996
+ if item == "merge of the tested code":
997
+ push = unpushed_target(root, record) if root else None
998
+ if push:
999
+ return push
1000
+ return ("the merged code differs from the tested code or no matching merge was found; "
1001
+ f"run workorder renew --task {tid} on main, or record workorder receipt merged --task {tid}")
1002
+ if item.startswith("deployment read-back"):
1003
+ return (f"workorder receipt deployed --task {tid} --target <name>"
1004
+ " -- <command that prints the deployed commit>")
1005
+ if item.startswith("live read-back"):
1006
+ return (f"workorder receipt live --task {tid} --target <name>"
1007
+ " -- <command that prints the commit the live system reports>")
1008
+ if item.startswith("task:"):
1009
+ field = "depends_on" if item[5:] in record.get("depends_on", []) else "waits_on"
1010
+ return f"finish {item[5:]} first, or remove it from {field}"
1011
+ return f"remove {item} from waits_on once it is answered"
1012
+
1013
+
1014
+ def test_line(record, history):
1015
+ """Describe the newest test evidence for the newest implementation."""
1016
+ implemented = newest_implementation(history)
1017
+ if implemented is None:
1018
+ return None, "none counted: no implementation recorded"
1019
+ short = implemented["commit"][:7]
1020
+ if implemented["missing"]:
1021
+ return short, f"none counted: commit {short} is not in this clone"
1022
+ after = history[history.index(implemented) + 1:]
1023
+ runs = counting_runs(record, after, implemented)
1024
+ if runs:
1025
+ newest = runs[-1]
1026
+ where = newest["commit"][:7]
1027
+ if newest["commit"] != implemented["commit"]:
1028
+ where += f", same code as {short}"
1029
+ if newest["exit_code"] != 0:
1030
+ latest = f"FAIL (exit {newest['exit_code']}, {where})"
1031
+ elif not newest["valid"]:
1032
+ latest = f"not counted: files or HEAD changed while it ran ({where})"
1033
+ else:
1034
+ return short, f"PASS (exit 0, {where})"
1035
+ if any(e["exit_code"] == 0 and e["valid"] for e in runs):
1036
+ return short, f"{latest}; an earlier run passed, but the latest run decides"
1037
+ return short, latest
1038
+ if declared_test(record) and any(e["kind"] == "test" and e["code"] == implemented["code"] for e in after):
1039
+ return short, f"no run of the task's test for this commit (test: {record['test'].strip()})"
1040
+ tests = [e for e in history if e["kind"] == "test"]
1041
+ if not tests:
1042
+ return short, "no passing test for this commit"
1043
+ if tests[-1]["code"] == implemented["code"]:
1044
+ return short, "no passing test for this commit; the last test was recorded before the implementation"
1045
+ return short, f"no passing test for this commit; the last test ran on {tests[-1]['commit'][:7]}"
1046
+
1047
+
1048
+ def uncounted(root, record, history):
1049
+ """Why the newest receipt, though recorded, cannot count toward the verdict; None if it can.
1050
+
1051
+ Failed or invalid runs are reported by their exit code and are not repeated here.
1052
+ """
1053
+ item, before = history[-1], history[:-1]
1054
+ kind = item["kind"]
1055
+ if kind == "implemented" or (kind in {"test", "deployed", "live"}
1056
+ and (item["exit_code"] != 0 or not item["valid"])):
1057
+ return None
1058
+ tid = record["id"]
1059
+ implemented = newest_implementation(before)
1060
+ if kind in {"merged", "deployed", "live"}:
1061
+ needed = {"merged": {"repo", "live"}, "deployed": {"live"}, "live": {"live"}}[kind]
1062
+ if record["ships"] not in needed:
1063
+ return f"{tid} has ships: {record['ships']}, so a {kind} receipt is not part of its evidence"
1064
+ if implemented is None:
1065
+ return f"no implementation is recorded yet; run workorder receipt implemented --task {tid} first"
1066
+ short = implemented["commit"][:7]
1067
+ if implemented["missing"]:
1068
+ return (f"the implementation names commit {short}, which is not in this clone; run"
1069
+ f" workorder receipt implemented --task {tid} again")
1070
+ if kind == "test":
1071
+ if item["code"] != implemented["code"]:
1072
+ return (f"this code differs from the implemented commit {short}; run"
1073
+ f" workorder receipt implemented --task {tid} first")
1074
+ declared = declared_test(record)
1075
+ if declared is not None and item["command"] != declared:
1076
+ return f"{tid} declares its test as: {record['test'].strip()}; only that command counts"
1077
+ return None
1078
+ if kind == "merged" and not carries(root, implemented, item):
1079
+ return (f"{item['ref']} on origin neither contains the implemented commit {short} nor holds exactly its"
1080
+ f" code; after a squash merge, record implemented and test again on the merged code")
1081
+ computed = computed_merge(root, record, implemented)
1082
+ if kind == "deployed" and not delivered_code(root, implemented, item, computed):
1083
+ return f"the deployed commit neither contains the implemented commit {short} nor holds exactly its code"
1084
+ current = before[before.index(implemented) + 1:]
1085
+ merges = [i for i, e in enumerate(current) if e["kind"] == "merged" and carries(root, implemented, e)]
1086
+ if kind == "deployed" and not merges and not computed:
1087
+ return (f"no merge of the tested code is recorded since the implementation;"
1088
+ f" run workorder receipt merged --task {tid} first")
1089
+ if kind == "live":
1090
+ after_merge = current if computed else current[merges[-1] + 1:] if merges else []
1091
+ deployed = [e for e in after_merge if e["kind"] == "deployed"]
1092
+ if not deployed:
1093
+ return "no deployment read-back is recorded after the merge"
1094
+ if deployed[-1]["exit_code"] != 0 or not deployed[-1]["valid"]:
1095
+ return "the latest deployment read-back did not pass"
1096
+ if deployed[-1]["commit"] != item["commit"] or deployed[-1]["target"] != item["target"]:
1097
+ return (f"it does not match the latest deployment read-back"
1098
+ f" ({deployed[-1]['target']} on {deployed[-1]['commit'][:7]})")
1099
+ return None
1100
+
1101
+
1102
+ def timeline(root, record, history):
1103
+ """One line per receipt, oldest first: when, what, by whom."""
1104
+ lines = []
1105
+ for item in history:
1106
+ when = item["at"][:16].replace("T", " ")
1107
+ commit = item["commit"][:7]
1108
+ kind = item["kind"]
1109
+ if kind == "implemented":
1110
+ what = f"implemented {commit}"
1111
+ elif kind == "test":
1112
+ result = ("PASS" if item["exit_code"] == 0 and item["valid"]
1113
+ else f"FAIL (exit {item['exit_code']})" if item["exit_code"] != 0 else "not counted")
1114
+ what = f"test {result}: {s.join_command(item['command'])} on {commit}"
1115
+ elif kind == "merged":
1116
+ what = f"merged: {item.get('ref', '')} at {commit}"
1117
+ else:
1118
+ what = f"{kind} read-back {item.get('target', '')}: {'ok' if item['valid'] else 'not valid'} ({commit})"
1119
+ if item["missing"]:
1120
+ what += " (commit not in this clone)"
1121
+ lines.append(f" {when} {what} ({item['who']})")
1122
+ computed = computed_merge(root, record, newest_implementation(history))
1123
+ if computed:
1124
+ lines.append(" " + merge_line(computed))
1125
+ return lines
1126
+
1127
+
1128
+ @s.read_session()
1129
+ def record_lines(root, tid):
1130
+ """The task as a record to come back to: what it is, where it stands, what happened, what is next."""
1131
+ errors = {}
1132
+ all_records = records(root, errors=errors)
1133
+ if tid in errors:
1134
+ raise s.Refused(errors[tid])
1135
+ if tid not in all_records:
1136
+ raise s.Refused(f"no task record tasks/{tid}.md")
1137
+ record = all_records[tid]
1138
+ views = Views(root, all_records)
1139
+ computed, done, delivery = views[tid]
1140
+ open_waits = waits(record, all_records, views)
1141
+ if computed in FINISHED and open_waits:
1142
+ computed = "BLOCKED"
1143
+ history = s.entries(root, tid)
1144
+ recognise_squashed(root, tid, history)
1145
+ stale = [] if done or delivery else (["a passing test on the code marked " + record["status"]]
1146
+ if stale_claim(root, record) else [])
1147
+ if stale and computed in FINISHED:
1148
+ computed = "IN_PROGRESS"
1149
+ lines = [f"{tid} recorded {record['status']}; computed {computed}",
1150
+ "still owes: " + owes(record, stale + done + open_waits, delivery)]
1151
+ if record["status"] not in FINISHED and computed in FINISHED:
1152
+ # Found in the handoff trial: "computed CLOSED, owes nothing" on a half-done task misleads.
1153
+ lines.append("note: " + ACCEPTANCE_NOTE)
1154
+ if s.dependencies(record):
1155
+ lines.append("waits_on: " + ", ".join(s.dependencies(record)))
1156
+ lines += ["", f"title: {record['title']}", f"owner: {record['owner']}"]
1157
+ for key in ("mission", "summary", "next"):
1158
+ if record.get(key, "").strip():
1159
+ lines.append(f"{key + ':':<9} {' '.join(record[key].split())}")
1160
+ lines.append(f"test: {record.get('test', '').strip() or '(none declared)'}")
1161
+ # The task's own words: every section of the body except Progress, which follows the history.
1162
+ sections = s.task_body_sections(s.read_text(root, f"tasks/{tid}.md"))
1163
+ for heading, body in sections:
1164
+ if heading in (None, "Progress"):
1165
+ continue
1166
+ text = [line.rstrip() for line in body if not line.strip().startswith("<!--")]
1167
+ while text and not text[0].strip():
1168
+ text.pop(0)
1169
+ while text and not text[-1].strip():
1170
+ text.pop()
1171
+ lines += ["", f"{heading.lower()}:"] + ([f" {line}" if line.strip() else "" for line in text]
1172
+ or [" (empty)"])
1173
+ lines += ["", "history:"] + (timeline(root, record, history) or [" (no receipts yet)"])
1174
+ progress = [line.strip() for heading, body in sections
1175
+ if heading == "Progress" for line in body if line.strip() and not line.strip().startswith("<!--")]
1176
+ lines += ["", "progress:"] + ([f" {line}" for line in progress] or [" (no notes yet)"])
1177
+ owed = stale + done + delivery + open_waits
1178
+ if owed:
1179
+ lines += ["", f"next step: {next_step(owed[0], record, root=root)}"]
1180
+ return lines
1181
+
1182
+
1183
+ @s.read_session()
1184
+ def explain(root, tid):
1185
+ """Lines describing one task's claim and evidence, and whether the claim stands."""
1186
+ errors = {}
1187
+ all_records = records(root, errors=errors)
1188
+ if tid in errors:
1189
+ raise s.Refused(errors[tid])
1190
+ if tid not in all_records:
1191
+ raise s.Refused(f"no task record tasks/{tid}.md")
1192
+ views = Views(root, all_records)
1193
+ record = all_records[tid]
1194
+ computed, done, delivery = views[tid]
1195
+ debt = claim_debt(record, all_records, views)
1196
+ history = s.entries(root, tid)
1197
+ recognise_squashed(root, tid, history)
1198
+ commit, test = test_line(record, history)
1199
+ implemented = newest_implementation(history)
1200
+ runs = (counting_runs(record, history[history.index(implemented) + 1:], implemented)
1201
+ if implemented and not implemented["missing"] else [])
1202
+ stale = None if debt else stale_claim(root, record)
1203
+ if stale and "uncommitted code changes" in stale:
1204
+ debt = ["evidence for the uncommitted code changes"]
1205
+ elif stale:
1206
+ debt = [f"a passing test on the code marked {record['status']} (it differs from {commit})"]
1207
+ code_changed = implemented is not None and s.code_digest(root, s.head(root)) != implemented["code"]
1208
+ claimed = record["status"]
1209
+ if computed in FINISHED and waits(record, all_records, views):
1210
+ computed = "BLOCKED" # the evidence is in, but a dependency is still open
1211
+ if s.dirty_paths(root):
1212
+ code_note = "uncommitted code changes are not covered by any receipt"
1213
+ else:
1214
+ code_note = None
1215
+ lines = [f"NOT QUITE {tid}" if debt else f"{claimed} {tid}", "",
1216
+ f" Claimed: {claimed}", f" Computed: {computed}",
1217
+ f" Commit: {commit or 'none recorded'}", f" Test: {test}"]
1218
+ merged = computed_merge(root, record, implemented)
1219
+ if merged:
1220
+ lines.append(" Merge: " + merge_line(merged))
1221
+ if runs:
1222
+ lines.append(f" Command: {s.join_command(runs[-1]['command'])}")
1223
+ if code_changed:
1224
+ lines.append(f" Note: the code has changed since {commit}; this verdict is about {commit}")
1225
+ if code_note:
1226
+ lines.append(f" Note: {code_note}")
1227
+ if not debt and claimed not in FINISHED and computed in FINISHED:
1228
+ lines.append(f" Note: {ACCEPTANCE_NOTE}")
1229
+ if debt:
1230
+ lines += [f" Missing: {item}" for item in debt]
1231
+ lines += [f" Next: {next_step(item, record, code_changed, root)}" for item in debt]
1232
+ result = "NOT DONE" if done or claimed == "DONE" else "NOT CLOSED"
1233
+ lines += ["", f" Result: {result}. The status says {claimed}; the evidence above does not support it."]
1234
+ else:
1235
+ owed = done + delivery
1236
+ if owed:
1237
+ lines.append(f" Owes: {', '.join(owed)}")
1238
+ lines += ["", f" Result: {'claim supported' if claimed in {'DONE', 'CLOSED'} else 'no completion claimed'}"]
1239
+ return lines, bool(debt)
1240
+
1241
+
1242
+ @s.read_session()
1243
+ def ready(root):
1244
+ # A refused DONE or CLOSED claim is shown on its own task; it does not hide the rest of the work.
1245
+ # Cycles belong to their participants; unrelated work remains visible.
1246
+ issues = check(root)
1247
+ unreadable = {}
1248
+ records(root, errors=unreadable)
1249
+ refused = {issue.split()[2] for issue in issues if issue.startswith("NOT QUITE ")}
1250
+ structural = [issue for issue in issues if not issue.startswith("NOT QUITE ")
1251
+ and issue.split(":")[0] not in unreadable and not issue.startswith("tasks/")
1252
+ and ": dependency cycle:" not in issue]
1253
+ if structural:
1254
+ raise s.Refused("; ".join(structural))
1255
+ errors = {}
1256
+ all_records = records(root, errors=errors)
1257
+ cycles = dependency_cycles(all_records)
1258
+ views = Views(root, all_records)
1259
+ lines = [f"{tid} cannot be read: {message.removeprefix(tid + ': ')}" for tid, message in sorted(errors.items())]
1260
+ upstream = {}
1261
+ try:
1262
+ claims = s.active_claims(root, upstream) if s.has_origin(root) else {}
1263
+ except s.Refused:
1264
+ claims = {}
1265
+ upstream = {}
1266
+ lines.append("(claims not shown: origin could not be reached)")
1267
+ for tid, record in sorted(all_records.items()):
1268
+ if record["status"] == "CANCELLED":
1269
+ continue
1270
+ blocked = waits(record, all_records, views)
1271
+ if record["status"] == "BLOCKED":
1272
+ blocked = ["status BLOCKED"] + blocked
1273
+ claimed = record["status"] in FINISHED
1274
+ if claimed and views[tid][0] == "CLOSED" and not blocked and tid not in refused:
1275
+ continue
1276
+ held = claims.get(tid)
1277
+ if tid in upstream:
1278
+ state = f"finished on {upstream[tid]['ref']}; pull to update"
1279
+ elif tid in cycles:
1280
+ state = cycles[tid]
1281
+ elif tid in refused:
1282
+ state = f"says {record['status']}, which the evidence does not support: workorder check {tid}"
1283
+ elif blocked:
1284
+ state = "blocked: " + ", ".join(blocked)
1285
+ elif held and not held["released"]:
1286
+ state = f"held by {held['who']} since {held['at']}"
1287
+ elif claimed and views[tid][0] == "DONE":
1288
+ state = "waiting for delivery: " + ", ".join(views[tid][2])
1289
+ else:
1290
+ state = "free"
1291
+ lines.append(f"{tid} {state}")
1292
+ return lines