lab-kit-cli 1.12.0__tar.gz → 1.14.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 (48) hide show
  1. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/CHANGELOG.md +35 -14
  2. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/PKG-INFO +1 -1
  3. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/docs/model.md +48 -37
  4. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/method/METHOD.md +8 -7
  5. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/pyproject.toml +1 -1
  6. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/skills/lab-review/SKILL.md +1 -1
  7. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/skills/lab-set-up/SKILL.md +11 -7
  8. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/skills/lab-talk/SKILL.md +10 -10
  9. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/skills/lab-work/SKILL.md +29 -22
  10. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/src/lab_kit/__init__.py +1 -1
  11. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/src/lab_kit/checks.py +3 -3
  12. lab_kit_cli-1.14.0/src/lab_kit/storylines.py +316 -0
  13. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/src/lab_kit/views.py +2 -2
  14. lab_kit_cli-1.14.0/tests/test_storylines.py +231 -0
  15. lab_kit_cli-1.12.0/src/lab_kit/papers.py +0 -228
  16. lab_kit_cli-1.12.0/tests/test_papers.py +0 -189
  17. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/.github/workflows/ci.yml +0 -0
  18. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/.github/workflows/policy.yml +0 -0
  19. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/.github/workflows/release.yml +0 -0
  20. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/.gitignore +0 -0
  21. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/AGENTS.md +0 -0
  22. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/CLAUDE.md +0 -0
  23. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/CONTRIBUTING.md +0 -0
  24. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/LICENSE +0 -0
  25. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/README.md +0 -0
  26. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/agents/reviewer.md +0 -0
  27. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/skills/lab-mission/SKILL.md +0 -0
  28. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/src/lab_kit/cli.py +0 -0
  29. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/src/lab_kit/history.py +0 -0
  30. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/src/lab_kit/record.py +0 -0
  31. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/src/lab_kit/runs.py +0 -0
  32. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/src/lab_kit/site.py +0 -0
  33. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/src/lab_kit/supervise.py +0 -0
  34. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/src/lab_kit/write.py +0 -0
  35. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_drafts.py +0 -0
  36. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_flow.py +0 -0
  37. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_held.py +0 -0
  38. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_integrity.py +0 -0
  39. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_mission.py +0 -0
  40. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_needs.py +0 -0
  41. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_order.py +0 -0
  42. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_parked.py +0 -0
  43. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_refusals.py +0 -0
  44. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_site.py +0 -0
  45. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_states.py +0 -0
  46. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_vocabulary.py +0 -0
  47. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tests/test_wording.py +0 -0
  48. {lab_kit_cli-1.12.0 → lab_kit_cli-1.14.0}/tools/import_run.py +0 -0
@@ -1,21 +1,42 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.14.0
4
+
5
+ - **A home map has Current storylines.** When `lab.toml` names active storylines, one of the library's home
6
+ maps has a section `<h2 id="current-storylines">Current storylines</h2>` whose rows are the active storyline
7
+ pages and nothing else, so every lab shows its storylines in the same place. `lab check` refuses a library
8
+ with no such section or with two, the section on a map that is not a home map, an active storyline with no
9
+ row there, a row listed twice, and a row there that is not an active storyline. Rows are read as folio reads
10
+ them: the first link of an item in a `rows` list, up to the next `h2` or `h3`. lab-set-up writes the section,
11
+ and lab-work keeps it when a storyline is added or retired.
12
+ - Upgrading: run `lab init`. A lab that names its storylines also moves their rows under Current storylines
13
+ (`folio map move <id> --to <map>#current-storylines`) before `lab check` passes.
14
+
15
+ ## 1.13.0
16
+
17
+ - **A scope page is a storyline.** A storyline is one argument the lab is building from its findings, for one
18
+ audience: what a paper, a talk or a report is later written from, never the finished artifact. The table in
19
+ `lab.toml` is `[storylines]`, `lab now` has a Storylines section and a "Serving no active storyline" list, and
20
+ the method, the model and the skills say storyline throughout. 1.12.0's table of the same shape, `[papers]`,
21
+ is no longer read: no lab had turned it on. Run `lab init` in a lab after upgrading.
22
+
3
23
  ## 1.12.0
4
24
 
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.
25
+ - **Storylines drive the work; the record names no storyline** (method rule 8, model section 4). A lab keeps one
26
+ overview page of the whole trail and one page per active storyline, written as that argument and opening with
27
+ a scope table: audience, thesis, experiments included, excluded or superseded, and open. The storylines' open
28
+ rows and their reviewers' criticisms say what is proposed, ordered, parked or dropped, and a result revises the
29
+ overview and every storyline it touches. So far gives the current finding, never the story of the bugs on the
30
+ way. Adding, merging or retiring a storyline is direction.
31
+ - **A table in `lab.toml`** (`[papers]` in this release, `[storylines]` from 1.13.0) names the overview and the
32
+ active storyline pages, as library paths. It is optional: a lab without it is unchanged. With it, each
33
+ storyline page marks its scope cells `data-scope="included"`, `"excluded"` and `"open"`, and `lab check`
34
+ refuses an id that is not in the lab, a step under included that is not done or is void, a step under open
35
+ that is finished, a question or goal under open that is done, a parked or dropped question or goal in either,
36
+ and a goal, question or step listed in two rows of one page. It notes a storyline page committed before a
37
+ result about something it lists under included or open.
38
+ - **`lab now` lists the storylines**: each active one with the open work its scope names, then the live steps
39
+ that none lists, by themselves or by their question or goal.
19
40
  - The skills `lab-set-up`, `lab-work`, `lab-talk` and `lab-review` and the method changed: run `lab init` in a lab
20
41
  after upgrading.
21
42
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.12.0
3
+ Version: 1.14.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
@@ -255,7 +255,7 @@ in points. When a named result belongs to a replaced experiment, the page says s
255
255
  You decide two things: **direction** and **resources**. You decide them in a discussion with the agent,
256
256
  not by approving requests.
257
257
 
258
- - **Direction.** The goals, the questions, and the papers they serve.
258
+ - **Direction.** The goals, the questions, and the storylines they serve.
259
259
  - **Resources.** Everything outside the lab that it may touch: what it may use, how much, and what it
260
260
  may do there.
261
261
 
@@ -376,35 +376,38 @@ is a resource and a cap, nothing else. A lower cap is the agent's to write. A hi
376
376
  rule, a new resource or a larger grant comes out of a decision: one that lists that experiment, or
377
377
  that resource, under `about:`.
378
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:
379
+ **Storylines drive the work; the record names no storyline.** A **storyline** is one argument the lab is
380
+ building from its findings, for one audience: what a paper, a talk or a report will later be written from. It is
381
+ the argument, never the finished artifact, and it keeps moving while the work runs. A lab that keeps storylines
382
+ keeps two layers apart. The record (`goals/`, `decisions/`, `runs/`) is the trail: every question, run, failed
383
+ attempt and replaced experiment, so that every number has an origin. No card names a storyline, because
384
+ storylines change, split, merge and are dropped while the record stays as it is and is read by each of them.
385
+ Above the record, the lab's library holds one **overview** page that keeps the whole trail in one place,
386
+ whatever storyline it serves: the words on one running example, the workflow, every related-work row, every
387
+ established finding, every criticism and what answers it. Beside it, each **active storyline** has its own page,
388
+ written as that storyline's technical argument and nothing else: it never talks about the lab or how it works. A
389
+ storyline page opens, under its thesis, with a **scope table** of five rows: the target audience and venues, the
390
+ core thesis, the experiments included (the clean runs each claim rests on), the experiments excluded or
391
+ superseded (a run that hit a harness bug, a subset a full run replaced, work that belongs to another storyline),
392
+ and the open experiments the storyline still needs. Then come its words on one running example, its pipeline,
393
+ its comparison with the published work of its community, its established results citing only included work, the
394
+ criticisms a reviewer in that community will raise with what answers each, and what remains to run. When the
395
+ time comes to write the paper, the talk or the report itself, it is written from this page.
396
+
397
+ The control runs from the storylines to the lab, not the other way. Which questions and experiments are
398
+ proposed, ordered, parked or dropped follows the open rows and the criticisms on the active storyline pages: a
399
+ decision says which storyline row it serves, and a step that serves none is a candidate to park or drop. When
400
+ a result lands, the overview and every storyline it touches are revised; a run that a newer one supersedes
401
+ moves from included to excluded. Adding, merging or retiring a storyline is direction, so it is decided with
402
+ you. A question's or an experiment's So far gives the current finding, not the story of the bugs on the way:
403
+ the replaced experiments and the reasons they were replaced keep that story.
404
+
405
+ A lab opts in by naming the pages in `lab.toml` (section 9), and its library's home map lists them under one
406
+ section, Current storylines. Then `lab check` holds that section and each scope table:
403
407
  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
+ parked or dropped is in either, and a goal, a question or a step sits in one row; a storyline page committed
409
+ before a result about something it lists under included or open is noted. `lab now` lists each storyline's
410
+ open experiments, and the live steps no storyline lists, by themselves or by their question or goal.
408
411
 
409
412
  ## 5. What the agent uses
410
413
 
@@ -492,13 +495,13 @@ Eight rules:
492
495
  6. Record what was decided and why, in the lab's words, and show the operator the text as recorded.
493
496
  Never record a decision that was not discussed with them.
494
497
  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.
498
+ 8. Storylines drive the work; the record names no storyline. The storylines' open rows and criticisms say
499
+ what to propose, order, park or drop, and a result revises the overview and every storyline it touches.
497
500
 
498
501
  `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
499
502
  card, short cards that write only their own front matter, a test on every line, a reason on every
500
503
  replacement, unchanged locks, sealed runs, results that still re-derive and were reviewed, use inside
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
504
+ the resources' amounts, what each storyline's scope table lists when the lab names its storylines, a decision behind every goal, question and metered amount, an experiment
502
505
  behind every answer, the method and the skills as the kit installed them, and a history that only
503
506
  grows. What it cannot read as this page describes (a mistyped folder, a list written as one value, a
504
507
  file that is not text) is a problem it reports; no command stops on it.
@@ -935,16 +938,16 @@ holds the line `launched`, else next, and `lab check` asks for the status to be
935
938
  reports a mission that breaks any of this, one whose `carries:` is not a decision, and a current mission whose
936
939
  decision is still open.
937
940
 
938
- **Papers.** `lab.toml` names the library's paper pages in a table, as library paths (the path under
941
+ **Storylines.** `lab.toml` names the library's storyline pages in a table, as library paths (the path under
939
942
  `content/`, as `see:` writes it):
940
943
 
941
944
  ```
942
- [papers]
945
+ [storylines]
943
946
  overview = "entries/where-the-results-stand"
944
- active = ["entries/paper-a", "entries/paper-b"]
947
+ active = ["entries/storyline-a", "entries/storyline-b"]
945
948
  ```
946
949
 
947
- `overview` is the page that keeps the whole trail; it is never an active paper. Each page under `active` is
950
+ `overview` is the page that keeps the whole trail; it is never an active storyline. Each page under `active` is
948
951
  in the library and marks the three cells of its scope table that list work, `data-scope="included"`,
949
952
  `data-scope="excluded"` and `data-scope="open"`, empty when it lists nothing:
950
953
 
@@ -960,7 +963,15 @@ a question or a step has one row on a page: where another row needs to mention i
960
963
  without its link. A question written in one row and a step under it written in another is allowed: the open
961
964
  question with its one finished step included is the usual case. A decision may be cited in any row. In
962
965
  `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.
966
+ every step under it.
967
+
968
+ While a storyline is active, one of the library's home maps (`home.maps` in `folio.yaml`) has a section headed
969
+ `<h2 id="current-storylines">Current storylines</h2>`, and its rows are the active storyline pages and nothing
970
+ else. A row is what folio counts as one: the first link, to `/content/<path>/`, of an item of a list whose classes
971
+ include `rows`, from the heading to the next `h2` or `h3`. A link in prose or in a row's reason is not a row. It
972
+ is the one place those pages have on a map; the overview and a retired storyline have theirs under other
973
+ headings. The library has one such section, and no map that is not a home map has one. A lab without
974
+ `[storylines]` has none of this.
964
975
 
965
976
  **Worked-out states.** A goal is open until `reached: true` makes it done or `dropped:` drops it. A
966
977
  question is waiting while the decision it came from is open, then open, then done with its answer; it
@@ -32,7 +32,7 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
32
32
  checks the solver leaves open", not "of 20". *The numbers and the budgets are held by `lab check`; whether a page
33
33
  can be read cold is judged, and the reviewer reads for it.*
34
34
  5. **Decide everything that is not direction or resources, and never wait idle.** Direction is the
35
- goals, the questions and the active papers. Resources are what `resources.toml` lists and how much. For those two,
35
+ goals, the questions and the active storylines. Resources are what `resources.toml` lists and how much. For those two,
36
36
  open a decision that says what was seen, the options and what you recommend, and work on what it
37
37
  does not hold. What a decision settled needs no further yes. Everything else is yours: decide,
38
38
  record it, go on. A mission (`missions/`) carries out what a settled decision settled across sessions, and approves
@@ -50,11 +50,12 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
50
50
  should never have to ask you. When you start on a card or move to another, log it:
51
51
  `lab log <id> doing "<what>" "<why now>"`. The line stands on the front page until a result, a
52
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,
53
+ 8. **Storylines drive the work; the record names no storyline.** The record is the trail, and no card names a storyline.
54
+ When the lab keeps storylines (the arguments its papers, talks or reports will be written from), its
55
+ library keeps one overview of the whole trail, and one page per active
56
+ storyline that is that storyline's argument and nothing else. A storyline page opens with its scope table: audience,
56
57
  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
58
+ order, park or drop follows the storylines' open rows and their reviewers' criticisms; when a result lands,
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
60
61
  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.12.0"
8
+ version = "1.14.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,7 @@ 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. Its numbers can then be cited nowhere: if a paper page lists it under included, `lab check`
47
+ differently. Its numbers can then be cited nowhere: if a storyline page lists it under included, `lab check`
48
48
  says so, and the author takes it off.
49
49
 
50
50
  When you read a plan, also read the card as someone who was not there. If an arm is named and not
@@ -43,13 +43,17 @@ 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
- 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).
46
+ 12. If the lab will argue its findings to an audience (a paper, a talk, a report), ask the operator which
47
+ storylines it aims at now, for whom and where (it is direction, and may stay empty). A storyline is the
48
+ argument such an output is written from, not the output itself. Write the overview page (for example
49
+ `entries/where-the-results-stand`) with folio's write skill: the words on one running example, the
50
+ workflow, the related work, and empty sections for the findings and the criticisms. For each storyline,
51
+ write `entries/storyline-<slug>`: its thesis, then the scope table (target audience and venues, core
52
+ thesis, experiments included, excluded or superseded, open), with the last three cells marked
53
+ `data-scope="included"`, `"excluded"` and `"open"`. Name them in `lab.toml` under `[storylines]`
54
+ (`overview`, `active`), and give each storyline page its row on a home map under the heading Current
55
+ storylines (`folio map add <map> <id> --section "Current storylines"`, which writes
56
+ `<h2 id="current-storylines">`); nothing else goes under that heading. No card names a storyline (method rule 8).
53
57
  13. Commit. Git is what holds the record: nothing is held before the first commit, and
54
58
  `lab check --strict` says so.
55
59
 
@@ -33,9 +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. 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.
36
+ running, what is next, what there is to discuss. No more than a screen. When the lab names its storylines,
37
+ lead with them: each active storyline by its title, with what its open row still needs, then the steps
38
+ serving no storyline.
39
39
  - `lab brief` is the question's page as text. Give it as it is, cut to what they asked. If what you
40
40
  want to say is not in it, the card is missing something: fix the card, then answer.
41
41
  - If the record does not say, say so. Never fill a gap from memory.
@@ -66,14 +66,14 @@ that resource or that experiment under `about:` before it is decided: `lab new d
66
66
  --about <resource or id>`. What a locked decision is about cannot be changed afterwards, and a
67
67
  resource's new amount names the decision in `from`.
68
68
 
69
- ## Papers
69
+ ## Storylines
70
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.
71
+ When the lab names its storylines, 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 storyline the
73
+ operator cares about first. Adding, splitting, merging or retiring a storyline is a decision like a question's:
74
+ `lab new decision "<what it is about>"`, with the storyline named in Seen and Decided by its page's title. Then
75
+ change the pages and `[storylines]` in `lab.toml` (the lab-work skill, The storylines and the overview). A
76
+ retired storyline's open work is parked or dropped in the same decision, or moved to another storyline's open row.
77
77
 
78
78
  ## When they decide something nobody raised
79
79
 
@@ -21,10 +21,10 @@ 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
24
+ When the lab names its storylines (`lab now` has a **Storylines** section), read each active storyline page's open row
25
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.
26
+ **Serving no active storyline** is a candidate to park or drop, which you bring to the operator in a decision,
27
+ or it belongs on a storyline's open row, which you add.
28
28
 
29
29
  When `lab now` lists a current mission and you were started to run it, or the operator asks to save,
30
30
  launch or resume one, follow the lab-mission skill: it starts sessions on the steps, and each of them
@@ -101,33 +101,40 @@ the plan in fixed boxes, then the steps and the record. Write the card for that
101
101
  - **Options are named in words, never letters.** "Read `sll` apart", not "(a)". A decision's options
102
102
  are a list, each item opening with its name in bold.
103
103
 
104
- ## The papers and the overview
104
+ ## The storylines and the overview
105
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".
106
+ When `lab.toml` names storylines (`[storylines]`), the library holds two kinds of page above the record (method
107
+ rule 8). The record itself never names a storyline: no card, no title, no So far says "Storyline A".
108
108
 
109
- - **The overview** (`overview`) keeps the whole trail, whatever paper it serves: the words on one running
109
+ - **The overview** (`overview`) keeps the whole trail, whatever storyline it serves: the words on one running
110
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.
111
+ it, and what runs now. Nothing is left off it for being off a storyline.
112
+ - **A storyline page** (each of `active`) is that storyline's technical argument, in its community's voice: the
113
+ page a paper, a talk or a report is later written from. It never talks about the lab, its method or itself
114
+ ("this page shows", "the lab's record"). It opens, under its thesis, with the scope table: target audience and
115
+ venues, core thesis, experiments included, experiments excluded or superseded, open experiments. The last
116
+ three cells carry `data-scope="included"`, `"excluded"` and `"open"`, and list ids as links
117
+ (`<a href="/lab/G1.Q1.4/">G1.Q1.4</a>`). Then: its words on one running example, its pipeline, the published work
118
+ of its community compared, its established results citing only included work, the criticisms its reviewers
119
+ will raise (for each: what is true in it, what the record shows, what remains to run), and last what remains
120
+ to run.
120
121
  - **A step or a question has one row on a page.** Where another row needs to mention it (excluded because
121
122
  a newer run superseded it), name it in words, without its link. A decision may be cited anywhere.
122
123
 
123
- When a result lands: bring the overview's findings up to date, then each paper whose argument it touches.
124
+ When a result lands: bring the overview's findings up to date, then each storyline whose argument it touches.
124
125
  If it supersedes an included run, move the old one to excluded and cite the new one. If it closes an open
125
126
  row, move it to included, or to excluded if it is void or no longer serves the argument. A result's review
126
127
  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
+ not list, and notes a storyline committed before a result about something it lists.
128
129
 
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.
130
+ A home map has the section Current storylines (`<h2 id="current-storylines">`): one row per active storyline
131
+ page, and nothing else. `lab check` holds that its rows and `active` name the same pages.
132
+
133
+ Adding, splitting, merging or retiring a storyline is direction: bring it to the operator (the lab-talk skill),
134
+ then change the pages, `[storylines]` and the Current storylines rows. A new storyline page gets its row with
135
+ `folio map add <map> <id> --section "Current storylines"`; a page that already has a place moves there with
136
+ `folio map move <id> --to <map>#current-storylines`. A retired storyline's page leaves `active` and stays in the
137
+ library: move its row under another heading (`folio map move <id> --to <map>#<heading>`).
131
138
 
132
139
  ## When to open a decision
133
140
 
@@ -143,7 +150,7 @@ parked question, and never take it up because it looks open: it is listed under
143
150
  1. `lab new decision "<what it is about>" --about <the goals, questions or experiments it concerns>`.
144
151
  2. On its card write **Seen** (what was observed, naming results), **Options** (a list of two or
145
152
  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
153
+ lab names its storylines, say which storyline's open row or criticism each option serves, by the storyline's exact
147
154
  title; an option that serves none says so. Put under `holds:` only the
148
155
  experiments that should not start before it is settled.
149
156
  3. Keep working on everything it does not hold. The lab-talk skill takes it to the operator and
@@ -223,7 +230,7 @@ until that decision is settled; after that it needs no further yes.
223
230
  before a result under it, or one it names. Give each result a label that says what it counts and
224
231
  of how many, in a set of cases the lab names once ("of the 20 checks the solver leaves open").
225
232
  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).
233
+ 11. When the lab names its storylines, revise them in the same sitting (next section).
227
234
 
228
235
  The outcome is worked out from the lines: you never write it.
229
236
 
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.12.0"
2
+ __version__ = "1.14.0"
@@ -3,7 +3,7 @@ from __future__ import annotations
3
3
 
4
4
  import glob, os, re
5
5
 
6
- from . import history, papers, record as R, runs as runs_, write
6
+ from . import history, 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"},
@@ -427,8 +427,8 @@ def run(lab, rederive=True):
427
427
  for t in sorted({t for t in terms if terms.count(t) > 1}):
428
428
  bad("glossary", "GLOSSARY.md", f"{t!r} is defined twice")
429
429
 
430
- # papers: each active paper's scope lists only what it may
431
- papers.check(lab, bad, notes)
430
+ # storylines: each active storyline's scope lists only what it may
431
+ storylines.check(lab, bad, notes)
432
432
 
433
433
  # clean: the plans and the store stay out of default searches
434
434
  ignore = R.read(f"{root}/.ignore") if os.path.exists(f"{root}/.ignore") else ""