lab-kit-cli 1.14.0__tar.gz → 1.16.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.
Files changed (50) hide show
  1. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/AGENTS.md +2 -1
  2. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/CHANGELOG.md +40 -0
  3. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/PKG-INFO +2 -2
  4. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/README.md +1 -1
  5. lab_kit_cli-1.16.0/agents/page-reviewer.md +42 -0
  6. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/docs/model.md +89 -6
  7. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/method/METHOD.md +5 -2
  8. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/pyproject.toml +1 -1
  9. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/skills/lab-mission/SKILL.md +3 -1
  10. lab_kit_cli-1.16.0/skills/lab-pages/SKILL.md +136 -0
  11. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/skills/lab-review/SKILL.md +5 -0
  12. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/skills/lab-work/SKILL.md +7 -1
  13. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/__init__.py +1 -1
  14. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/checks.py +8 -1
  15. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/cli.py +41 -5
  16. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/history.py +8 -0
  17. lab_kit_cli-1.16.0/src/lab_kit/pages.py +518 -0
  18. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/record.py +12 -0
  19. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/views.py +2 -1
  20. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/write.py +24 -6
  21. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_held.py +61 -0
  22. lab_kit_cli-1.16.0/tests/test_pages.py +245 -0
  23. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/.github/workflows/ci.yml +0 -0
  24. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/.github/workflows/policy.yml +0 -0
  25. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/.github/workflows/release.yml +0 -0
  26. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/.gitignore +0 -0
  27. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/CLAUDE.md +0 -0
  28. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/CONTRIBUTING.md +0 -0
  29. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/LICENSE +0 -0
  30. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/agents/reviewer.md +0 -0
  31. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/skills/lab-set-up/SKILL.md +0 -0
  32. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/skills/lab-talk/SKILL.md +0 -0
  33. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/runs.py +0 -0
  34. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/site.py +0 -0
  35. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/storylines.py +0 -0
  36. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/supervise.py +0 -0
  37. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_drafts.py +0 -0
  38. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_flow.py +0 -0
  39. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_integrity.py +0 -0
  40. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_mission.py +0 -0
  41. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_needs.py +0 -0
  42. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_order.py +0 -0
  43. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_parked.py +0 -0
  44. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_refusals.py +0 -0
  45. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_site.py +0 -0
  46. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_states.py +0 -0
  47. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_storylines.py +0 -0
  48. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_vocabulary.py +0 -0
  49. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_wording.py +0 -0
  50. {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tools/import_run.py +0 -0
@@ -22,7 +22,8 @@ The tests build a small lab with the command itself and take it from a question
22
22
 
23
23
  - The model wins. Change `docs/model.md` first, then the code, the method and the skills, in the same change.
24
24
  - A rule a command holds is in `docs/model.md`, in the code and in a test together, with a case that it refuses.
25
- - A command validates before it writes, and says what it wrote. No command writes a computed view into a lab.
25
+ - A command validates before it writes, and says what it wrote. No command writes a computed view into a lab. The one exception is `lab pages terms`,
26
+ which copies each glossary definition into the links to it, as hover text that `lab check` otherwise refuses.
26
27
  - Never `git add -A`. Add the files you touched.
27
28
 
28
29
  ## Content and gate
@@ -1,5 +1,45 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.16.0
4
+
5
+ - **The library's pages are held to the record, when the library keeps `pages.toml`.** The question cards are the
6
+ facts, and no page repeats one. `pages.toml` gives every page a kind: storyline (the argument, revised when a
7
+ question it cites is answered), stable (how the method works, only corrected), reference (the trail, the
8
+ appendices, the maps) or retiring. `lab check` then holds that every page has a kind; a number quoted in a
9
+ `data-result="<experiment>:<result>"` element is the card's, from reviewed results; a storyline page tagged
10
+ `<meta name="numbers" content="tagged">` shows no other number; no page but a retiring one uses a phrase
11
+ `pages.toml` drops or claims to be first without "to our knowledge"; every storyline and stable page matches a
12
+ page reviewer's recorded pass (`page-reviews.tsv`, by a fingerprint of the page, so a page is read again only
13
+ when its text changes); every question answered since `since` records that its answer reached its pages
14
+ (`answers-in-pages.tsv`); each active storyline page links every storyline page; and a link to a glossary term
15
+ names a term the glossary has and carries its definition as hover text.
16
+ - `lab pages` lists the pages and whether each was passed as it stands; `lab pages check` runs only the page check;
17
+ `lab pages cites <id>` lists the storyline pages to revise when a question is answered; `lab pages passed` and
18
+ `lab pages answered` write the two records; `lab pages terms` writes the hover text from the glossary. `lab now`
19
+ lists the answers whose pages lag and the pages waiting for a reviewer, and `lab answer` says what comes next.
20
+ - A new skill, `lab-pages`, and a new role, `page-reviewer`, with fix rounds that converge: the same reviewer reads
21
+ only what changed, and passes from the third reading once nothing blocks. Method rule 8, lab-work and
22
+ lab-mission say when they apply.
23
+ - A lab without `pages.toml` is unchanged. Upgrading: run `lab init`, which installs the new skill and role. It
24
+ replaces any skill or role of the same name the lab wrote itself (`.agents/skills/lab-pages`,
25
+ `.agents/agents/page-reviewer.md`): move what is local in them to the lab's AGENTS.md first. A new lab's
26
+ `.gitattributes` unions the two page records, which sessions add rows to side by side. To opt in, write `pages.toml` with `since` and a kind for every page, then have a page reviewer pass each storyline and
27
+ stable page.
28
+
29
+ ## 1.15.0
30
+
31
+ - **A later results review can supersede an earlier one, by name.** A reviewed row that had to be read another
32
+ way, to the same result (a command that read the run by a fixed path, rewritten to read `$RUN` so the gate
33
+ passes), was held as it was: `lab check` said "a row that a review had passed in ... is gone or changed", a
34
+ second passing review did not lift it, and putting the old row back brought back the failure it was changed
35
+ to fix. `lab review <experiment> results pass "<why>" --supersedes <of>` now names the earlier passing results
36
+ review by its `of`; it ends the note with "Supersedes the results review of <of>.", and the rows that review
37
+ read are held no more once it is committed together with the rows it read, which are held in their place. A review that does not name the earlier one
38
+ still supersedes nothing, and a note may not end with that sentence by hand. `lab review` refuses it on a plan or a failing review, for an `of` no earlier passing
39
+ results review has, and when the earlier review read the rows as they are now; `lab check` refuses a note that
40
+ names no earlier passing results review of other rows.
41
+ - The skill `lab-review` changed: run `lab init` in a lab after upgrading.
42
+
3
43
  ## 1.14.0
4
44
 
5
45
  - **A home map has Current storylines.** When `lab.toml` names active storylines, one of the library's home
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.14.0
3
+ Version: 1.16.0
4
4
  Summary: A research lab's record, its method, and the command that keeps both.
5
5
  Project-URL: Homepage, https://github.com/pierg/lab-kit
6
6
  Project-URL: Issues, https://github.com/pierg/lab-kit/issues
@@ -76,4 +76,4 @@ where folio serves the lab, which brings `folio-kb` 0.5.0 or later, and list `la
76
76
 
77
77
  - [docs/model.md](https://github.com/pierg/lab-kit/blob/main/docs/model.md): the contract. What you read, how a number becomes a result, who decides, the commands, the files.
78
78
  - [method/METHOD.md](https://github.com/pierg/lab-kit/blob/main/method/METHOD.md): the eight rules every lab keeps.
79
- - [skills/](https://github.com/pierg/lab-kit/blob/main/skills/): lab-set-up, lab-work, lab-review, lab-talk and lab-mission. [agents/](https://github.com/pierg/lab-kit/blob/main/agents/): the reviewer.
79
+ - [skills/](https://github.com/pierg/lab-kit/blob/main/skills/): lab-set-up, lab-work, lab-review, lab-talk, lab-mission and lab-pages. [agents/](https://github.com/pierg/lab-kit/blob/main/agents/): the reviewer and the page reviewer.
@@ -57,4 +57,4 @@ where folio serves the lab, which brings `folio-kb` 0.5.0 or later, and list `la
57
57
 
58
58
  - [docs/model.md](docs/model.md): the contract. What you read, how a number becomes a result, who decides, the commands, the files.
59
59
  - [method/METHOD.md](method/METHOD.md): the eight rules every lab keeps.
60
- - [skills/](skills/): lab-set-up, lab-work, lab-review, lab-talk and lab-mission. [agents/](agents/): the reviewer.
60
+ - [skills/](skills/): lab-set-up, lab-work, lab-review, lab-talk, lab-mission and lab-pages. [agents/](agents/): the reviewer and the page reviewer.
@@ -0,0 +1,42 @@
1
+ ---
2
+ name: page-reviewer
3
+ description: >-
4
+ Reads one library page with fresh context and checks every number and claim against the question cards, the
5
+ units and the words the lab uses, and how the page reads. Use for every page the lab-pages skill writes or
6
+ revises. Give it only the page's path and the ids it cites. Never use it in the session that wrote the page.
7
+ ---
8
+
9
+ You review one page of the library, under its `content/` folder. You did not write it. You need to run commands
10
+ (`lab show`, `lab pages check`, `lab pages passed`): if you cannot, say so at once and stop, without a verdict, so
11
+ the writer starts a reviewer that can. A reading without them is not a reading, and is not counted. Follow the lab-pages skill
12
+ (`.agents/skills/lab-pages/SKILL.md`, How a page reads) and the lab's own writing rules, which its AGENTS.md names.
13
+
14
+ 1. Read the page top to bottom as a reader who does not know the lab. Note every name used before it is defined
15
+ (a term linked to the glossary at its first use counts as defined), every term the page defines in its own
16
+ words when `GLOSSARY.md` already has it (it should link instead), every glossary term whose first use is not
17
+ linked, every number without its unit or without "k of n", and every figure that comes before the words that
18
+ introduce it.
19
+ 2. For every number and claim, open the card it rests on (`lab show <id>`) and check it: the value, what n counts,
20
+ the limit the card states, and whether the step's results review passed. A claim no card supports is a fault.
21
+ 3. Check the words: the glossary's terms as it defines them, no phrase `pages.toml` drops, "first" only as "to our
22
+ knowledge" with the closest published work named, and nothing from a step still running given as a result.
23
+ 4. Run `lab pages check`. Until you record a pass, it reports the page under review as "no page reviewer has
24
+ passed it"; that one line is expected. Any other line about the page is a fault.
25
+
26
+ Return pass, or fail with a numbered list of fixes, each naming the sentence and what the card says, and marked
27
+ **blocks** or **nit**. Everything steps 1 to 4 find blocks, and so does any `lab pages check` line about the page other
28
+ than the expected one; a nit is wording only.
29
+
30
+ Each time you read a page, keep a copy of it in your scratch folder, outside the repository and the store. When the
31
+ writer comes back after a fail, find what changed yourself, by diffing the page against that copy; do not rely on
32
+ the writer's list. For each changed spot, run steps 2 to 4 again, and re-check the page-wide order of step 1 (each
33
+ term defined or linked at its first use, each figure after its words). If anything changed that you did not ask
34
+ for, read the whole page again. Rounds are counted per page: nits may still be listed as fixes in the first and
35
+ second readings; from the third reading of the page on (the first reading plus two fix rounds), pass once nothing
36
+ blocks, and list the remaining nits briefly in your reply. If you are a fresh reviewer taking over a page, read the
37
+ whole page, with the earlier lists of fixes and the number of readings so far in hand; the count carries over.
38
+
39
+ On a pass, and only then, record it: `lab pages passed <page> "<one line: what you checked>"` (the page is its path
40
+ under `content/`, such as `entries/the-error-halves`). That line in `page-reviews.tsv` is the one thing you write
41
+ in the lab or the library; the only other file you write is your copy of the page in your scratch folder. The lab's
42
+ AGENTS.md may name places you never open; keep to them.
@@ -199,6 +199,20 @@ Each arrow is a command that refuses when the step before it is missing. You see
199
199
  problem `lab check` reports at every step: a different result is a new experiment. A review is
200
200
  bound to the rows it read by its `of`, so only those are held: a draft row committed after a
201
201
  review, which that review never read, may still be corrected before the next review reads it.
202
+ **A review that supersedes another.** A reviewed row that must be read another way, to the same
203
+ result (a command that read the run by a fixed path and now reads `$RUN`), is not a new
204
+ experiment. A later results review that passes the new rows says so by name: `lab review
205
+ <experiment> results pass "<why the rows changed, and what was re-read>" --supersedes <of>`, where
206
+ `<of>` is the earlier passing results review's `of` (eight to sixteen of its first hex digits).
207
+ The command ends the note with "Supersedes the results review of <of>.". Once that review is
208
+ committed together with the rows it read, the rows the earlier review read are held no more, and
209
+ the new rows are held in their place; until then it supersedes nothing. A note cannot end with that
210
+ sentence except through `--supersedes`.
211
+ A later review that passes changed rows without naming the earlier one supersedes nothing, so the
212
+ old rows are still held. `lab review` refuses `--supersedes` on a plan review or a failing one, an
213
+ `of` that no earlier passing results review has, and a review that read the rows as they are now;
214
+ `lab check` refuses a note that names a review that is not an earlier passing results review of
215
+ other rows.
202
216
  **The history that is read.** The check reads the history of the record under the lab's root as
203
217
  that root is now. Moving the lab's root inside its repository, or to another repository, starts
204
218
  again what is held: what was committed under the old root is not compared. And it needs the
@@ -409,6 +423,25 @@ parked or dropped is in either, and a goal, a question or a step sits in one row
409
423
  before a result about something it lists under included or open is noted. `lab now` lists each storyline's
410
424
  open experiments, and the live steps no storyline lists, by themselves or by their question or goal.
411
425
 
426
+ **Pages: the cards are the facts, and every page is passed as it stands.** Above the record, the library's pages
427
+ argue and explain; they never repeat a question card. A lab may opt in to hold its pages to the record by giving
428
+ its library a `pages.toml` (section 9), which gives every page a **kind**. A **storyline** page carries the
429
+ argument and is revised when a question it cites is answered. A **stable** page explains how the method works, or
430
+ the words and objects every page leans on, and is changed only to correct it. A **reference** page holds the full
431
+ trail, the appendices, the guide and the maps. A **retiring** page waits to be merged into another and retired.
432
+ The session that answers a question revises, in the same sitting, the storyline pages that cite it, and a **page
433
+ reviewer** who did not write them reads each against the cards and records a pass with a fingerprint of the page
434
+ as it read it. A page is read again only when its text changes. Then `lab check` holds that every page under the
435
+ sections the lab lists has a kind; a number a page quotes inside a `data-result` element is the value its card gives
436
+ that result, from results that were reviewed and not replaced or dropped; a storyline page says its numbers are
437
+ tagged and shows no other; no page but a retiring one uses a phrase the lab has dropped, or claims to be first
438
+ without "to our knowledge"; every
439
+ storyline and stable page matches a recorded pass; every question answered since the day the lab names has a row
440
+ saying its answer reached its pages; each active storyline page links every storyline page; and a link to a
441
+ glossary term names a term the glossary has, with its definition, as it now stands, as hover text. `lab now` lists
442
+ the answers that have not reached their pages and the pages waiting for a reviewer. A lab without `pages.toml` has
443
+ none of this.
444
+
412
445
  ## 5. What the agent uses
413
446
 
414
447
  - **To look:** `lab now`, `lab show <id or path>`, `lab brief <question>`, `lab since`, `lab define <term>`. Each shows one level,
@@ -429,10 +462,17 @@ open experiments, and the live steps no storyline lists, by themselves or by the
429
462
  `--evidence <folder>` writes an amendment instead (below, under `runs.tsv`). Where the system gives no way to tell that a process is the run's, nothing is
430
463
  stopped and the command says so. `lab runs lost` records a run that started and whose folder is
431
464
  gone for good.
432
- - **Once:** `lab init`. Run again, it restores the method, the skills and the reviewer role.
465
+ - **Once:** `lab init`. Run again, it restores the method, the skills and the reviewer roles.
433
466
  - **To carry out a decision:** `lab mission` (below).
467
+ - **For the library's pages,** when it keeps `pages.toml`: `lab pages` lists every page with its kind and
468
+ whether a page reviewer passed it as it now stands; `lab pages check` runs only what `lab check` holds about the
469
+ pages; `lab pages cites <id>` lists the storyline pages that cite a question or a step; `lab pages passed <page>
470
+ "<note>"` is the page reviewer's pass; `lab pages answered <question> "<note>"` records that an answer reached its
471
+ pages, and is refused while a storyline or stable page waits for a pass; `lab pages terms` writes each glossary
472
+ link's hover text from `GLOSSARY.md`. It is the one command that writes into a page, and it writes only what
473
+ `lab check` would otherwise refuse: the definition, as the glossary gives it, in the link's `title`.
434
474
 
435
- That is sixteen commands. `lab --help` lists them the same way.
475
+ That is seventeen commands. `lab --help` lists them the same way.
436
476
 
437
477
  **A mission.** A settled decision says what is done and why: the questions, the order, the resources. Carrying
438
478
  it out can take many sessions, each starting sessions or runs of its own and watching them, and a session that
@@ -478,9 +518,10 @@ since when), and the time of the last recorded activity. A `doing` line stands u
478
518
  about the same card, or the card being finished, ends it. When there is none, the page says that
479
519
  nobody is on anything and names the next step. Nothing is inferred from a session being open.
480
520
 
481
- Five skills: `lab-set-up`, `lab-work`, `lab-review`, `lab-talk` (tell you where things stand, bring
482
- a decision to you, record what was decided), and `lab-mission` (save, launch, resume and close a mission). One
483
- role: the reviewer.
521
+ Six skills: `lab-set-up`, `lab-work`, `lab-review`, `lab-talk` (tell you where things stand, bring
522
+ a decision to you, record what was decided), `lab-mission` (save, launch, resume and close a mission), and
523
+ `lab-pages` (revise and review the library's pages when it keeps `pages.toml`). Two roles: the reviewer, and the
524
+ page reviewer.
484
525
 
485
526
  Eight rules:
486
527
 
@@ -822,7 +863,8 @@ with each quote inside written twice, as a spreadsheet writes it, is read withou
822
863
  quote is a character like any other.
823
864
 
824
865
  **`reviews.tsv`** is written by `lab review`: `date`, `stage` (plan, results), `verdict` (pass, fail),
825
- `by`, `of` (a hash of what was read), `note`.
866
+ `by`, `of` (a hash of what was read), `note`. A results review written with `--supersedes` ends its
867
+ note with "Supersedes the results review of <of>." (section 3, Reviewed rows stay).
826
868
 
827
869
  **`resources.toml`** has one table per resource: `what`, `key` (where it is kept), `rules` (a list of
828
870
  sentences), `retired` (why, once it is no longer used), and for a metered resource `unit`, `granted`,
@@ -973,6 +1015,47 @@ is the one place those pages have on a map; the overview and a retired storyline
973
1015
  headings. The library has one such section, and no map that is not a home map has one. A lab without
974
1016
  `[storylines]` has none of this.
975
1017
 
1018
+ **Pages.** A library that keeps `pages.toml` (beside `folio.yaml`) gives every page a kind, and says how the
1019
+ page check reads its pages:
1020
+
1021
+ ```
1022
+ since = "2026-11-21" # every question answered from this day on records that it reached its pages
1023
+ dropped = ["law of everything", "breakthrough"] # phrases no page but a retiring one uses, as case-blind regular expressions
1024
+ names = ["Model", "Trial"] # words after which a number is a name, not a result ("Model 4", "Trial 2")
1025
+ sections = ["entries", "concepts", "guides"] # the folders under content/ whose pages each need a kind (these by default)
1026
+ first = ["for the first time", "first[- ]ever", "never before"] # claims to be first, which say "to our knowledge"
1027
+
1028
+ [pages]
1029
+ "index" = "reference"
1030
+ "entries/the-error-halves" = "storyline"
1031
+ "concepts/error-ratio" = "stable"
1032
+ ```
1033
+
1034
+ A page is a path under `content/`: a folder, whose HTML files are all the page, or a file `<page>.html` (the home
1035
+ page, a map), never with `..`. `since` is required, a date; `dropped` is empty and `sections` is as shown unless set;
1036
+ `first` lists the claims to be first that a sentence makes only with "to our knowledge", and by default holds "for
1037
+ the first time", "first-ever", "never before", "had not been done" and "never been done", "shown", "proved" or
1038
+ "measured"; `[]` turns it off. Every folder under a listed section has a kind, and every page `[pages]` lists is
1039
+ there. A number quotes a result in an element `data-result="<experiment>:<result>"`, whose first number is compared
1040
+ with the result's value, rounded half up to as many decimals as the page shows, or with the number the card itself
1041
+ shows (`reads`: a share as a percentage, a difference in points); names joined by `+` are summed and by `*`
1042
+ multiplied, and a single result that reads as a percent or in points is compared as one, never added to others. The
1043
+ result is usable: its experiment's results were reviewed, and it was not replaced or dropped. An element whose end
1044
+ tag is left out ends where HTML ends it, with its parent; one still open where the page ends is refused. Each HTML
1045
+ file of a storyline page carries `<meta name="numbers" content="tagged">` and shows a number only in such an element, in an element
1046
+ marked `data-plain`, in `<code>`, a `<figure>` or an `<svg>`, in a link to a card (`/lab/<id>/`), or as the total
1047
+ in "k of n", a year, or right after one of `names` or of Result, Step, Figure, Table, Section, Part and Version, in
1048
+ any case. A link to a glossary term is `<a class="term" href="/lab/glossary/#<anchor>" title="<definition>">`, the
1049
+ anchor being the entry's heading, or a name under its `- also:`, in lower case with spaces as hyphens.
1050
+
1051
+ Two records sit beside `pages.toml`, each a TSV whose rows are only added, through the commands:
1052
+ `page-reviews.tsv` (`page`, `fingerprint`, `date`, `note`), one row per pass, and `answers-in-pages.tsv`
1053
+ (`question`, `answered`, `date`, `note`), one row per answer that reached its pages, keyed by the question and the
1054
+ date on its `answered:` line. A page's fingerprint is the first 16 hex digits of the SHA-256 of its HTML files, in
1055
+ path order, each as its path under `content/`, a zero byte, its bytes with every glossary link's `title` left out,
1056
+ and a zero byte. A storyline or stable page whose fingerprint no row of `page-reviews.tsv` holds waits for a page
1057
+ reviewer; a reference page never read is listed by `lab pages`, and not held.
1058
+
976
1059
  **Worked-out states.** A goal is open until `reached: true` makes it done or `dropped:` drops it. A
977
1060
  question is waiting while the decision it came from is open, then open, then done with its answer; it
978
1061
  is parked while the last settled decision that parks or brings it back parks it. A step is waiting while
@@ -57,5 +57,8 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
57
57
  thesis, the experiments included, those excluded or superseded, and those still open. What you propose,
58
58
  order, park or drop follows the storylines' open rows and their reviewers' criticisms; when a result lands,
59
59
  revise the overview and every storyline it touches, and move what a newer run supersedes to excluded. Adding,
60
- merging or retiring a storyline is direction. *Held by `lab check` when `lab.toml` names the storylines; otherwise
61
- judged.*
60
+ merging or retiring a storyline is direction. When the library keeps `pages.toml`, every page has a kind
61
+ (storyline, stable, reference or retiring), quotes a number only beside the result it comes from, and lands
62
+ only once a page reviewer who did not write it has passed it as it stands; the session that answers a question
63
+ revises the pages that cite it before the answer lands. *The storylines are held by `lab check` when `lab.toml`
64
+ names them, and the pages when the library keeps `pages.toml`; otherwise judged.*
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  dynamic = ["readme"]
7
7
  name = "lab-kit-cli"
8
- version = "1.14.0"
8
+ version = "1.16.0"
9
9
  description = "A research lab's record, its method, and the command that keeps both."
10
10
  license = "MIT"
11
11
  authors = [{ name = "Piergiuseppe Mallozzi" }]
@@ -70,7 +70,9 @@ operator wants its parts run separately, such as one wave each.
70
70
  4. Log each start: `lab mission log <id> "started G1.Q2.3 in its own session"`. Commit the
71
71
  mission file each time you add lines.
72
72
  5. Watch the sessions. When one ends a step, or is stuck, log it in the mission, and start the
73
- next step the rules leave room for.
73
+ next step the rules leave room for. When the library keeps `pages.toml`, the session whose result
74
+ passes review, or that answers a question, revises the pages that cite it with the lab-pages skill
75
+ before it pushes: give each session that rule with its step.
74
76
 
75
77
  ## Resume: "resume the mission", "resume M3", "how is the mission going"
76
78
 
@@ -0,0 +1,136 @@
1
+ ---
2
+ name: lab-pages
3
+ description: >-
4
+ Keep the library's pages in step with the record, when the library keeps `pages.toml`: the session that answers
5
+ a question revises, in the same sitting, the storyline pages that cite it, corrects a stable page only when it is
6
+ wrong, and lands nothing a page reviewer has not passed. Use whenever a question is answered (`lab answer`), when
7
+ a mission's result passes review, and when the operator says "update the pages", "revise the storyline",
8
+ "rewrite the top page", "fix this page" or names a page of the library.
9
+ ---
10
+
11
+ # lab-pages
12
+
13
+ This skill applies only when the library keeps `pages.toml` (`lab pages` says so). Without it, lab-work's rules
14
+ for the overview and the storylines are all there is.
15
+
16
+ The library sits above the record. The question cards (`lab show <id>`, served at `/lab/<id>/`) are the facts, and
17
+ no page repeats one. Every page has a kind in `pages.toml`:
18
+
19
+ | Kind | What it holds | When it changes |
20
+ |---|---|---|
21
+ | `storyline` | the argument: the top page, the result pages, what is new, what is not shown yet | when a question it cites is answered, or on request |
22
+ | `stable` | how the method works, and the words and objects every page leans on | only to correct an error, or when the method itself changes |
23
+ | `reference` | the overview (the full trail), the storyline's scope page, the appendices, the guide, the maps | as lab-work's rules for the overview and the storylines say |
24
+ | `retiring` | a page waiting to be merged into another and retired | never; finish the merge instead |
25
+
26
+ `lab check` holds the rest (docs/model.md, section 9, Pages): every page has a kind; every number a page quotes in a
27
+ `data-result` element is its card's, from reviewed results; no page but a retiring one uses a phrase `pages.toml`
28
+ drops or claims to be first without "to our knowledge"; every storyline and stable page has passed a page reviewer
29
+ as it now stands; every answer since `since` has reached its pages; each active storyline page links every storyline
30
+ page; and every link to a glossary term names a term the glossary has, with its definition as hover text.
31
+
32
+ ## When a question is answered
33
+
34
+ 1. Pull. Read `lab show <question>` and each of its steps' Found, Means and result names.
35
+ 2. List the pages to revise: `lab pages cites <question>`, plus the same for every question its answer
36
+ supersedes. Add the overview and the active storyline pages that `lab.toml` names (lab-work, The storylines and
37
+ the overview). Revise nothing else.
38
+ 3. If no storyline page cites the question, decide whether the answer belongs in the argument: a new item on the
39
+ top page, a limit under an existing item, or a line under what is not shown yet. If it would change the thesis
40
+ or drop an item, bring it to the operator with lab-talk instead of writing it.
41
+ 4. Revise each listed page (How a page reads, below). Change only what the answer changes. A number that changed
42
+ is changed everywhere it is quoted; `lab pages check` finds the quotes that disagree.
43
+ 5. If the answer shows a stable page wrong, correct that sentence and nothing else, and say so where the library
44
+ keeps its log ("correction").
45
+ 6. Review (below). Once every page has passed, record that the answer reached the pages:
46
+ `lab pages answered <question> "<the pages revised, or why none needed it>"`. It is refused while any storyline
47
+ or stable page waits for a pass. Until this row exists, `lab check` fails on the answered question: that failure
48
+ is expected before this step.
49
+ 7. Run the lab's gate.
50
+ 8. Land the answer, the pages, `page-reviews.tsv` and `answers-in-pages.tsv` together, as the lab's AGENTS.md says
51
+ content lands. If the push is refused because another session changed the same page, rebase, merge the two
52
+ edits, and have the merged paragraph read again.
53
+
54
+ A new storyline page is also linked from the active scope page (`lab.toml`'s `[storylines] active`), with the cards
55
+ it cites under included and the runs it leaves out under excluded; `lab check` fails on a storyline page the scope
56
+ page does not link.
57
+
58
+ The record is keyed by the question and the date on its `answered:` line. A question re-answered on the same day
59
+ is not due again: the session that re-answers it revises the pages all the same.
60
+
61
+ ## On request
62
+
63
+ The operator names a page, or asks to revise the storyline. Follow step 4, then the review, then steps 7 and 8 for
64
+ the pages named, with no answer to record. A new page: write it in the page shape, give it a kind in `pages.toml`
65
+ and one place on a map, then review. Moving, renaming, merging or retiring a page is proposed to the operator as a
66
+ table (page, from, to, why) and done with the library's own commands only after their yes.
67
+
68
+ ## Review
69
+
70
+ Every page you wrote or revised is read by a page reviewer who did not write it: start the `page-reviewer` agent
71
+ with only the page's path and the ids it cites. It checks each number and claim against the cards, the units, the
72
+ glossary's words and the lab's writing rules, and returns pass or a list of fixes. A page lands only on a pass.
73
+ Never review a page you wrote.
74
+
75
+ Fix rounds converge; they do not start over:
76
+
77
+ - The reviewer marks each fix **blocks** or **nit**. Everything its checklist finds blocks: a number or claim the
78
+ cards do not support, a running step given as a result, a count without "k of n" or a bare percentage, an
79
+ unhedged "first", a dropped phrase, a figure before its words, a term used undefined or defined when the glossary
80
+ has it, a broken sentence, and any `lab pages check` line about the page other than the expected one. A nit is wording
81
+ only.
82
+ - After a fail, make the fixes and send the page back to **the same reviewer** (continue that agent; do not start a
83
+ new one). It finds what changed itself, by diffing the page against the copy it kept of the version it read (in
84
+ its scratch folder, outside the repository and the store), not from your list. It re-checks each changed spot
85
+ against the cards, runs `lab pages check` again, and re-checks the page-wide order (each term linked at its first use,
86
+ each figure after its words). A change it did not ask for means it reads the whole page again.
87
+ - Rounds are counted per page. Nits may still be listed as fixes in the first and second readings; from the third
88
+ reading of the page on (the first reading plus two fix rounds), the reviewer passes once nothing blocks, and
89
+ lists the remaining nits briefly in its reply.
90
+ - If the original reviewer cannot be continued, a fresh reviewer reads the whole page, with the earlier lists of
91
+ fixes and the number of readings so far in hand; the count carries over. A pass is recorded only by a reviewer
92
+ that has every earlier fix in hand.
93
+
94
+ The reviewer records its pass in `page-reviews.tsv` (`lab pages passed`), with a fingerprint of the page as it read
95
+ it; the writer never records one. `lab check` fails on a storyline or stable page that no recorded pass matches, so a
96
+ page is read again only when its text changes, and never when it has not. `lab pages` lists every page and whether
97
+ its last change was passed. Commit `page-reviews.tsv` with the page.
98
+
99
+ ## How a page reads
100
+
101
+ Follow the lab's own writing rules (its AGENTS.md says where they are) and lab-work's page style. On top of them:
102
+
103
+ - **The top page**, in this order: the problem; the one contribution; a map of the results on one screen, each with
104
+ its count; one short block per item with its claim, one figure, its count, its limit and one link to its page;
105
+ what is not shown yet.
106
+ - **Every other page**, in this order: a title that states the claim; the question in one sentence; the answer in
107
+ one bold sentence; one example worked by hand; one figure after the words that name its parts; the count and its
108
+ honest limit; a record box at the foot with the ids, linked. Ids appear nowhere else on the page, except in an
109
+ active storyline page's scope table, which lab-work fills with id links.
110
+ - **Numbers.** Write "k of n" with what n is, never a bare percentage. A storyline page carries
111
+ `<meta name="numbers" content="tagged">`, and every number on it from a card sits in an element naming its result:
112
+ `<span data-result="G1.Q1.1:ratio">50%</span>`, or `<span data-result="G1.Q2.1:held+held-late">12</span> of 12`. Names joined by `+` are summed and by `*`
113
+ multiplied, so a share times its total gives a count; a single result read as a percent or in points is compared
114
+ as one. The first number the element shows is compared with the card's value rounded to as many decimals as the page
115
+ shows, or with the number the card itself shows.
116
+ A number that is not a result (a definition, a count of what is studied) sits in an element marked `data-plain`;
117
+ the total in "k of n", a year, and a number right after a word `pages.toml` lists under `names` need neither.
118
+ - **Definitions live in the glossary.** The lab defines each word once, in `GLOSSARY.md`, served at
119
+ `/lab/glossary/`. A page never defines a term the glossary has: it links the term's first use on the page to its
120
+ entry, `<a class="term" href="/lab/glossary/#error-ratio">error ratio</a>`, then runs `lab pages terms`, which
121
+ writes the entry's definition into the link as hover text. The anchor is the entry's heading in lower case with
122
+ spaces as hyphens; a word of the page that is not a heading is listed under the entry's `- also:`. A word the
123
+ glossary lacks is added to `GLOSSARY.md` first, in the lab's words, then linked. A page explains only what is
124
+ particular to it. The hover text is left out of a page's fingerprint, so a changed definition asks for no new
125
+ review.
126
+ - **Words.** The glossary's terms as it defines them; none of the phrases `pages.toml` drops; "first" only as "to our
127
+ knowledge", naming the closest published work.
128
+ - **Running work.** A step still running has no result on any page; it may appear under what is not shown yet.
129
+
130
+ ## Never
131
+
132
+ - A page that repeats a question card.
133
+ - A number on a storyline page without its `data-result`.
134
+ - A stable page reframed to fit a new result.
135
+ - A card, a decision or a locked plan changed to fit a page.
136
+ - A pass recorded by the session that wrote the page.
@@ -42,6 +42,11 @@ A failed plan is fixed by its author and read again.
42
42
  can read, saying what you conclude ("The numbers are what the rows say, and the bars were fixed
43
43
  before the run."). What you re-ran and what you could not verify comes after it: the page shows
44
44
  the first sentence and folds the rest.
45
+ 5. When rows that an earlier results review passed have changed since (`lab check` says "a row that a
46
+ review had passed in ... is gone or changed"), read what changed (`git diff` of `results.tsv` from
47
+ the commit it names) as well as the rows. Pass it only when each changed row still reports the same
48
+ result, read another way, and add `--supersedes <of>`, naming that earlier review's `of` from
49
+ `reviews.tsv`: the note says why the rows changed. A different result is a new experiment: fail it.
45
50
 
46
51
  A failed results review is final for that experiment. Say in the note what a replacement must do
47
52
  differently. Its numbers can then be cited nowhere: if a storyline page lists it under included, `lab check`
@@ -127,6 +127,11 @@ row, move it to included, or to excluded if it is void or no longer serves the a
127
127
  that fails makes the experiment void: take it off every included row. `lab check` refuses what a row may
128
128
  not list, and notes a storyline committed before a result about something it lists.
129
129
 
130
+ When the library keeps `pages.toml`, every page has a kind, and the lab-pages skill says how a page is revised and
131
+ reviewed: the session that answers a question revises the storyline pages that cite it (`lab pages cites
132
+ <question>`) in the same sitting, a page reviewer who did not write them passes each, and `lab pages answered`
133
+ records it before the answer lands. `lab check` holds it, and `lab now` lists what waits.
134
+
130
135
  A home map has the section Current storylines (`<h2 id="current-storylines">`): one row per active storyline
131
136
  page, and nothing else. `lab check` holds that its rows and `active` name the same pages.
132
137
 
@@ -287,7 +292,8 @@ repository, tests first. When it works, put `commits:` and `tests:` on the card
287
292
  `lab now` lists such a question under **Yours next**, and a goal whose questions are all settled. Decide whether they answer it. For a test, `lab answer <question> yes|no|mixed "<what the answer rests
288
293
  on>"`: yes and no say whether what the question expected held; mixed says part held and part did not,
289
294
  and the sentence says which. For an estimate, `lab answer <question> found "<the finding, with its range
290
- or its shape, and what it rests on>"`. Then bring **So far** up to date. An answer rests on a done experiment that is not
295
+ or its shape, and what it rests on>"`. Then bring **So far** up to date. When the library keeps `pages.toml`,
296
+ revise the pages the answer touches in the same sitting, with the lab-pages skill, before you push the answer. An answer rests on a done experiment that is not
291
297
  void. If they do not answer it, add the next experiment. An answer usually changes
292
298
  what should come next: open a decision.
293
299
 
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.14.0"
2
+ __version__ = "1.16.0"
@@ -3,7 +3,7 @@ from __future__ import annotations
3
3
 
4
4
  import glob, os, re
5
5
 
6
- from . import history, storylines, record as R, runs as runs_, write
6
+ from . import history, pages, storylines, record as R, runs as runs_, write
7
7
 
8
8
  KEYS = { # what a card's front matter may hold; a state is never among them
9
9
  "goal": {"title", "from", "reached", "dropped", "see"},
@@ -305,6 +305,10 @@ def run(lab, rederive=True):
305
305
  if r["stage"] not in ("plan", "results") or r["verdict"] not in ("pass", "fail") or not R.day(r["date"]) or not r["of"]:
306
306
  bad("reviews", p, f"a row of reviews.tsv is not one `lab review` wrote: {R.flat(' '.join(r.values()))[:60]!r}")
307
307
  break
308
+ for i, r in enumerate(x["reviews"]):
309
+ m = R.SUPERSEDING.search((r.get("note") or "").rstrip()) if r.get("stage") == "results" and r.get("verdict") == "pass" else None
310
+ if m and not any(e.get("stage") == "results" and e.get("verdict") == "pass" and e.get("of") == m.group(1) and e.get("of") != r.get("of") for e in x["reviews"][:i]):
311
+ bad("reviews", p, f"a results review supersedes {m.group(1)}, which is no earlier results review of other rows that passed")
308
312
  if x["results"]:
309
313
  if not x["lock"] or not x["finished"]:
310
314
  bad("results", p, "has results with no locked plan and finished run behind them")
@@ -430,6 +434,9 @@ def run(lab, rederive=True):
430
434
  # storylines: each active storyline's scope lists only what it may
431
435
  storylines.check(lab, bad, notes)
432
436
 
437
+ # pages: when the library keeps pages.toml, every page has a kind, quotes its numbers as the cards give them and was passed as it stands
438
+ pages.check(lab, bad, notes)
439
+
433
440
  # clean: the plans and the store stay out of default searches
434
441
  ignore = R.read(f"{root}/.ignore") if os.path.exists(f"{root}/.ignore") else ""
435
442
  if "plan/" not in ignore or "runs/" not in ignore:
@@ -3,7 +3,7 @@ from __future__ import annotations
3
3
 
4
4
  import os, re, sys
5
5
 
6
- from . import __version__, checks, runs, views, write
6
+ from . import __version__, checks, pages, runs, views, write
7
7
  from .record import Lab, amount, find_root
8
8
 
9
9
  USAGE = """To look
@@ -27,6 +27,13 @@ To carry out a decision
27
27
  lab mission launch [<mission>] make it current; with no id, the one saved last. Several may be current
28
28
  lab mission log [<mission>] "<what happened>" a line in a current mission's log
29
29
  lab mission close [<mission>] [--stopped] "<what it did, or why it stopped>" done (or stopped), one line in log.md; the file is kept
30
+ For the library's pages (when it keeps pages.toml)
31
+ lab pages every page with its kind and whether a page reviewer passed it as it stands
32
+ lab pages check only what `lab check` holds about the pages, quickly
33
+ lab pages cites <question or step> the storyline pages that cite it: those to revise when it is answered
34
+ lab pages passed <page> "<what was checked>" the page reviewer's pass of a page as it now stands
35
+ lab pages answered <question> "<the pages revised>" the answer has reached its pages, each passed
36
+ lab pages terms write each glossary link's hover text from GLOSSARY.md
30
37
  For evidence
31
38
  lab lock <experiment>
32
39
  lab run <experiment> [--trial] [--wait] [--changed "<what changed since the last run, and why>"] -- <command>
@@ -34,7 +41,9 @@ For evidence
34
41
  lab runs close <run> "<why>" [--used <resource>=<amount>]... a run whose process died; --used for one that wrote no used.json
35
42
  lab runs close <run> "<why>" --used <resource>=<amount>... --evidence <folder> an ended run that did not record what it used of a resource it ran on
36
43
  lab runs lost <run> "<why>" [--used <resource>=<amount>]... a run that started and whose folder is gone for good
37
- lab review <experiment> plan|results pass|fail "<note>" [--by <who>]
44
+ lab review <experiment> plan|results pass|fail "<note>" [--by <who>] [--supersedes <of>]
45
+ --supersedes: a results review that passes rows changed after the review
46
+ whose `of` it names had passed them; the note says why they changed
38
47
  lab check [--no-rederive] [--strict] runs every command in results.tsv: only on a lab you trust. --strict fails when
39
48
  history or the store could not be checked, as in CI
40
49
  Once
@@ -63,7 +72,8 @@ def main(argv=None):
63
72
  held = None
64
73
  bare = [r for r in rest if r != "--all"]
65
74
  looks = cmd == "mission" and len(bare) <= 1 and (not bare or re.fullmatch(r"M\d+", bare[0]) is not None) # `lab mission [<id>]` only reads
66
- if cmd in ("new", "log", "decide", "answer", "lock", "review") or (cmd == "mission" and not looks): # one writer at a time, on the lab as it then is
75
+ writes = cmd == "pages" and rest[:1] in (["passed"], ["answered"], ["terms"])
76
+ if cmd in ("new", "log", "decide", "answer", "lock", "review") or (cmd == "mission" and not looks) or writes: # one writer at a time, on the lab as it then is
67
77
  held = runs.exclusive(find_root())
68
78
  held.__enter__()
69
79
  lab = Lab()
@@ -141,6 +151,31 @@ def main(argv=None):
141
151
  if len(rest) != 3:
142
152
  raise SystemExit(USAGE)
143
153
  print(f"answered: {write.answer(lab, rest[0], rest[1], rest[2])}")
154
+ if pages.on(lab):
155
+ print(f"now revise the pages it touches (`lab pages cites {rest[0]}`) with the lab-pages skill; once a page reviewer has passed them, "
156
+ f"`lab pages answered {rest[0]} \"<the pages revised>\"`. `lab check` reports it until then")
157
+ elif cmd == "pages":
158
+ if not rest:
159
+ print(pages.listing(lab))
160
+ elif rest[0] == "check" and len(rest) == 1:
161
+ pages._require(lab)
162
+ found = []
163
+ pages.check(lab, lambda check, where, what: found.append(f"{check}: {where}: {what}"), [])
164
+ print("\n".join(sorted(set(found))) or "the pages are in step with the record")
165
+ if found:
166
+ return 1
167
+ elif rest[0] == "cites" and len(rest) == 2:
168
+ pages._require(lab)
169
+ print("\n".join(pages.cites(lab, rest[1])) or f"no storyline page cites {rest[1]}")
170
+ elif rest[0] == "passed" and len(rest) == 3:
171
+ print(f"recorded in {pages.record_pass(lab, rest[1], rest[2])}; commit it with the page")
172
+ elif rest[0] == "answered" and len(rest) == 3:
173
+ print(f"recorded in {pages.record_answer(lab, rest[1], rest[2])}; commit it with the answer and the pages")
174
+ elif rest[0] == "terms" and len(rest) == 1:
175
+ changed = pages.sync_terms(lab)
176
+ print("hover text written in " + ", ".join(changed) if changed else "every glossary link's hover text is its definition")
177
+ else:
178
+ raise SystemExit(USAGE)
144
179
  elif cmd == "lock" and len(rest) == 1:
145
180
  print(f"locked: {write.lock(lab, rest[0])}")
146
181
  elif cmd == "run":
@@ -191,10 +226,11 @@ def main(argv=None):
191
226
  else:
192
227
  raise SystemExit(USAGE)
193
228
  elif cmd == "review":
194
- by = flag("--by")
229
+ named = "--supersedes" in rest
230
+ by, supersedes = flag("--by"), flag("--supersedes")
195
231
  if len(rest) != 4:
196
232
  raise SystemExit(USAGE)
197
- print(f"recorded in {write.review(lab, rest[0], rest[1], rest[2], rest[3], by or None)}")
233
+ print(f"recorded in {write.review(lab, rest[0], rest[1], rest[2], rest[3], by or None, supersedes if named else None)}")
198
234
  elif cmd == "check":
199
235
  if set(rest) - {"--no-rederive", "--strict"}:
200
236
  raise SystemExit(USAGE)
@@ -382,6 +382,7 @@ def check(lab):
382
382
  rows, read = where.rsplit("/", 1)[0] + "/results.tsv", set()
383
383
  if rows not in now:
384
384
  continue # never committed, so nothing is held; or committed and gone, which is said above
385
+ held_at = [] # (commit, the rows it holds, the last review that passed them there), newest first
385
386
  for c, path in reversed(commits + versions.get(rows, [])): # every commit that touched the reviews or the rows
386
387
  folder = os.path.dirname(path)
387
388
  if c in read:
@@ -395,6 +396,13 @@ def check(lab):
395
396
  seals = [l[5] for l in listed if len(l) >= 6 and l[1] == "run" and l[2] == "ended" and l[4] == "0"] # the finished run, as that commit lists it
396
397
  if passed[-1].get("of") not in {R.text_hash(R.text_hash(was) + str(seal))[:16] for seal in seals}:
397
398
  continue # the last review that passed there read other rows than these
399
+ held_at.append((c, was, passed[-1]))
400
+ # A passing results review that names an earlier one by its `of` (`lab review ... --supersedes`) supersedes it
401
+ # only once it is committed together with the rows it read: then those rows are held instead of the earlier ones.
402
+ gone = R.superseded([r for _, _, r in held_at])
403
+ for c, was, review in held_at:
404
+ if review.get("of") in gone:
405
+ continue # a later review, committed with the rows it read, superseded it and said why
398
406
  lost = subsequence(was.splitlines(), R.read(os.path.join(root, now[rows][0])).splitlines())
399
407
  if lost is not None:
400
408
  bad(now[rows][0], f"a row that a review had passed in {c[:8]} is gone or changed: {lost[:70]!r}. Reviewed rows stay; a different result is a new experiment")