lab-kit-cli 1.11.0__tar.gz → 1.12.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 (46) hide show
  1. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/CHANGELOG.md +28 -0
  2. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/PKG-INFO +2 -2
  3. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/README.md +1 -1
  4. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/docs/model.md +66 -4
  5. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/method/METHOD.md +12 -3
  6. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/pyproject.toml +1 -1
  7. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/skills/lab-review/SKILL.md +2 -1
  8. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/skills/lab-set-up/SKILL.md +8 -2
  9. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/skills/lab-talk/SKILL.md +12 -1
  10. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/skills/lab-work/SKILL.md +40 -2
  11. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/src/lab_kit/__init__.py +1 -1
  12. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/src/lab_kit/checks.py +25 -2
  13. lab_kit_cli-1.12.0/src/lab_kit/papers.py +228 -0
  14. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/src/lab_kit/views.py +2 -1
  15. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_integrity.py +8 -0
  16. lab_kit_cli-1.12.0/tests/test_papers.py +189 -0
  17. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/.github/workflows/ci.yml +0 -0
  18. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/.github/workflows/policy.yml +0 -0
  19. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/.github/workflows/release.yml +0 -0
  20. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/.gitignore +0 -0
  21. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/AGENTS.md +0 -0
  22. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/CLAUDE.md +0 -0
  23. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/CONTRIBUTING.md +0 -0
  24. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/LICENSE +0 -0
  25. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/agents/reviewer.md +0 -0
  26. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/skills/lab-mission/SKILL.md +0 -0
  27. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/src/lab_kit/cli.py +0 -0
  28. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/src/lab_kit/history.py +0 -0
  29. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/src/lab_kit/record.py +0 -0
  30. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/src/lab_kit/runs.py +0 -0
  31. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/src/lab_kit/site.py +0 -0
  32. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/src/lab_kit/supervise.py +0 -0
  33. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/src/lab_kit/write.py +0 -0
  34. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_drafts.py +0 -0
  35. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_flow.py +0 -0
  36. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_held.py +0 -0
  37. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_mission.py +0 -0
  38. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_needs.py +0 -0
  39. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_order.py +0 -0
  40. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_parked.py +0 -0
  41. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_refusals.py +0 -0
  42. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_site.py +0 -0
  43. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_states.py +0 -0
  44. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_vocabulary.py +0 -0
  45. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tests/test_wording.py +0 -0
  46. {lab_kit_cli-1.11.0 → lab_kit_cli-1.12.0}/tools/import_run.py +0 -0
@@ -1,5 +1,33 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.12.0
4
+
5
+ - **Papers drive the work; the record names no paper** (method rule 8, model section 4). A lab that writes
6
+ papers keeps one overview page of the whole trail and one page per active paper, written as that paper's
7
+ argument and opening with a scope table: audience, thesis, experiments included, excluded or superseded, and
8
+ open. The papers' open rows and their reviewers' criticisms say what is proposed, ordered, parked or dropped,
9
+ and a result revises the overview and every paper it touches. So far gives the current finding, never the
10
+ story of the bugs on the way. Adding, merging or retiring a paper is direction.
11
+ - **`[papers]` in `lab.toml`** names the overview and the active paper pages, as library paths. It is optional:
12
+ a lab without it is unchanged. With it, each paper page marks its scope cells `data-scope="included"`,
13
+ `"excluded"` and `"open"`, and `lab check` refuses an id that is not in the lab, a step under included that is
14
+ not done or is void, a step under open that is finished, a question or goal under open that is done, a parked
15
+ or dropped question or goal in either, and a goal, question or step listed in two rows of one page. It notes a
16
+ paper page committed before a result about something it lists under included or open.
17
+ - **`lab now` lists the papers**: each active paper with the open work its scope names, then the live steps
18
+ that no paper lists, by themselves or by their question or goal.
19
+ - The skills `lab-set-up`, `lab-work`, `lab-talk` and `lab-review` and the method changed: run `lab init` in a lab
20
+ after upgrading.
21
+
22
+ ## 1.11.1
23
+
24
+ - **A run in progress in another checkout no longer fails `lab check`.** A run stays in the `.lab/running` of the
25
+ checkout that started it until it ends, so every other checkout of the same lab saw a run listed as started and
26
+ not in the store, and `lab check` failed there with "a run is never removed": with several sessions running
27
+ experiments in their own worktrees, the gate was red everywhere but in each run's own checkout. A run listed as
28
+ started and not ended, whose folder is in the `.lab/running` of another git worktree of the lab on this machine,
29
+ is now a note. A run listed as started whose folder is nowhere is still a problem, the prompt to declare it lost.
30
+
3
31
  ## 1.11.0
4
32
 
5
33
  - **An ended run that did not record what it used can be amended.** A run stopped before its machines' files came
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.11.0
3
+ Version: 1.12.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
@@ -75,5 +75,5 @@ where folio serves the lab, which brings `folio-kb` 0.5.0 or later, and list `la
75
75
  ## Read more
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
- - [method/METHOD.md](https://github.com/pierg/lab-kit/blob/main/method/METHOD.md): the seven rules every lab keeps.
78
+ - [method/METHOD.md](https://github.com/pierg/lab-kit/blob/main/method/METHOD.md): the eight rules every lab keeps.
79
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.
@@ -56,5 +56,5 @@ where folio serves the lab, which brings `folio-kb` 0.5.0 or later, and list `la
56
56
  ## Read more
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
- - [method/METHOD.md](method/METHOD.md): the seven rules every lab keeps.
59
+ - [method/METHOD.md](method/METHOD.md): the eight rules every lab keeps.
60
60
  - [skills/](skills/): lab-set-up, lab-work, lab-review, lab-talk and lab-mission. [agents/](agents/): the reviewer.
@@ -173,7 +173,10 @@ Each arrow is a command that refuses when the step before it is missing. You see
173
173
  git: one row when a run or a trial starts, and one when it ends, with how it ended and its seal.
174
174
  Rows are only added. `lab run` reads that list as well as the store, so a clone without the store
175
175
  still knows what ran. `lab check` asks that every listed run is in the store with the seal that
176
- was listed, and that every run in the store is listed. Where the store is not mounted the check
176
+ was listed, and that every run in the store is listed. A run in progress is in the `.lab/running`
177
+ of the checkout that started it until it ends: one listed as started and not ended whose folder is
178
+ there in another git worktree of the lab on this machine is running, and the check notes it
179
+ instead of asking for it in the store. Where the store is not mounted the check
177
180
  says so and checks no run.
178
181
  **A run that is lost.** A run can start and never report back: the machine dies with its folder on
179
182
  it. Its `started` row stays. `lab runs lost <run> "<why>"` adds a row that says so, with the reason
@@ -252,7 +255,7 @@ in points. When a named result belongs to a replaced experiment, the page says s
252
255
  You decide two things: **direction** and **resources**. You decide them in a discussion with the agent,
253
256
  not by approving requests.
254
257
 
255
- - **Direction.** The goals and the questions.
258
+ - **Direction.** The goals, the questions, and the papers they serve.
256
259
  - **Resources.** Everything outside the lab that it may touch: what it may use, how much, and what it
257
260
  may do there.
258
261
 
@@ -373,6 +376,36 @@ is a resource and a cap, nothing else. A lower cap is the agent's to write. A hi
373
376
  rule, a new resource or a larger grant comes out of a decision: one that lists that experiment, or
374
377
  that resource, under `about:`.
375
378
 
379
+ **Papers drive the work; the record names no paper.** A lab that writes papers keeps two layers apart. The
380
+ record (`goals/`, `decisions/`, `runs/`) is the trail: every question, run, failed attempt and replaced
381
+ experiment, so that every number has an origin. No card names a paper, because papers change, split, merge
382
+ and are dropped while the record stays as it is and is read by each of them. Above the record, the lab's
383
+ library holds one **overview** page that keeps the whole trail in one place, whatever paper it serves: the
384
+ words on one running example, the workflow, every related-work row, every established finding, every
385
+ criticism and what answers it. Beside it, each **active paper** has its own page, written as that paper's
386
+ technical argument and nothing else: it never talks about the lab or how it works. A paper page opens, under
387
+ its thesis, with a **scope table** of five rows: the target audience and venues, the core thesis, the
388
+ experiments included (the clean runs each claim rests on), the experiments excluded or superseded (a run
389
+ that hit a harness bug, a subset a full run replaced, work that belongs to another paper), and the open
390
+ experiments the paper still needs. Then come its words on one running example, its pipeline, its
391
+ comparison with the published work of its community, its established results citing only included work,
392
+ the criticisms a reviewer in that community will raise with what answers each, and what remains to run.
393
+
394
+ The control runs from the papers to the lab, not the other way. Which questions and experiments are
395
+ proposed, ordered, parked or dropped follows the open rows and the criticisms on the active paper pages: a
396
+ decision says which paper row it serves, and a step that serves none is a candidate to park or drop. When a
397
+ result lands, the overview and every paper it touches are revised; a run that a newer one supersedes moves
398
+ from included to excluded. Adding, merging or retiring a paper is direction, so it is decided with you. A
399
+ question's or an experiment's So far gives the current finding, not the story of the bugs on the way: the
400
+ replaced experiments and the reasons they were replaced keep that story.
401
+
402
+ A lab opts in by naming the pages in `lab.toml` (section 9). Then `lab check` holds each scope table:
403
+ included lists only finished work that is not void, replaced or dropped, open only work still to do, nothing
404
+ parked or dropped is in either, and a goal, a question or a step sits in one row; a paper page committed
405
+ before a result about something it lists under included or open is noted. `lab now` lists each paper's open
406
+ experiments, and the live steps no paper lists, by themselves or
407
+ by their question or goal.
408
+
376
409
  ## 5. What the agent uses
377
410
 
378
411
  - **To look:** `lab now`, `lab show <id or path>`, `lab brief <question>`, `lab since`, `lab define <term>`. Each shows one level,
@@ -446,7 +479,7 @@ Five skills: `lab-set-up`, `lab-work`, `lab-review`, `lab-talk` (tell you where
446
479
  a decision to you, record what was decided), and `lab-mission` (save, launch, resume and close a mission). One
447
480
  role: the reviewer.
448
481
 
449
- Seven rules:
482
+ Eight rules:
450
483
 
451
484
  1. Say what would refute it before you run.
452
485
  2. A number counts only as a reviewed result of a locked plan.
@@ -459,11 +492,13 @@ Seven rules:
459
492
  6. Record what was decided and why, in the lab's words, and show the operator the text as recorded.
460
493
  Never record a decision that was not discussed with them.
461
494
  7. Say what you are on. When you start on a card, log what you are doing and why now.
495
+ 8. Papers drive the work; the record names no paper. The papers' open rows and criticisms say what to
496
+ propose, order, park or drop, and a result revises the overview and every paper it touches.
462
497
 
463
498
  `lab check` holds what can be held mechanically: ids and links, the goal's vocabulary being terms of the glossary, a title and a description on every
464
499
  card, short cards that write only their own front matter, a test on every line, a reason on every
465
500
  replacement, unchanged locks, sealed runs, results that still re-derive and were reviewed, use inside
466
- the resources' amounts, a decision behind every goal, question and metered amount, an experiment
501
+ the resources' amounts, what each paper's scope table lists when the lab names its papers, a decision behind every goal, question and metered amount, an experiment
467
502
  behind every answer, the method and the skills as the kit installed them, and a history that only
468
503
  grows. What it cannot read as this page describes (a mistyped folder, a list written as one value, a
469
504
  file that is not text) is a problem it reports; no command stops on it.
@@ -900,6 +935,33 @@ holds the line `launched`, else next, and `lab check` asks for the status to be
900
935
  reports a mission that breaks any of this, one whose `carries:` is not a decision, and a current mission whose
901
936
  decision is still open.
902
937
 
938
+ **Papers.** `lab.toml` names the library's paper pages in a table, as library paths (the path under
939
+ `content/`, as `see:` writes it):
940
+
941
+ ```
942
+ [papers]
943
+ overview = "entries/where-the-results-stand"
944
+ active = ["entries/paper-a", "entries/paper-b"]
945
+ ```
946
+
947
+ `overview` is the page that keeps the whole trail; it is never an active paper. Each page under `active` is
948
+ in the library and marks the three cells of its scope table that list work, `data-scope="included"`,
949
+ `data-scope="excluded"` and `data-scope="open"`, empty when it lists nothing:
950
+
951
+ ```
952
+ <tr><th>Experiments included</th><td data-scope="included"><a href="/lab/G1.Q1.4/">G1.Q1.4</a>, ...</td></tr>
953
+ ```
954
+
955
+ A cell lists what its `/lab/<id>/` links name, written from the site's root; any other text in it is prose. A
956
+ cell whose closing tag is left out ends where the next cell or row begins. The rules hold for the ids written in
957
+ the cells. Under included, a step is done and not void, and a question or a goal is not parked or dropped;
958
+ under open, a step is open, waiting or running, and a question or a goal is not done, parked or dropped. A goal,
959
+ a question or a step has one row on a page: where another row needs to mention it, it is named in words,
960
+ without its link. A question written in one row and a step under it written in another is allowed: the open
961
+ question with its one finished step included is the usual case. A decision may be cited in any row. In
962
+ `lab now` and in the note on a stale page, a goal or a question written under included or open stands for
963
+ every step under it. A lab without `[papers]` has none of this.
964
+
903
965
  **Worked-out states.** A goal is open until `reached: true` makes it done or `dropped:` drops it. A
904
966
  question is waiting while the decision it came from is open, then open, then done with its answer; it
905
967
  is parked while the last settled decision that parks or brings it back parks it. A step is waiting while
@@ -1,6 +1,6 @@
1
1
  # The method
2
2
 
3
- Seven rules every lab keeps. Each says what holds it: a command that refuses, a check, or a reviewer's
3
+ Eight rules every lab keeps. Each says what holds it: a command that refuses, a check, or a reviewer's
4
4
  judgement. The lab's own `AGENTS.md` adds only what is local.
5
5
 
6
6
  1. **Say what would refute it before you run.** An experiment states what it compares, what would
@@ -25,13 +25,14 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
25
25
  4. **Write for a reader who was not there.** Every page stands on its own: it says what each thing it
26
26
  mentions is, names each arm of an experiment and what it is, names another page by its exact
27
27
  title, and uses a term only as the glossary defines it, the one place a word is defined. A number is said once: it lives in its result row, and a card names it. A state is
28
- worked out, never written, and So far says what was learned, never where a step stands. Every
28
+ worked out, never written, and So far says what is learned now, never where a step stands and never the story of
29
+ the bugs on the way: the replaced experiments keep that. Every
29
30
  card has one of the same states: open, waiting, running, parked, done, replaced or dropped. A
30
31
  number's label says what it counts and of how many, in one set of cases named once: "of the 20
31
32
  checks the solver leaves open", not "of 20". *The numbers and the budgets are held by `lab check`; whether a page
32
33
  can be read cold is judged, and the reviewer reads for it.*
33
34
  5. **Decide everything that is not direction or resources, and never wait idle.** Direction is the
34
- goals and the questions. Resources are what `resources.toml` lists and how much. For those two,
35
+ goals, the questions and the active papers. Resources are what `resources.toml` lists and how much. For those two,
35
36
  open a decision that says what was seen, the options and what you recommend, and work on what it
36
37
  does not hold. What a decision settled needs no further yes. Everything else is yours: decide,
37
38
  record it, go on. A mission (`missions/`) carries out what a settled decision settled across sessions, and approves
@@ -49,3 +50,11 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
49
50
  should never have to ask you. When you start on a card or move to another, log it:
50
51
  `lab log <id> doing "<what>" "<why now>"`. The line stands on the front page until a result, a
51
52
  stuck line or a choice about the same card ends it. *Judged.*
53
+ 8. **Papers drive the work; the record names no paper.** The record is the trail, and no card names a paper.
54
+ When the lab writes papers, its library keeps one overview of the whole trail, and one page per active
55
+ paper that is that paper's argument and nothing else. A paper page opens with its scope table: audience,
56
+ thesis, the experiments included, those excluded or superseded, and those still open. What you propose,
57
+ order, park or drop follows the papers' open rows and their reviewers' criticisms; when a result lands,
58
+ revise the overview and every paper it touches, and move what a newer run supersedes to excluded. Adding,
59
+ merging or retiring a paper is direction. *Held by `lab check` when `lab.toml` names the papers; otherwise
60
+ 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.11.0"
8
+ version = "1.12.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" }]
@@ -44,7 +44,8 @@ A failed plan is fixed by its author and read again.
44
44
  the first sentence and folds the rest.
45
45
 
46
46
  A failed results review is final for that experiment. Say in the note what a replacement must do
47
- differently.
47
+ differently. Its numbers can then be cited nowhere: if a paper page lists it under included, `lab check`
48
+ says so, and the author takes it off.
48
49
 
49
50
  When you read a plan, also read the card as someone who was not there. If an arm is named and not
50
51
  explained, or the card points at something it does not say, say so in the note: it does not fail the
@@ -43,8 +43,14 @@ You set the lab up in one discussion with the operator, so that everything it se
43
43
  here first.
44
44
  11. The site: the lab's `docs/` folder is a folio library whose charter lists `lab_kit.site` under
45
45
  `views:`. Set it up with folio's own skill if it is not there.
46
-
47
- 12. Commit. Git is what holds the record: nothing is held before the first commit, and
46
+ 12. If the lab will write papers, ask the operator which papers it aims at now, for whom and where (it is
47
+ direction, and may stay empty). Write the overview page (for example `entries/where-the-results-stand`) with folio's
48
+ write skill: the words on one running example, the workflow, the related work, and empty sections for the
49
+ findings and the criticisms. For each paper, write `entries/paper-<slug>`: its thesis, then the scope table
50
+ (target audience and venues, core thesis, experiments included, excluded or superseded, open), with the
51
+ last three cells marked `data-scope="included"`, `"excluded"` and `"open"`. Name them in `lab.toml` under
52
+ `[papers]` (`overview`, `active`). No card names a paper (method rule 8).
53
+ 13. Commit. Git is what holds the record: nothing is held before the first commit, and
48
54
  `lab check --strict` says so.
49
55
 
50
56
  Done when `lab check --strict` passes and `lab now` shows each question as open.
@@ -33,7 +33,9 @@ from the record, shortest first. A decision is a discussion, not a request for a
33
33
  comes up, give its definition from `lab define` in a few words. Never use a word in its everyday
34
34
  sense when it is also a lab term. Compare items in a table.
35
35
  - For "where are we": each goal in a line, each open question with what is known so far, what is
36
- running, what is next, what there is to discuss. No more than a screen.
36
+ running, what is next, what there is to discuss. No more than a screen. When the lab names its papers,
37
+ lead with them: each active paper by its title, with what its open row still needs, then the steps
38
+ serving no paper.
37
39
  - `lab brief` is the question's page as text. Give it as it is, cut to what they asked. If what you
38
40
  want to say is not in it, the card is missing something: fix the card, then answer.
39
41
  - If the record does not say, say so. Never fill a gap from memory.
@@ -64,6 +66,15 @@ that resource or that experiment under `about:` before it is decided: `lab new d
64
66
  --about <resource or id>`. What a locked decision is about cannot be changed afterwards, and a
65
67
  resource's new amount names the decision in `from`.
66
68
 
69
+ ## Papers
70
+
71
+ When the lab names its papers, they set the direction: the options you bring follow their open rows and
72
+ their reviewers' criticisms, and an order of work (`order:`) is built from the open rows, the paper the
73
+ operator cares about first. Adding, splitting, merging or retiring a paper is a decision like a question's:
74
+ `lab new decision "<what it is about>"`, with the paper named in Seen and Decided by its page's title. Then
75
+ change the pages and `[papers]` in `lab.toml` (the lab-work skill, The papers and the overview). A
76
+ retired paper's open work is parked or dropped in the same decision, or moved to another paper's open row.
77
+
67
78
  ## When they decide something nobody raised
68
79
 
69
80
  `lab new decision "<what it is about>" --about <id>`, fill **Seen** with what prompted it, then
@@ -21,6 +21,11 @@ When a decision has set the order of the work, **Yours next** is already in that
21
21
  decision set it; follow it, and bring a change of order to the operator rather than skipping ahead.
22
22
  `lab show <id>` before you touch anything.
23
23
 
24
+ When the lab names its papers (`lab now` has a **Papers** section), read each active paper page's open row
25
+ and its criticisms before you choose what to propose: they say what the lab is for now. A step listed under
26
+ **Serving no active paper** is a candidate to park or drop, which you bring to the operator in a decision,
27
+ or it belongs on a paper's open row, which you add.
28
+
24
29
  When `lab now` lists a current mission and you were started to run it, or the operator asks to save,
25
30
  launch or resume one, follow the lab-mission skill: it starts sessions on the steps, and each of them
26
31
  works as this skill says.
@@ -96,6 +101,34 @@ the plan in fixed boxes, then the steps and the record. Write the card for that
96
101
  - **Options are named in words, never letters.** "Read `sll` apart", not "(a)". A decision's options
97
102
  are a list, each item opening with its name in bold.
98
103
 
104
+ ## The papers and the overview
105
+
106
+ When `lab.toml` names papers (`[papers]`), the library holds two kinds of page above the record (method
107
+ rule 8). The record itself never names a paper: no card, no title, no So far says "Paper A".
108
+
109
+ - **The overview** (`overview`) keeps the whole trail, whatever paper it serves: the words on one running
110
+ example, the workflow, every related-work row, every established finding, every criticism and what answers
111
+ it, and what runs now. Nothing is left off it for being off a paper.
112
+ - **A paper page** (each of `active`) is that paper's technical argument, in its community's voice, and
113
+ never talks about the lab, its method or itself ("this page shows", "the lab's record"). It opens, under its
114
+ thesis, with the scope table: target audience and venues, core thesis, experiments included, experiments
115
+ excluded or superseded, open experiments. The last three cells carry `data-scope="included"`,
116
+ `"excluded"` and `"open"`, and list ids as links (`<a href="/lab/G1.Q1.4/">G1.Q1.4</a>`). Then: its words
117
+ on one running example, its pipeline, the published work of its community compared, its established
118
+ results citing only included work, the criticisms its reviewers will raise (for each: what is true in
119
+ it, what the record shows, what remains to run), and last what remains to run.
120
+ - **A step or a question has one row on a page.** Where another row needs to mention it (excluded because
121
+ a newer run superseded it), name it in words, without its link. A decision may be cited anywhere.
122
+
123
+ When a result lands: bring the overview's findings up to date, then each paper whose argument it touches.
124
+ If it supersedes an included run, move the old one to excluded and cite the new one. If it closes an open
125
+ row, move it to included, or to excluded if it is void or no longer serves the argument. A result's review
126
+ that fails makes the experiment void: take it off every included row. `lab check` refuses what a row may
127
+ not list, and notes a paper committed before a result about something it lists.
128
+
129
+ Adding, splitting, merging or retiring a paper is direction: bring it to the operator (the lab-talk skill),
130
+ then change the pages and `[papers]`. A retired paper's page leaves `active` and stays in the library.
131
+
99
132
  ## When to open a decision
100
133
 
101
134
  Open one when a question is answered or an experiment refutes what was expected, when a result
@@ -109,7 +142,9 @@ parked question, and never take it up because it looks open: it is listed under
109
142
 
110
143
  1. `lab new decision "<what it is about>" --about <the goals, questions or experiments it concerns>`.
111
144
  2. On its card write **Seen** (what was observed, naming results), **Options** (a list of two or
112
- three, each item an option with what it costs and what it changes) and **Recommendation**. Put under `holds:` only the
145
+ three, each item an option with what it costs and what it changes) and **Recommendation**. When the
146
+ lab names its papers, say which paper's open row or criticism each option serves, by the paper's exact
147
+ title; an option that serves none says so. Put under `holds:` only the
113
148
  experiments that should not start before it is settled.
114
149
  3. Keep working on everything it does not hold. The lab-talk skill takes it to the operator and
115
150
  records what was decided.
@@ -182,10 +217,13 @@ until that decision is settled; after that it needs no further yes.
182
217
  of typing its number: `{attack-success}`. It is shown the way its row says it reads. Bring the
183
218
  experiment's **So far** up to date, and rewrite the question's **So far** the same way, with full names: `{G1.Q1.2:attack-success}`.
184
219
  So far says what was learned, never where a step stands ("is running", "is next", "no result yet"):
185
- the pages draw each step's state. `lab check` reports a question's So far that was last committed
220
+ the pages draw each step's state. It says what is known now, from the clean runs. When a newer
221
+ experiment fixes a harness bug or replaces an earlier setup, rewrite So far as the current finding; do
222
+ not retell the earlier bug, which the replaced experiment and its `because:` keep. `lab check` reports a question's So far that was last committed
186
223
  before a result under it, or one it names. Give each result a label that says what it counts and
187
224
  of how many, in a set of cases the lab names once ("of the 20 checks the solver leaves open").
188
225
  10. `lab log <experiment> result "<what was found, in a sentence, without numbers>" "<so what>"`.
226
+ 11. When the lab names its papers, revise them in the same sitting (next section).
189
227
 
190
228
  The outcome is worked out from the lines: you never write it.
191
229
 
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.11.0"
2
+ __version__ = "1.12.0"
@@ -3,7 +3,7 @@ from __future__ import annotations
3
3
 
4
4
  import glob, os, re
5
5
 
6
- from . import history, record as R, runs as runs_, write
6
+ from . import history, papers, 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"},
@@ -32,6 +32,22 @@ def run(lab, rederive=True):
32
32
  if lab.held.get("error"): # what locks a decision is read from git; without it a lock could be edited away unseen
33
33
  bad("history", "git", f"what locks a decision could not be read from the lab's history: {lab.held['error']}")
34
34
 
35
+ elsewhere, others = [], [] # runs runs.tsv lists as started and not ended whose folder is in another checkout's .lab/running
36
+
37
+ def running_elsewhere():
38
+ """The runs whose folder is in the .lab/running of another git worktree of this lab, on this machine."""
39
+ if not others:
40
+ top = history.git(root, "rev-parse", "--show-toplevel")
41
+ sub = os.path.relpath(root, top.strip()) if top else "."
42
+ trees = [l[len("worktree "):] for l in (history.git(root, "worktree", "list", "--porcelain") or "").splitlines() if l.startswith("worktree ")]
43
+ found = set()
44
+ for t in trees:
45
+ folder = os.path.join(t, sub, ".lab", "running")
46
+ if os.path.realpath(os.path.join(t, sub)) != os.path.realpath(root) and os.path.isdir(folder):
47
+ found.update(os.listdir(folder))
48
+ others.append(found)
49
+ return others[0]
50
+
35
51
  absent = {} # the libraries the charter names whose folder is not on this machine
36
52
 
37
53
  def see(where, page, who=""):
@@ -243,7 +259,9 @@ def run(lab, rederive=True):
243
259
  where = f"{r['dir']}"
244
260
  listed = x["listed"].get(r["id"])
245
261
  if r["missing"]: # runs.tsv is in git and the store is not: a run the ledger lists stays where it was sealed
246
- if here and not r["lost"]:
262
+ if here and not r["lost"] and r["state"] == "running" and r["id"] in running_elsewhere(): # it runs in another checkout here
263
+ elsewhere.append(r["id"])
264
+ elif here and not r["lost"]:
247
265
  bad("runs", where, f"is listed in {x['dir']}/runs.tsv and is not in the store: a run is never removed. If it started and its folder is gone for good, `lab runs lost {r['id']} \"<why>\"` records that")
248
266
  continue
249
267
  if listed and listed["lost"]:
@@ -409,6 +427,9 @@ def run(lab, rederive=True):
409
427
  for t in sorted({t for t in terms if terms.count(t) > 1}):
410
428
  bad("glossary", "GLOSSARY.md", f"{t!r} is defined twice")
411
429
 
430
+ # papers: each active paper's scope lists only what it may
431
+ papers.check(lab, bad, notes)
432
+
412
433
  # clean: the plans and the store stay out of default searches
413
434
  ignore = R.read(f"{root}/.ignore") if os.path.exists(f"{root}/.ignore") else ""
414
435
  if "plan/" not in ignore or "runs/" not in ignore:
@@ -425,6 +446,8 @@ def run(lab, rederive=True):
425
446
  waiting = [r for r in lab.runs if r["local"] and r["state"] != "running"]
426
447
  if waiting:
427
448
  notes.append(f"{len(waiting)} ended run(s) are still on this machine, not in the store: `lab runs publish`")
449
+ if elsewhere: # its own checkout checks it; it is held here once runs.tsv says it ended
450
+ notes.append(f"{len(elsewhere)} run(s) still running in another checkout on this machine, checked once they end: {', '.join(elsewhere)}")
428
451
  found, said = history.check(lab)
429
452
  said += history.uncommitted(lab) # not held by git yet: a note, and a failure when the check is strict
430
453
  problems += found
@@ -0,0 +1,228 @@
1
+ """Papers: the library's pages that argue for one target paper each, above a record that names no paper.
2
+
3
+ A lab opts in with `[papers]` in `lab.toml`: `overview`, the page that keeps the whole trail, and `active`, the page
4
+ of each paper being written. Each paper page opens with a scope table whose cells are marked
5
+ `data-scope="included"`, `"excluded"` and `"open"`; the `/lab/<id>/` links inside a cell are what it lists.
6
+ `lab check` holds what a cell may list, and `lab now` says what each paper still has open and which live steps
7
+ serve no paper.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ import os, re
12
+ from html.parser import HTMLParser
13
+
14
+ from . import record as R
15
+
16
+ ROWS = ("included", "excluded", "open")
17
+ LINK = re.compile(r"^/lab/(G\d+(?:\.Q\d+(?:\.\d+)?)?|D\d+)/?(?:[#?].*)?$")
18
+ LIVE = ("open", "waiting", "running")
19
+
20
+
21
+ class _Scope(HTMLParser):
22
+ """The page's title and, for each marked cell, the ids its links name, in order."""
23
+
24
+ def __init__(self):
25
+ super().__init__(convert_charrefs=True)
26
+ self.title, self.cells, self.marked, self.unknown = "", {r: [] for r in ROWS}, set(), []
27
+ self._title, self._row, self._tag, self._depth, self._tables = False, None, None, 0, 0
28
+
29
+ def handle_starttag(self, tag, attrs):
30
+ a = dict(attrs)
31
+ if tag == "title":
32
+ self._title = True
33
+ if self._row and ("data-scope" in a or (self._depth == 1 and not self._tables and self._tag in ("td", "th") and tag in ("td", "th", "tr"))):
34
+ self._row = None # a cell whose closing tag is left out ends where the next cell or row begins
35
+ if self._row:
36
+ self._depth += tag == self._tag
37
+ self._tables += tag == "table" # a table inside the cell has rows and cells of its own
38
+ m = LINK.match(a.get("href") or "") if tag == "a" else None
39
+ if m and m.group(1) not in self.cells[self._row]:
40
+ self.cells[self._row].append(m.group(1))
41
+ return
42
+ row = a.get("data-scope")
43
+ if row is None:
44
+ return
45
+ if row not in ROWS:
46
+ self.unknown.append(row)
47
+ return
48
+ self._row, self._tag, self._depth, self._tables = row, tag, 1, 0
49
+ self.marked.add(row)
50
+
51
+ def handle_endtag(self, tag):
52
+ if tag == "title":
53
+ self._title = False
54
+ if self._row and tag == "table" and self._tables:
55
+ self._tables -= 1
56
+ if self._row and tag == self._tag:
57
+ self._depth -= 1
58
+ if not self._depth:
59
+ self._row = None
60
+
61
+ def handle_data(self, data):
62
+ if self._title:
63
+ self.title += data
64
+
65
+
66
+ def page_file(lab, path):
67
+ return os.path.join(lab.root, lab.cfg.get("library", "docs"), "content", path.strip("/"), "index.html")
68
+
69
+
70
+ def config(lab):
71
+ """(overview, active pages, problems). (None, [], []) when the lab keeps no papers."""
72
+ p = lab.cfg.get("papers")
73
+ if p is None:
74
+ return None, [], []
75
+ if not isinstance(p, dict):
76
+ return None, [], ["`[papers]` is a table that names `overview` and `active`"]
77
+ problems = [f"`[papers]` holds `{k}`; it names only `overview` and `active`" for k in sorted(set(p) - {"overview", "active"})]
78
+ overview, active = p.get("overview"), p.get("active", [])
79
+ if not isinstance(overview, str) or not overview.strip():
80
+ problems.append("`[papers]` names its `overview`: the library page that keeps the whole trail, such as \"entries/where-the-results-stand\"")
81
+ overview = None
82
+ if not isinstance(active, list) or not all(isinstance(a, str) and a.strip() for a in active):
83
+ problems.append("`[papers]` lists its `active` paper pages as library paths, such as [\"entries/paper-a\"]")
84
+ active = []
85
+ active = [a.strip("/") for a in active]
86
+ for path in ([overview] if overview else []) + active:
87
+ if ".." in path.split("/"):
88
+ problems.append(f"`[papers]` names {path}; a page is a path inside the library's content, without `..`")
89
+ for a in sorted({a for a in active if active.count(a) > 1}):
90
+ problems.append(f"`[papers]` lists {a} more than once")
91
+ return (overview.strip("/") if overview else None), list(dict.fromkeys(active)), problems
92
+
93
+
94
+ def read(lab):
95
+ """Each active paper page as read: path, title, its cells' ids, the rows it marks; `missing` when not there."""
96
+ if getattr(lab, "_papers", None) is not None:
97
+ return lab._papers
98
+ _, active, _ = config(lab)
99
+ out = []
100
+ for path in active:
101
+ f = page_file(lab, path)
102
+ if not os.path.exists(f):
103
+ out.append({"path": path, "title": path, "cells": {r: [] for r in ROWS}, "marked": set(), "unknown": [], "missing": True})
104
+ continue
105
+ s = _Scope()
106
+ s.feed(R.read(f))
107
+ out.append({"path": path, "title": " ".join(s.title.split()) or path, "cells": s.cells, "marked": s.marked, "unknown": s.unknown, "missing": False})
108
+ lab._papers = out
109
+ return out
110
+
111
+
112
+ def _covered(lab, ident):
113
+ """The ids a cell's id stands for: itself, and every question and step under a goal or a question."""
114
+ n = lab.nodes.get(ident)
115
+ if not n:
116
+ return {ident}
117
+ if n["type"] == "goal":
118
+ return {ident} | {q["id"] for q in n.get("questions", [])} | {x["id"] for q in n.get("questions", []) for x in q["items"]}
119
+ if n["type"] == "question":
120
+ return {ident} | {x["id"] for x in n["items"]}
121
+ return {ident}
122
+
123
+
124
+ def serving(lab):
125
+ """The live steps that no active paper lists under included or open, by themselves or by their question or goal."""
126
+ named = set()
127
+ for p in read(lab):
128
+ for row in ("included", "open"):
129
+ for i in p["cells"][row]:
130
+ named |= _covered(lab, lab.folded.get(i, i))
131
+ return [x for x in lab.items if x["state"] in LIVE and not {x["id"], x["question"], x.get("goal")} & named]
132
+
133
+
134
+ def _say(n):
135
+ return "void: its results review failed, so no page uses its numbers" if n.get("label") == "void" else n["state"]
136
+
137
+
138
+ def check(lab, bad, notes):
139
+ """What `lab check` holds about the papers: the table in `lab.toml`, each page's scope, and what each row lists."""
140
+ overview, active, problems = config(lab)
141
+ for p in problems:
142
+ bad("papers", "lab.toml", p)
143
+ if overview is None and not active:
144
+ return
145
+ if overview and not os.path.exists(page_file(lab, overview)):
146
+ bad("papers", "lab.toml", f"`overview` names {overview}, which is not a page of the library")
147
+ if overview and overview in active:
148
+ bad("papers", "lab.toml", f"{overview} is the overview and an active paper: the overview keeps the whole trail, a paper only what it argues")
149
+ for p in read(lab):
150
+ where = lab.rel(page_file(lab, p["path"]))
151
+ if p["missing"]:
152
+ bad("papers", "lab.toml", f"`active` names {p['path']}, which is not a page of the library")
153
+ continue
154
+ for row in ROWS:
155
+ if row not in p["marked"]:
156
+ bad("papers", where, f"has no scope cell marked data-scope=\"{row}\": a paper page opens with its scope table, and each of included, excluded and open is a marked cell, empty if it lists nothing")
157
+ for row in p["unknown"]:
158
+ bad("papers", where, f"marks a cell data-scope=\"{row}\"; a scope cell is included, excluded or open")
159
+ rows = {row: [lab.folded.get(i, i) for i in p["cells"][row]] for row in ROWS}
160
+ for row, ids in rows.items():
161
+ for i in ids:
162
+ n = lab.nodes.get(i)
163
+ if not n:
164
+ bad("papers", where, f"lists {i} under {row}, which is not a goal, a question, a step or a decision of the lab")
165
+ continue
166
+ if row == "included":
167
+ if n["type"] in R.STEPS and (n["state"] != "done" or n.get("label") == "void"):
168
+ to = "open" if n["state"] in LIVE else "excluded"
169
+ bad("papers", where, f"lists {i} under included, which is {_say(n)}: a paper includes only finished work that is not void, replaced or dropped; list it under {to}")
170
+ elif n["type"] in ("question", "goal") and n["state"] in ("parked", "dropped"):
171
+ bad("papers", where, f"lists {i} under included, which is {n['state']}: list it under excluded")
172
+ elif row == "open":
173
+ if n["type"] in R.STEPS and n["state"] not in LIVE:
174
+ to = "included or excluded" if n["state"] == "done" and n.get("label") != "void" else "excluded"
175
+ bad("papers", where, f"lists {i} under open, which is {_say(n)}: open holds only work still to do; list it under {to}")
176
+ elif n["type"] in ("question", "goal") and n["state"] in ("done", "parked", "dropped"):
177
+ bad("papers", where, f"lists {i} under open, which is {n['state']}: open holds only work still to do")
178
+ for a, b in (("included", "excluded"), ("included", "open"), ("open", "excluded")):
179
+ for i in sorted(i for i in set(rows[a]) & set(rows[b]) if lab.nodes.get(i, {}).get("type") != "decision"): # a decision may be cited wherever it explains a row
180
+ bad("papers", where, f"lists {i} under both {a} and {b}: a step or a question has one row; where another row needs it, name it in words, without its link")
181
+ for q, step, at in stale(lab):
182
+ notes.append(f"papers: {q} was last committed before the result of {step} ({at}): bring the paper's argument up to date with it")
183
+
184
+
185
+ def stale(lab):
186
+ """[(page, step, when)]: an active paper page last committed before the newest `result` line about a step it lists
187
+ under included or open, or under a question or goal it lists there. Nothing where git cannot tell."""
188
+ from . import history
189
+ root, out = lab.root, []
190
+ if not history.committed(root):
191
+ return out
192
+ for p in read(lab):
193
+ if p["missing"]:
194
+ continue
195
+ f = os.path.relpath(page_file(lab, p["path"]), root)
196
+ if (history.git(root, "status", "--porcelain", "--", f) or "").strip():
197
+ continue # being brought up to date now
198
+ last = R.moment((history.git(root, "log", "-1", "--format=%cI", "--", f) or "").strip())
199
+ if not last:
200
+ continue
201
+ mine = set()
202
+ for row in ("included", "open"):
203
+ for i in p["cells"][row]:
204
+ mine |= _covered(lab, lab.folded.get(i, i))
205
+ newer = [l for l in lab.lines if l["kind"] == "result" and l["about"] in mine and l["time"] and (R.moment(l["at"]) or last) > last]
206
+ if newer:
207
+ out.append((p["path"], newer[-1]["about"], f"{newer[-1]['day']} {newer[-1]['time']}"))
208
+ return out
209
+
210
+
211
+ def now_lines(lab):
212
+ """The lines `lab now` gives the papers: each active paper with what it has open, then the steps no paper serves."""
213
+ _, active, _ = config(lab)
214
+ if not active:
215
+ return []
216
+ out = ["", "Papers (direction comes from their open rows and their criticisms)"]
217
+ for p in read(lab):
218
+ if p["missing"]:
219
+ out.append(f"- {p['path']}: not in the library")
220
+ continue
221
+ left = [lab.nodes[i] for i in (lab.folded.get(i, i) for i in p["cells"]["open"]) if i in lab.nodes and lab.nodes[i]["type"] != "decision"]
222
+ todo = ", ".join(f"{n['id']} {n['title']} ({n['state']})" for n in left) or "nothing"
223
+ out.append(f"- {p['title']} ({p['path']}): open {todo}")
224
+ idle = serving(lab)
225
+ if idle:
226
+ out += ["", "Serving no active paper (add to a paper's open row, or bring parking or dropping it to the operator)"]
227
+ out += [f"- {x['id']} {x['title']} ({x['state']})" for x in idle]
228
+ return out
@@ -3,7 +3,7 @@ from __future__ import annotations
3
3
 
4
4
  import os
5
5
 
6
- from . import record as R
6
+ from . import papers, record as R
7
7
 
8
8
 
9
9
  def num(x):
@@ -91,6 +91,7 @@ def _now(lab):
91
91
  key = x["label"] if x["state"] == "done" and x.get("label") else x["state"]
92
92
  counts[key] = counts.get(key, 0) + 1
93
93
  out += [f"- {q['id']} ({state(q)}): {q['title']} [{', '.join(f'{n} {k}' for k, n in counts.items()) or 'nothing under it'}]"]
94
+ out += papers.now_lines(lab)
94
95
  aside = lab.set_aside()
95
96
  if any(aside.values()):
96
97
  out += ["", "Set aside"] + [f"- {q['id']} (parked by {lab.parked_by(q['id'])['id']}): {q['title']}" for q in aside["parked"]]
@@ -516,6 +516,14 @@ def test_a_run_that_never_reports_back_is_declared_lost(tmp_path):
516
516
  assert f"lab runs lost {gone}" in lab(root, "run", ident, "--wait", "--", *command, ok=False)
517
517
  assert f"lab runs lost {gone}" in lab(root, "runs", "close", gone, "the machine is gone", ok=False)
518
518
  assert f"lab runs lost {gone}" in lab(root, "check", "--no-rederive", ok=False)
519
+ # while its folder is in another checkout's .lab/running on this machine, it is running there: a note, not a problem
520
+ other = str(tmp_path) + "-other"
521
+ subprocess.run(["git", "-C", root, "worktree", "add", "-q", "--detach", other], check=True, capture_output=True)
522
+ os.makedirs(f"{other}/.lab/running/{gone}")
523
+ out = lab(root, "check", "--no-rederive")
524
+ assert "the record is sound" in out and f"still running in another checkout on this machine, checked once they end: {gone}" in out
525
+ shutil.rmtree(f"{other}/.lab/running/{gone}")
526
+ assert f"lab runs lost {gone}" in lab(root, "check", "--no-rederive", ok=False)
519
527
  assert "no run 20260102-0931_G1.Q1.1_zzzz is listed" in lab(root, "runs", "lost", "20260102-0931_G1.Q1.1_zzzz", "gone", ok=False)
520
528
  assert "say why" in lab(root, "runs", "lost", gone, " ", ok=False)
521
529
  assert "--used laptop=1" in lab(root, "runs", "lost", gone, "The machine was deleted.", "--used", "laptop=1", ok=False)
@@ -0,0 +1,189 @@
1
+ """Papers drive the work: the record names no paper, and each active paper's page opens with a scope table whose
2
+ included, excluded and open cells `lab check` holds, and whose open row `lab now` puts before the agent."""
3
+ import os
4
+
5
+ from test_flow import experiment, lab, open_question, results
6
+ from test_integrity import WRITES, commit, done
7
+ from test_states import PAST, git_env
8
+
9
+ PAGE = """<!DOCTYPE html>
10
+ <html><head><title>{title}</title></head>
11
+ <body><main>
12
+ <p class="thesis">The error falls with the square root of the sample.</p>
13
+ <section id="scope"><table><tbody>
14
+ <tr><th>Experiments included</th><td data-scope="included">{included}</td></tr>
15
+ <tr><th>Experiments excluded / superseded</th><td data-scope="excluded">{excluded}</td></tr>
16
+ <tr><th>Open experiments</th><td data-scope="open">{open}</td></tr>
17
+ </tbody></table></section>
18
+ </main></body></html>
19
+ """
20
+
21
+
22
+ def links(*ids):
23
+ return ", ".join(f'<a href="/lab/{i}/">{i}</a>' for i in ids)
24
+
25
+
26
+ def page(root, path, title="Paper A: The square-root law", included=(), excluded=(), open_=()):
27
+ d = os.path.join(root, "docs", "content", path)
28
+ os.makedirs(d, exist_ok=True)
29
+ open(f"{d}/index.html", "w").write(PAGE.format(title=title, included=links(*included), excluded=links(*excluded), open=links(*open_)))
30
+
31
+
32
+ def papers(root, overview="entries/where-the-results-stand", active=("entries/paper-a",)):
33
+ text = open(f"{root}/lab.toml").read().split("[papers]")[0]
34
+ open(f"{root}/lab.toml", "w").write(text + f'[papers]\noverview = "{overview}"\nactive = [{", ".join(chr(34) + a + chr(34) for a in active)}]\n')
35
+
36
+
37
+ def two_experiments(root):
38
+ """G1.Q1.1 done and confirmed, G1.Q1.2 done and void, G1.Q1.3 still open."""
39
+ open_question(root)
40
+ first, d1, c1 = experiment(root, command=WRITES % "0.5")
41
+ lab(root, "lock", first)
42
+ lab(root, "run", first, "--wait", "--", *c1)
43
+ done(root, first, d1)
44
+ void, d2, c2 = experiment(root, title="Error at 100 and at 1600 flips", command=WRITES % "0.25")
45
+ lab(root, "lock", void)
46
+ lab(root, "run", void, "--wait", "--", *c2)
47
+ results(d2, "0.25")
48
+ lab(root, "review", void, "results", "fail", "The seed was fixed after a first look.")
49
+ later, _, _ = experiment(root, title="Error at 400 and at 1600 flips")
50
+ page(root, "entries/where-the-results-stand", title="Where the results stand")
51
+ return first, void, later
52
+
53
+
54
+ def test_a_lab_without_papers_is_unchanged(tmp_path):
55
+ root = str(tmp_path)
56
+ two_experiments(root)
57
+ assert "Papers" not in lab(root, "now")
58
+ assert "papers:" not in lab(root, "check", "--no-rederive")
59
+
60
+
61
+ def test_a_paper_includes_only_finished_work_and_lists_each_id_once(tmp_path):
62
+ root = str(tmp_path)
63
+ first, void, later = two_experiments(root)
64
+ papers(root)
65
+ page(root, "entries/paper-a", included=(first, void, later), excluded=(first,), open_=("G1.Q9.1",))
66
+ out = lab(root, "check", "--no-rederive", ok=False)
67
+ assert f"lists {void} under included, which is void" in out and "list it under excluded" in out
68
+ assert f"lists {later} under included, which is open" in out and "list it under open" in out
69
+ assert f"lists {first} under both included and excluded" in out
70
+ assert "lists G1.Q9.1 under open, which is not a goal, a question, a step or a decision of the lab" in out
71
+ page(root, "entries/paper-a", included=(first,), excluded=(void,), open_=(first,))
72
+ assert f"lists {first} under open, which is done" in lab(root, "check", "--no-rederive", ok=False)
73
+ page(root, "entries/paper-a", included=(first, "D1"), excluded=(void,), open_=(later,))
74
+ assert "the record is sound" in lab(root, "check", "--no-rederive")
75
+
76
+
77
+ def test_the_papers_table_names_pages_that_are_there_each_with_its_scope(tmp_path):
78
+ root = str(tmp_path)
79
+ two_experiments(root)
80
+ papers(root, active=("entries/paper-a", "entries/paper-b", "entries/where-the-results-stand"))
81
+ os.makedirs(f"{root}/docs/content/entries/paper-a", exist_ok=True)
82
+ open(f"{root}/docs/content/entries/paper-a/index.html", "w").write("<html><body><td data-scope=\"kept\"></td></body></html>")
83
+ out = lab(root, "check", "--no-rederive", ok=False)
84
+ assert "`active` names entries/paper-b, which is not a page of the library" in out
85
+ assert "is the overview and an active paper" in out
86
+ assert 'has no scope cell marked data-scope="included"' in out and 'marks a cell data-scope="kept"' in out
87
+ papers(root, overview="entries/nowhere")
88
+ assert "`overview` names entries/nowhere, which is not a page of the library" in lab(root, "check", "--no-rederive", ok=False)
89
+
90
+
91
+ def test_a_card_never_names_a_paper(tmp_path):
92
+ root = str(tmp_path)
93
+ first, _, _ = two_experiments(root)
94
+ from test_flow import folder, front
95
+ front(f"{folder(root, first)}/experiment.md", paper="paper-a")
96
+ assert "`paper:` is not something a experiment card holds" in lab(root, "check", "--no-rederive", ok=False)
97
+
98
+
99
+ def test_now_puts_each_papers_open_row_first_and_names_what_serves_no_paper(tmp_path):
100
+ root = str(tmp_path)
101
+ first, void, later = two_experiments(root)
102
+ papers(root)
103
+ page(root, "entries/paper-a", included=(first,), excluded=(void,))
104
+ now = lab(root, "now")
105
+ assert "Paper A: The square-root law (entries/paper-a): open nothing" in now
106
+ assert "Serving no active paper" in now and f"- {later} Error at 400 and at 1600 flips (open)" in now
107
+ page(root, "entries/paper-a", included=(first,), excluded=(void,), open_=(later,))
108
+ now = lab(root, "now")
109
+ assert f"open {later} Error at 400 and at 1600 flips (open)" in now and "Serving no active paper" not in now
110
+ page(root, "entries/paper-a", included=(first,), excluded=(void,), open_=("G1.Q1",)) # a question stands for every step under it
111
+ assert "Serving no active paper" not in lab(root, "now")
112
+
113
+
114
+ def test_a_paper_older_than_a_result_it_lists_is_noted(tmp_path):
115
+ root = str(tmp_path)
116
+ first, void, later = two_experiments(root)
117
+ papers(root)
118
+ page(root, "entries/paper-a", included=(first,), excluded=(void,), open_=(later,))
119
+ git_env(root, "init", "-q")
120
+ git_env(root, "add", "-A")
121
+ git_env(root, "commit", "-qm", "the paper", GIT_AUTHOR_DATE=PAST, GIT_COMMITTER_DATE=PAST)
122
+ lab(root, "log", first, "result", "The error halves.", "It converges as the theory says.")
123
+ commit(root, "the result")
124
+ out = lab(root, "check", "--no-rederive", ok=False) # the question's So far is stale too, which is a problem
125
+ assert f"note: papers: entries/paper-a was last committed before the result of {first}" in out
126
+ assert "papers:" not in out.split("note: papers:")[1].split("\n", 1)[1] # a note, never a problem
127
+
128
+
129
+ def test_every_rule_on_a_row_and_on_the_table_has_a_refusal(tmp_path):
130
+ root = str(tmp_path)
131
+ first, void, later = two_experiments(root)
132
+ papers(root)
133
+ from test_flow import folder, front
134
+ front(f"{folder(root, later)}/experiment.md", dropped="the first comparison answers the question")
135
+ lab(root, "answer", "G1.Q1", "yes", "It halves at 400 flips.")
136
+ page(root, "entries/paper-a", included=(first,), excluded=(void,), open_=("G1.Q1",))
137
+ assert "lists G1.Q1 under open, which is done" in lab(root, "check", "--no-rederive", ok=False)
138
+ page(root, "entries/paper-a", included=("G1", first), excluded=(void,), open_=("G1",))
139
+ assert "lists G1 under both included and open" in lab(root, "check", "--no-rederive", ok=False)
140
+ # a question written in one row and a step under it in another is allowed
141
+ page(root, "entries/paper-a", included=("G1.Q1",), excluded=(void, later), open_=())
142
+ assert "papers:" not in lab(root, "check", "--no-rederive")
143
+ page(root, "entries/paper-a", included=(first,), excluded=("G1.Q1", void), open_=())
144
+ assert "papers:" not in lab(root, "check", "--no-rederive")
145
+ for table, said in (('papers = "entries/paper-a"', "`[papers]` is a table"),
146
+ ('[papers]\noverview = "entries/where-the-results-stand"\nkept = 1', "`[papers]` holds `kept`"),
147
+ ('[papers]\noverview = 3', "`[papers]` names its `overview`"),
148
+ ('[papers]\noverview = "entries/where-the-results-stand"\nactive = "entries/paper-a"', "lists its `active` paper pages"),
149
+ ('[papers]\noverview = "entries/where-the-results-stand"\nactive = ["entries/paper-a", "entries/paper-a/"]', "lists entries/paper-a more than once"),
150
+ ('[papers]\noverview = "../outside"', "without `..`")):
151
+ text = open(f"{root}/lab.toml").read().split("[papers]")[0].split("papers =")[0]
152
+ open(f"{root}/lab.toml", "w").write(text + table + "\n")
153
+ assert said in lab(root, "check", "--no-rederive", ok=False), table
154
+
155
+
156
+ def test_a_parked_or_dropped_question_is_in_neither_included_nor_open(tmp_path):
157
+ root = str(tmp_path)
158
+ first, void, later = two_experiments(root)
159
+ from test_parked import park
160
+ card, d = park(root, "G1.Q1", "Set the first sizes aside", "")
161
+ lab(root, "decide", d, "--with", "Ada", "Set the first sizes aside until the sampler is fixed.")
162
+ papers(root)
163
+ page(root, "entries/paper-a", included=("G1.Q1",), excluded=(void,))
164
+ assert "lists G1.Q1 under included, which is parked" in lab(root, "check", "--no-rederive", ok=False)
165
+ page(root, "entries/paper-a", excluded=(void,), open_=("G1.Q1",))
166
+ assert "lists G1.Q1 under open, which is parked" in lab(root, "check", "--no-rederive", ok=False)
167
+
168
+
169
+ def test_a_cell_left_open_ends_where_the_next_cell_begins(tmp_path):
170
+ root = str(tmp_path)
171
+ first, void, later = two_experiments(root)
172
+ papers(root)
173
+ d = f"{root}/docs/content/entries/paper-a"
174
+ os.makedirs(d, exist_ok=True)
175
+ open(f"{d}/index.html", "w").write(f'<html><head><title>Paper A</title></head><body><table><tr><td data-scope="included">{links(first)}'
176
+ f'<tr><td data-scope="excluded">{links(void)}<tr><td data-scope="open">{links(later)}</table></body></html>')
177
+ assert "papers:" not in lab(root, "check", "--no-rederive")
178
+ assert f"open {later} Error at 400 and at 1600 flips (open)" in lab(root, "now")
179
+
180
+
181
+ def test_a_table_inside_a_scope_cell_is_read_as_part_of_it(tmp_path):
182
+ root = str(tmp_path)
183
+ first, void, later = two_experiments(root)
184
+ papers(root)
185
+ d = f"{root}/docs/content/entries/paper-a"
186
+ os.makedirs(d, exist_ok=True)
187
+ open(f"{d}/index.html", "w").write(f'<html><body><table><tr><td data-scope="included"><table><tr><td>{links(first, void)}</td></tr></table></td>'
188
+ f'<td data-scope="excluded"></td><td data-scope="open">{links(later)}</td></tr></table></body></html>')
189
+ assert f"lists {void} under included, which is void" in lab(root, "check", "--no-rederive", ok=False)
File without changes
File without changes
File without changes
File without changes