lab-kit-cli 1.5.0__tar.gz → 1.6.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 (43) hide show
  1. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/.github/workflows/ci.yml +1 -1
  2. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/.github/workflows/release.yml +1 -1
  3. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/CHANGELOG.md +29 -0
  4. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/PKG-INFO +3 -3
  5. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/README.md +1 -1
  6. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/docs/model.md +89 -37
  7. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/method/METHOD.md +7 -3
  8. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/pyproject.toml +3 -3
  9. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/skills/lab-work/SKILL.md +18 -6
  10. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/src/lab_kit/__init__.py +1 -1
  11. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/src/lab_kit/checks.py +34 -13
  12. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/src/lab_kit/cli.py +4 -1
  13. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/src/lab_kit/history.py +26 -3
  14. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/src/lab_kit/record.py +77 -58
  15. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/src/lab_kit/runs.py +2 -2
  16. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/src/lab_kit/site.py +178 -126
  17. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/src/lab_kit/views.py +9 -9
  18. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/src/lab_kit/write.py +7 -7
  19. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tests/test_flow.py +7 -7
  20. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tests/test_integrity.py +1 -1
  21. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tests/test_needs.py +1 -1
  22. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tests/test_order.py +1 -1
  23. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tests/test_parked.py +5 -2
  24. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tests/test_refusals.py +2 -2
  25. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tests/test_site.py +34 -15
  26. lab_kit_cli-1.6.0/tests/test_states.py +118 -0
  27. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/.github/workflows/policy.yml +0 -0
  28. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/.gitignore +0 -0
  29. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/AGENTS.md +0 -0
  30. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/CLAUDE.md +0 -0
  31. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/CONTRIBUTING.md +0 -0
  32. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/LICENSE +0 -0
  33. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/agents/reviewer.md +0 -0
  34. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/skills/lab-mission/SKILL.md +0 -0
  35. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/skills/lab-review/SKILL.md +0 -0
  36. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/skills/lab-set-up/SKILL.md +0 -0
  37. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/skills/lab-talk/SKILL.md +0 -0
  38. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/src/lab_kit/supervise.py +0 -0
  39. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tests/test_held.py +0 -0
  40. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tests/test_mission.py +0 -0
  41. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tests/test_vocabulary.py +0 -0
  42. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tests/test_wording.py +0 -0
  43. {lab_kit_cli-1.5.0 → lab_kit_cli-1.6.0}/tools/import_run.py +0 -0
@@ -15,7 +15,7 @@ jobs:
15
15
  - uses: actions/setup-python@v5
16
16
  with:
17
17
  python-version: ${{ matrix.python }}
18
- # The site's tests need folio's views hook, in folio-kb 0.5.0 and later: the `site` extra brings it.
18
+ # The site's tests need folio's views hook, in folio-kb 0.7.0 and later: the `site` extra brings it.
19
19
  - name: Install lab-kit, and folio for the site's tests
20
20
  run: |
21
21
  python -m pip install --upgrade pip
@@ -22,7 +22,7 @@ jobs:
22
22
  with:
23
23
  python-version: "3.12"
24
24
  # Never publish untested: the same gate CI runs, and here the site's tests must run too, so
25
- # folio-kb 0.5.0 or later has to be on PyPI before lab-kit is released.
25
+ # folio-kb 0.7.0 or later has to be on PyPI before lab-kit is released.
26
26
  - run: python -m pip install -e ".[dev,site]"
27
27
  - run: python -m pytest -q -rs
28
28
  env:
@@ -1,5 +1,34 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.6.0
4
+
5
+ One set of states for every card, and the checks that keep a card from saying what the record does not. The site's
6
+ Now page is a dashboard and its rail is the tree of goals, questions and steps; the Graph page is gone. It needs
7
+ folio 0.7.0, whose rail draws the tree. The skill `lab-work` and the method changed: run `lab init` in a lab after
8
+ upgrading.
9
+
10
+ - **Seven states, the same for every kind of card:** open, waiting, running, parked, done, replaced, dropped. What
11
+ was `planned`, `active` or `in progress` is open or running; `built` and `reached` are done; `under discussion`
12
+ is waiting. A done card may carry a label: a question's answer (yes, no or mixed) and an experiment's outcome
13
+ (confirmed, refuted, unclear, or void when its results review failed). `lab show` and `lab now` print
14
+ `done, confirmed`. A decision is open or done.
15
+ - **A failed results review makes an experiment done and void,** not a step to replace. No page uses its numbers,
16
+ and what it made may still be used.
17
+ - **`lab answer <question> yes|no|mixed`.** An answer rests on a done experiment that is not void.
18
+ - **A need is met by a done step, and by a replaced or dropped experiment whose run finished:** a later step may
19
+ use what such an experiment made (a frozen program), and says so with `needs:`.
20
+ - **`drops:` on a decision** drops the questions and steps it names once it is settled, like `parks:`. It is frozen
21
+ with the rest of what a settled decision says.
22
+ - **`waiting_on:` is for what is outside the lab.** `lab check` refuses one that names a goal, question, step or
23
+ decision: that wait never clears by itself. Builds and readings may carry it too.
24
+ - **So far says what was learned.** `lab check` refuses a question's So far with words that say where a step
25
+ stands ("is running", "is next", "no result yet"), and reports a So far last committed before a `result` line
26
+ about a step under the question, or one it names. `lab log <step> result` says so.
27
+ - **The site.** Now shows what is live with a pulsing sign (runs, the current mission, what the agent is on), what
28
+ needs the operator, what is next for the agent in the agreed order, a tile per question with one sign per step,
29
+ the resources and the latest events. The rail nests goal, question and step, opens on the current page, marks each
30
+ with a sign for its state, folds what was replaced, dropped or set aside, and ends with a key.
31
+
3
32
  ## 1.5.0
4
33
 
5
34
  A closed mission is kept. In 1.4.0 `lab mission close` removed the mission's file, and with it the only account of
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.5.0
3
+ Version: 1.6.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
@@ -13,7 +13,7 @@ Requires-Dist: tomli; python_version < '3.11'
13
13
  Provides-Extra: dev
14
14
  Requires-Dist: pytest; extra == 'dev'
15
15
  Provides-Extra: site
16
- Requires-Dist: folio-kb>=0.5.0; extra == 'site'
16
+ Requires-Dist: folio-kb>=0.7.0; extra == 'site'
17
17
  Description-Content-Type: text/markdown
18
18
 
19
19
  # lab-kit
@@ -33,7 +33,7 @@ record to the operator as a live site: `lab_kit.site` draws the pages, and nothi
33
33
 
34
34
  ```
35
35
  Goal what the lab wants to be able to say
36
- Question a yes-or-no question: what we expect, what would prove us wrong, what we know so far
36
+ Question a question answered yes, no or mixed: what we expect, what would prove us wrong, what we know so far
37
37
  Build something an experiment needs that has to be made first
38
38
  Reading a look at what already exists: it suggests, and never confirms
39
39
  Experiment what is compared, what would confirm, what would refute; then what was found
@@ -15,7 +15,7 @@ record to the operator as a live site: `lab_kit.site` draws the pages, and nothi
15
15
 
16
16
  ```
17
17
  Goal what the lab wants to be able to say
18
- Question a yes-or-no question: what we expect, what would prove us wrong, what we know so far
18
+ Question a question answered yes, no or mixed: what we expect, what would prove us wrong, what we know so far
19
19
  Build something an experiment needs that has to be made first
20
20
  Reading a look at what already exists: it suggests, and never confirms
21
21
  Experiment what is compared, what would confirm, what would refute; then what was found
@@ -9,14 +9,36 @@ A lab is a tree, and the decisions that shaped it.
9
9
 
10
10
  | Thing | What it says | States |
11
11
  | --- | --- | --- |
12
- | **Goal** | A short name, what the lab wants to be able to say, and the claim: what we would report if the questions come out as expected, and against whose work. | active, reached, dropped |
13
- | **Question** | A short name, and a yes-or-no question under a goal, written in full: why we ask it, how we would know, what we expect, what would prove us wrong, what we know so far. | under discussion, open, parked, yes, no, dropped |
14
- | **Experiment** | One thing tried to answer a question. What it is for. Before the run: what is compared, each arm by name with what it is, the cases it runs on, what would confirm, what would refute. After: what was found, what it means. | planned, running, waiting, done (confirmed, refuted or unclear), review failed, replaced, dropped |
15
- | **Build** | One thing an experiment needs that has to be made first: what it is for, how it works in plain words, and how we know it works. | planned, in progress, built, dropped |
16
- | **Reading** | One look at what already exists: sealed runs, traces, the benchmark's own definitions. What it looks at; then what was seen and what that suggests. It sets no bar in advance, so it can suggest and never confirm. | planned, in progress, done, dropped |
12
+ | **Goal** | A short name, what the lab wants to be able to say, and the claim: what we would report if the questions come out as expected, and against whose work. | open, done, dropped |
13
+ | **Question** | A short name, and a question under a goal, answered yes, no or mixed, written in full: why we ask it, how we would know, what we expect, what would prove us wrong, what we know so far. | open, waiting, parked, done (yes, no or mixed), dropped |
14
+ | **Experiment** | One thing tried to answer a question. What it is for. Before the run: what is compared, each arm by name with what it is, the cases it runs on, what would confirm, what would refute. After: what was found, what it means. | open, waiting, running, done (confirmed, refuted, unclear or void), replaced, dropped |
15
+ | **Build** | One thing an experiment needs that has to be made first: what it is for, how it works in plain words, and how we know it works. | open, waiting, running, done, dropped |
16
+ | **Reading** | One look at what already exists: sealed runs, traces, the benchmark's own definitions. What it looks at; then what was seen and what that suggests. It sets no bar in advance, so it can suggest and never confirm. | open, waiting, running, done, dropped |
17
17
  | **Run** | One try at producing what an experiment demands: when, on which resource, what changed since the run before, how it ended, what it used. An experiment has one or more, until one finishes. | running, finished, failed |
18
18
  | **Result** | One number from a finished run: a plain label, how it reads, and the command that prints it again. | |
19
- | **Decision** | One thing discussed with you and settled: first what there is to discuss, then what was decided and why. | open, decided |
19
+ | **Decision** | One thing discussed with you and settled: first what there is to discuss, then what was decided and why. | open, done |
20
+
21
+ **One set of states for everything.** A goal, a question, an experiment, a build and a reading use the same
22
+ seven words, and each type uses only those it can be in:
23
+
24
+ | State | Means | Goal | Question | Experiment | Build | Reading |
25
+ | --- | --- | --- | --- | --- | --- | --- |
26
+ | open | not finished, and free to move | yes | yes | yes | yes | yes |
27
+ | waiting | held by a step it needs, an open decision, or something outside the lab | | yes | yes | yes | yes |
28
+ | running | work under way | | | yes | yes | yes |
29
+ | parked | set aside by a decision; may come back | | yes | | | |
30
+ | done | finished; it carries a label where its type has one | yes | yes | yes | yes | yes |
31
+ | replaced | redone by a newer experiment | | | yes | | |
32
+ | dropped | will not be done | yes | yes | yes | yes | yes |
33
+
34
+ Two types carry a label on done. A question's is its answer: **yes**, **no** or **mixed**, the answer to
35
+ the question as asked, with one sentence on what it rests on. Mixed says which part held and which did
36
+ not, and usually leads to a narrower question. An answer is a finding, never good or bad: no is not a
37
+ failure. A question has no "unclear": while the evidence cannot answer it, it is open. An experiment's
38
+ label is its outcome: **confirmed**, **refuted** or **unclear**, read against the bars set before the
39
+ run, or **void** when its results review failed, so that its numbers cannot be cited. A decision is open,
40
+ then done; a mission's `status:` (next, current, done, stopped) reads on the pages as open, running,
41
+ done and dropped.
20
42
 
21
43
  Goal, question, experiment, run, result: each sits inside the one before it. Ids spell the path: `G1`,
22
44
  `G1.Q2`, `G1.Q2.3`, and a result is `G1.Q2.3:attack-success`. Decisions are `D1`, `D2`.
@@ -94,7 +116,7 @@ what it means and what was found, then says how many bars were met and names the
94
116
  outcome. There are no confidence numbers and no score sheet. A caveat the results raise goes in
95
117
  *Means*; what the experiment could never show is its Limits, written before the run.
96
118
 
97
- A build has no lock, no lines and no result. It ends as built, naming its commits and its tests.
119
+ A build has no lock, no lines and no result. It is done once it names its commits and its tests.
98
120
 
99
121
  A reading has no lock, no lines, no run and no review. It exists because much of what a lab learns
100
122
  comes from reading what it already has: why each failure failed, which tasks a defence costs, what
@@ -203,10 +225,11 @@ Each arrow is a command that refuses when the step before it is missing. You see
203
225
  or from a trial run that measured it. A trial that only showed the apparatus starts does not count.
204
226
  5. a failed run's partial numbers were read before the apparatus was changed for the next run.
205
227
 
206
- A plan review that fails is fixed before the lock, and read again. A results review that fails does
207
- not finish the experiment: its outcome is not shown and no card may name its results. The plan and
208
- the rows stay as they are. The remedy is a new experiment that names the one it replaces; the site
209
- folds the old one under it, and the old results keep re-deriving.
228
+ A plan review that fails is fixed before the lock, and read again. A results review that fails ends
229
+ the experiment as done with the outcome **void**: its run finished, but no card may name its results.
230
+ The plan and the rows stay as they are. A new experiment may name the one it replaces; the site then
231
+ folds the old one under it, and the old results keep re-deriving. What the void experiment made (a
232
+ frozen program, a built file) may still be used by later steps, which name it under `needs:`.
210
233
 
211
234
  A card never types a result's number. It names the result, and the value is filled in when the card is
212
235
  shown, written the way its row says it reads: a share as a percentage, a difference between two shares
@@ -243,11 +266,15 @@ approval: an experiment added later under a settled question is the agent's to p
243
266
 
244
267
  **Parking a question.** A question can be set aside without being dropped: not now, perhaps later. A settled
245
268
  decision parks it by listing it under `parks:`, and lists it under `about:` too. The decision's Decided text says
246
- why, and what would bring it back. A parked question leaves Now, the rail and the graph, as a dropped one does.
269
+ why, and what would bring it back. A parked question leaves Now's map and the rail's list of live questions, as a dropped one does.
247
270
  Nothing under it moves: `lab new` refuses a step under it, and `lab lock` and `lab run` refuse its experiments. It
248
271
  comes back only by a later settled decision that lists it under `unparks:`. The last settled decision, by number,
249
272
  that parks or brings back a question has the say. An open decision parks nothing yet. Drop a question that will
250
- never come back, with `dropped: <why>` on its card; park one that may. A goal is closed by `reached: true` or
273
+ never come back, with `dropped: <why>` on its card; park one that may.
274
+
275
+ **Dropping by a decision.** A settled decision may drop steps and questions by listing them under `drops:`
276
+ (each also under `about:`). A step or a question a settled decision drops is dropped, with that decision as
277
+ its reason, whether or not its card says so: the card needs no edit, and none can be forgotten. A goal is closed by `reached: true` or
251
278
  `dropped: <why>`, and a dropped goal drops every question under it.
252
279
 
253
280
  **The order of the work.** What the agent takes up first is agreed with you, and a settled decision records
@@ -265,12 +292,12 @@ work (a decision with a new `order:`), stop a run. Say it, and the agent records
265
292
  you as for the agent: a locked plan is changed by a new experiment that replaces it, and an outcome is
266
293
  worked out from the results, not decided.
267
294
 
268
- **A settled decision stays as it was settled.** Its `decided:`, its `about:`, its `parks:`, its `unparks:`, its `order:` and its Decided text never
295
+ **A settled decision stays as it was settled.** Its `decided:`, its `about:`, its `parks:`, its `unparks:`, its `drops:`, its `order:` and its Decided text never
269
296
  change once committed; a change of mind is a new decision. `lab check` holds this against the lab's
270
297
  history. So a decision cannot be made, afterwards, to be about something it never discussed.
271
298
 
272
299
  The agent decides everything else and records each choice in the log. It drops an experiment or a
273
- build that will not be done, saying why. It marks a question yes or no itself, with `lab answer`, and
300
+ build that will not be done, saying why. It answers a question itself, yes, no or mixed, with `lab answer`, and
274
301
  the command refuses while an experiment of that question is neither done, replaced nor dropped, and
275
302
  when no experiment of it is done: a reading alone answers nothing. `lab check` asks the same of every
276
303
  answered question, and that the log holds the line `lab answer` wrote. It never asks you to check
@@ -356,7 +383,7 @@ missions before it takes a machine.
356
383
  `log` and `close` may leave out the mission while only one is current, and refuse to guess when several are.
357
384
  `lab now` names every open mission under **Right now**. A mission is not part of the record: `lab check` checks its
358
385
  form (section 9) and that it carries a decision, and does not hold it against history; the site does not draw
359
- it; its log is not the lab's log. The lab-mission skill says what to do on each step.
386
+ it, except that Now names the current mission and the last line of its log; its log is not the lab's log. The lab-mission skill says what to do on each step.
360
387
 
361
388
  The log is one file. Every line carries its time. A line is one of five kinds: a decision was
362
389
  recorded, the agent decided, a result, something is stuck, and what the agent is starting on now.
@@ -431,8 +458,17 @@ A folder is named after its card's title, so a short title gives a short path.
431
458
 
432
459
  ## 7. The site
433
460
 
434
- Now, Graph, a page per goal, question, experiment, build, reading and decision, Decisions, Log,
435
- Resources, Glossary. Every page has the copy-path control.
461
+ Now (the dashboard), a page per goal, question, experiment, build, reading and decision, Decisions,
462
+ Log, Resources, Glossary. Every page has the copy-path control.
463
+
464
+ **The rail** on the left of every page is the lab as a tree: each goal, its questions under it, and
465
+ each question's steps under that. A row shows a mark for its type (G, Q, E, B, R), its short id, its
466
+ title and a mark for its state, whose colour and shape follow the state and, on done, the label; the
467
+ word is on hover. A running step's mark pulses. A goal or a question opens and closes, and a closed
468
+ one shows how many of the steps under it are in each state. The page being read is always opened in
469
+ place and marked, with its goal, its question and its siblings in view. A question's replaced and
470
+ dropped steps fold into one line at its end; a goal's parked and dropped questions into one line at
471
+ its end.
436
472
 
437
473
  **How a page of a card reads.** Every page of a goal, a question or a step reads in the same order:
438
474
 
@@ -466,11 +502,13 @@ and where each stands, what it costs, what it cannot show, where to look. Half o
466
502
  the same briefing as text, which is what the agent says in chat when asked what is going on: the page
467
503
  and the answer in chat cannot differ. An experiment's page is the evidence behind one step.
468
504
 
469
- **Now** is read top to bottom in the order the operator asks: what is happening at this moment and
470
- how fresh the record is; what there is to discuss with you; what is next and who moves it, in the agreed
471
- order of the work and naming the decision that set it; where each
472
- question stands (what is known so far, and nothing else); the latest events; what is left of each
473
- resource. Nothing on it is static text except one line per goal.
505
+ **Now** is the dashboard, read top to bottom in the order the operator asks, and all of it worked out:
506
+ what is live at this moment (each run going, the current mission with the last line of its log, what
507
+ the agent says it is on), each with a pulsing mark, and when the record last moved; what needs you (the
508
+ open decisions) and what is next for the agent, in the agreed order of the work; the map, one row per
509
+ goal with how many of its questions are answered, and one tile per live question with its state, its
510
+ answer and one mark per step in tree order; what each resource has used of its grant, as a bar; the
511
+ latest events. There is no graph page: the rail is the tree and Now is the map.
474
512
 
475
513
  **An example on every question.** A question's page carries one case, step by step, as a numbered
476
514
  list that says who does what: the user, the agent, the tools, the gate, the scorer. A real episode
@@ -479,7 +517,7 @@ each role, states the design before the approximation, and lists its vocabulary:
479
517
  uses the same way, each drawn with the glossary's definition.
480
518
 
481
519
  **What was set aside** stays in the record: a dropped goal or question, and a parked question, keeps its
482
- card and its page, and leaves Now, the rail and the graph. Now lists it apart, under Set aside: each parked
520
+ card and its page, and leaves Now's map and the rail's live lists. Now lists it apart, under Set aside: each parked
483
521
  question with the decision that parked it and the first sentence of what was decided, then the dropped
484
522
  questions and the closed goals, folded. A goal's page folds its parked and its dropped questions; a parked
485
523
  question's page says, at the top, which decision parked it and why. `lab now` lists the parked questions in
@@ -537,17 +575,17 @@ and its sealed runs across as what they were.
537
575
  **A card** is front matter, then its description as a paragraph, then `## Slot` sections. It never
538
576
  holds an id, a state or an outcome. Every file of a lab is UTF-8 text; line ends of either kind
539
577
  read the same, and so hash the same where a review is bound to a file. The front matter sits between
540
- the first two lines that are exactly `---`. A key that holds a list (`needs`, `uses`, `see`, `about`, `holds`, `parks`, `unparks`, `order`, `commits`,
578
+ the first two lines that are exactly `---`. A key that holds a list (`needs`, `uses`, `see`, `about`, `holds`, `parks`, `unparks`, `drops`, `order`, `commits`,
541
579
  `tests`) is written as one, `[a, b]`; every other key holds one value.
542
580
 
543
581
  | Card | Front matter | Slots (word budget) |
544
582
  | --- | --- | --- |
545
583
  | `goal.md` | `title:`, `from:` (its decision); `reached: true`; `dropped: <why>` | description (70), Claim (90), Example: the idea in one case, from the reader's own domain (260), Approach: the design, how this lab approximates it, and where it knowingly differs (340), Roles: a list, `- <role>: <who plays it and what it does>` (170), Vocabulary: a list of names only, `- <term>`, the few words every card uses the same way; each is a term of `GLOSSARY.md`, which defines it (260) |
546
- | `question.md` | `title:` (a short name), `asks:` (the question in full), `from:`, `needs:`; `dropped: <why>`; `answer:` and `answered:` are written by `lab answer` | description: why we ask (150), How we would know (180), Example: one case step by step, a numbered list (380), We expect (70), Wrong if (70), So far (220) |
547
- | `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:`, `dropped: <why>` | description (80), So far: optional, everything observed since the plan was written (300), Compares: the comparison, in a sentence or a numbered list of the whole work (300), Arms (260), Cases (120), Confirmed if (150), Refuted if (110), Outcomes (260), Limits (160), Found (180), Means (150) |
548
- | `reading.md` | `title:`, `needs:`, `dropped: <why>` | description (70), Looks at: what, and where it is (120), Seen (360), Suggests (150) |
549
- | `build.md` | `title:`, `needs:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
550
- | `D<n>-<slug>.md` | `title:`, `about:` (the goals, questions, experiments or resources it concerns), `date:`, `holds:`; `parks:` and `unparks:` (questions, each also under `about:`); `order:` (goals, questions and steps, first to last); `decided: {date, with}` is written by `lab decide` | Seen (150), Options: a list, one option an item (200), Recommendation (80), Decided (150), Note: optional, what a reader of the pages it is about must know from it (60) |
584
+ | `question.md` | `title:` (a short name), `asks:` (the question in full), `from:`, `needs:`; `dropped: <why>`; `answer:` (yes, no or mixed) and `answered:` are written by `lab answer` | description: why we ask (150), How we would know (180), Example: one case step by step, a numbered list (380), We expect (70), Wrong if (70), So far (220) |
585
+ | `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:` (something outside the lab; never a goal, question, step or decision of the lab, which go under `needs:` and are waited on by themselves), `dropped: <why>` | description (80), So far: optional, everything observed since the plan was written (300), Compares: the comparison, in a sentence or a numbered list of the whole work (300), Arms (260), Cases (120), Confirmed if (150), Refuted if (110), Outcomes (260), Limits (160), Found (180), Means (150) |
586
+ | `reading.md` | `title:`, `needs:`, `waiting_on:`, `dropped: <why>` | description (70), Looks at: what, and where it is (120), Seen (360), Suggests (150) |
587
+ | `build.md` | `title:`, `needs:`, `waiting_on:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
588
+ | `D<n>-<slug>.md` | `title:`, `about:` (the goals, questions, experiments or resources it concerns), `date:`, `holds:`; `parks:` and `unparks:` (questions, each also under `about:`); `drops:` (steps and questions, each also under `about:`); `order:` (goals, questions and steps, first to last); `decided: {date, with}` is written by `lab decide` | Seen (150), Options: a list, one option an item (200), Recommendation (80), Decided (150), Note: optional, what a reader of the pages it is about must know from it (60) |
551
589
 
552
590
  **Why these budgets.** A budget is a ceiling. In 1.3.0 the budgets of the slots that hold a table or a
553
591
  numbered list (an experiment's Compares, Cases, Outcomes and So far, a question's So far and How we
@@ -563,6 +601,14 @@ plan, so it may change after the lock; a card written before 1.3.0 may leave it
563
601
  carry a Note: one or two sentences a reader of the pages it is about must know. While a card's So far
564
602
  says nothing, its page shows there the Notes of the settled decisions about it.
565
603
 
604
+ **So far says what was learned, never where a step stands.** The pages draw each step's state from the
605
+ record, so a So far that says a step "is running", "is next" or has "no result yet" can only go stale,
606
+ and `lab check` reports those words in a question's So far. It also reports a question whose card was
607
+ last committed before the newest `result` line about a step under it, or about a step its So far names:
608
+ the result came in and the question was not brought up to date. `lab log <step> result` says which
609
+ question to bring up to date. Where git cannot tell (no history, the card changed and not committed),
610
+ nothing is reported.
611
+
566
612
  **A picture.** Any goal, question, experiment, build or reading may have a `picture.svg` beside its
567
613
  card. It is drawn inline at the top of its page, after the title and the lead. It shows the whole
568
614
  work as numbered steps: what goes in, who does what, the checks, the tools, how it is counted, the
@@ -660,7 +706,7 @@ A test is a result's name, one of `<`, `<=`, `>`, `>=`, and a number. At most si
660
706
  **A named result** on a card is `{name}` inside its own experiment and `{G1.Q1.2:name}` elsewhere.
661
707
 
662
708
  **`results.tsv`** is tab-separated: `name`, `label` (what the number is, as a phrase that stands on its
663
- own: what is counted, out of what, under which arm, with no "that" or "the same" pointing at another row), `value` (a
709
+ own: what is counted, out of how many and of which set of cases, named the same way on every row that uses it, under which arm, with no "that" or "the same" pointing at another row), `value` (a
664
710
  plain number), `reads` (`percent` for a share, `points` for a difference between two shares, or empty),
665
711
  `versus` (what it is compared with), `command` (run from the lab's root with `RUN` set to the finished
666
712
  run's folder; prints `value` exactly, and reads `$RUN`, or it would not be printing from the sealed
@@ -771,20 +817,26 @@ holds the line `launched`, else next, and `lab check` asks for the status to be
771
817
  reports a mission that breaks any of this, one whose `carries:` is not a decision, and a current mission whose
772
818
  decision is still open.
773
819
 
774
- **Worked-out states.** A question is under discussion while the decision it came from is open, then
775
- open, then yes or no; it is parked while the last settled decision that parks or brings it back parks it; a page calls an open question with nothing under it "not started". A build is in
776
- progress once the log has a line about it, and built once it names its commits. An experiment whose
777
- results review failed shows as review failed until it is replaced or dropped.
820
+ **Worked-out states.** A goal is open until `reached: true` makes it done or `dropped:` drops it. A
821
+ question is waiting while the decision it came from is open, then open, then done with its answer; it
822
+ is parked while the last settled decision that parks or brings it back parks it. A step is waiting while
823
+ something holds it: a step it needs, an open decision, its question or goal not being open, or its
824
+ `waiting_on:`. A build or a reading is running once the log has a line about it; a build is done once
825
+ it names its commits, a reading once it says what was seen and what it suggests. An experiment is running
826
+ while a run of it is going, and done once its results are reviewed (its label is the outcome) or its
827
+ results review failed (its label is void).
778
828
 
779
829
  **What a step needs.** `needs:` on an experiment, a build or a reading names other steps, anywhere in
780
830
  the tree: under its own question or another, before it or after it. A step is not the agent's to move
781
- while one it needs is neither done nor built, and `lab lock` and `lab run` refuse it until then. Each
831
+ while one it needs is not done, and `lab lock` and `lab run` refuse it until then. An experiment that
832
+ was replaced or dropped after a run of it finished made what it made: a need on it is met, and its page
833
+ lists the steps that use it. Each
782
834
  step's state is worked out after the state of everything it needs, wherever that sits, so the order
783
835
  of the cards changes nothing: a build under the second question that needs a reading under the third
784
836
  moves as soon as that reading is done. Every view says the same: `lab now`, `lab show`, `lab brief`,
785
837
  and the site's pages and rail. Steps that need each other in a circle are a problem `lab check`
786
838
  reports. Until the circle is broken none of them moves, whatever the others' states, and each says
787
- which of its needs leads back to it. A step that needs one that is dropped or replaced would wait
839
+ which of its needs leads back to it. A step that needs one that was dropped or replaced before any run of it finished would wait
788
840
  for ever, so what it waits on says so, and says what to do: remove the need or replace it. A need
789
841
  that names nothing in the lab, or something that is not a step, holds the step in `lab lock` and
790
842
  `lab run` as `lab check` reports it. A question's `needs:` names the questions it builds on, for its
@@ -13,8 +13,9 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
13
13
  `lab check`; the review itself is judged.*
14
14
  3. **A miss is recorded like a hit, and nothing recorded is edited. What a locked plan demands is never
15
15
  changed; its words may be made clearer.** A failed run is kept. A refuted line is an outcome like
16
- any other. A changed plan, a failed review or a partial score is a new experiment that replaces the
17
- old one and says why in a sentence. What an experiment demands (each bar's role, result, comparison and
16
+ any other. A changed plan or a partial score is a new experiment that replaces the old one and
17
+ says why in a sentence. An experiment whose results review failed is done and void: no page uses its
18
+ numbers, and what it made may still be used through `needs:`. What an experiment demands (each bar's role, result, comparison and
18
19
  number, each arm's name, the resources it uses) is locked once; a clearer word keeps its meaning,
19
20
  and a reviewer who did not write it reads it. It is run until one run finishes, and a run after a fix says what changed. Once a
20
21
  run has finished, nothing more runs under it. Every run is listed in the experiment's `runs.tsv`,
@@ -24,7 +25,10 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
24
25
  4. **Write for a reader who was not there.** Every page stands on its own: it says what each thing it
25
26
  mentions is, names each arm of an experiment and what it is, names another page by its exact
26
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
27
- worked out, never written. *The numbers and the budgets are held by `lab check`; whether a page
28
+ worked out, never written, and So far says what was learned, never where a step stands. Every
29
+ card has one of the same states: open, waiting, running, parked, done, replaced or dropped. A
30
+ number's label says what it counts and of how many, in one set of cases named once: "of the 20
31
+ checks the solver leaves open", not "of 20". *The numbers and the budgets are held by `lab check`; whether a page
28
32
  can be read cold is judged, and the reviewer reads for it.*
29
33
  5. **Decide everything that is not direction or resources, and never wait idle.** Direction is the
30
34
  goals and the questions. Resources are what `resources.toml` lists and how much. For those two,
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  dynamic = ["readme"]
7
7
  name = "lab-kit-cli"
8
- version = "1.5.0"
8
+ version = "1.6.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" }]
@@ -14,9 +14,9 @@ dependencies = ["pyyaml", "tomli; python_version < '3.11'"]
14
14
 
15
15
  [project.optional-dependencies]
16
16
  dev = ["pytest"]
17
- # folio serves the operator's site and lab_kit.site draws its pages, through the views hook of folio-kb 0.5.0.
17
+ # folio serves the operator's site and lab_kit.site draws its pages, through the views hook of folio-kb 0.7.0.
18
18
  # The `lab` command itself needs no folio.
19
- site = ["folio-kb>=0.5.0"]
19
+ site = ["folio-kb>=0.7.0"]
20
20
 
21
21
  [project.urls]
22
22
  Homepage = "https://github.com/pierg/lab-kit"
@@ -70,7 +70,7 @@ the plan in fixed boxes, then the steps and the record. Write the card for that
70
70
  no result: a number observed never goes in a picture. Use the site's colours (`var(--ink)`,
71
71
  `var(--ink-2)`, `var(--accent)`, `var(--surface)`, `var(--rule)`, `var(--sans)`) and never a fixed
72
72
  colour, so it reads in light and dark. Keep its text at least 12 pixels at its own width.
73
- - **What we know so far holds everything observed.** The card's `## So far`: where it stands, what
73
+ - **What we know so far holds everything observed.** The card's `## So far`: what was learned, what
74
74
  was learned after the plan was written, later decisions and what they change, reference runs. On
75
75
  an experiment it sits outside the plan, so you keep it current after the lock. When a decision
76
76
  changes how a node is read, give the decision a `## Note` of one or two sentences: a node whose So
@@ -178,6 +178,10 @@ until that decision is settled; after that it needs no further yes.
178
178
  9. Once the review has passed, write **Found** and **Means** on the card. Name each result instead
179
179
  of typing its number: `{attack-success}`. It is shown the way its row says it reads. Bring the
180
180
  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}`.
181
+ So far says what was learned, never where a step stands ("is running", "is next", "no result yet"):
182
+ the pages draw each step's state. `lab check` reports a question's So far that was last committed
183
+ before a result under it, or one it names. Give each result a label that says what it counts and
184
+ of how many, in a set of cases the lab names once ("of the 20 checks the solver leaves open").
181
185
  10. `lab log <experiment> result "<what was found, in a sentence, without numbers>" "<so what>"`.
182
186
 
183
187
  The outcome is worked out from the lines: you never write it.
@@ -232,8 +236,10 @@ repository, tests first. When it works, put `commits:` and `tests:` on the card
232
236
 
233
237
  ## When all experiments of a question are done
234
238
 
235
- Decide whether they answer it. `lab answer <question> yes|no "<what the answer rests on>"`, and bring
236
- **So far** up to date. If they do not answer it, add the next experiment. An answer usually changes
239
+ Decide whether they answer it. `lab answer <question> yes|no|mixed "<what the answer rests on>"`, and
240
+ bring **So far** up to date. Yes and no say whether what the question expected held; mixed says part
241
+ held and part did not, and the sentence says which. An answer rests on a done experiment that is not
242
+ void. If they do not answer it, add the next experiment. An answer usually changes
237
243
  what should come next: open a decision.
238
244
 
239
245
  ## When something is in the way
@@ -241,9 +247,15 @@ what should come next: open a decision.
241
247
  - **It is yours to decide.** Decide, `lab log <id> agent "<what you decided>" "<why>"`, go on.
242
248
  - **It is the operator's** (direction or resources). Open a decision, then work on what it does not
243
249
  hold.
244
- - **It waits on something outside the lab.** Put `waiting_on: <what>` on the card, log a `stuck`
245
- line, and remove both when it clears.
246
- - **It will not be done.** Put `dropped: <why>` on the card and log it.
250
+ - **It waits on something outside the lab** (an account, a person, a machine being repaired). Put
251
+ `waiting_on: <what>` on the card, log a `stuck` line, and remove both when it clears. A wait on the
252
+ lab's own work is a `needs:`, or a decision's `holds:`: `lab check` refuses a `waiting_on:` that
253
+ names a goal, question, step or decision.
254
+ - **It will not be done.** Put `dropped: <why>` on the card and log it. When a decision drops it,
255
+ the decision lists it under `drops:`, and the card needs nothing more.
256
+ - **A later step uses what a replaced or void step made** (a frozen program, a data set). Put the
257
+ step under `needs:`: a need is met by a done step, and by a replaced or dropped experiment whose
258
+ run finished.
247
259
  - **A run's process died.** `lab runs close <run> "<why>"`. It stops whatever the run left going and
248
260
  reads the run's `used.json`. If the run used a metered resource and wrote none, say what it used:
249
261
  `--used <resource>=<amount>`.
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.5.0"
2
+ __version__ = "1.6.0"
@@ -9,12 +9,16 @@ KEYS = { # what a card's front matter may hold; a state is never among them
9
9
  "goal": {"title", "from", "reached", "dropped", "see"},
10
10
  "question": {"title", "asks", "from", "needs", "answer", "answered", "dropped", "see"},
11
11
  "experiment": {"title", "needs", "uses", "override", "replaces", "because", "cost", "waiting_on", "dropped", "see"},
12
- "build": {"title", "needs", "commits", "tests", "dropped", "see"},
13
- "reading": {"title", "needs", "dropped", "see"},
14
- "decision": {"title", "about", "date", "holds", "parks", "unparks", "order", "decided", "see"},
12
+ "build": {"title", "needs", "commits", "tests", "waiting_on", "dropped", "see"},
13
+ "reading": {"title", "needs", "waiting_on", "dropped", "see"},
14
+ "decision": {"title", "about", "date", "holds", "parks", "unparks", "drops", "order", "decided", "see"},
15
15
  }
16
16
 
17
17
 
18
+ LAB_ID = re.compile(r"\b(G\d+(?:\.Q\d+(?:\.\d+)?)?|D\d+)\b") # a goal, a question, a step or a decision of the lab
19
+ STATE_WORDS = ("is running", "are running", "currently running", "no result yet", "is next", "are next", "is waiting", "is planned") # where a step stands, which the pages draw
20
+
21
+
18
22
  def run(lab, rederive=True):
19
23
  """Every problem, notes on what could not be checked here, and whether anything was left unchecked."""
20
24
  problems, notes, unchecked = list(lab.problems), [], False
@@ -89,13 +93,13 @@ def run(lab, rederive=True):
89
93
  for need in q["needs"]:
90
94
  if nodes.get(need, {}).get("type") != "question":
91
95
  bad("links", q["path"], f"needs {need}, which is not a question")
92
- if q.get("answer") is not None and q.get("answer") not in ("yes", "no"):
93
- bad("cards", q["path"], "`answer:` is yes or no, written by `lab answer`")
94
- if q.get("answer") in ("yes", "no"): # what `lab answer` requires holds for an answer however it got on the card
95
- waiting = [x["id"] for x in q["items"] if x["state"] not in ("done", "built", "replaced", "dropped")]
96
+ if q.get("answer") is not None and q.get("answer") not in R.ANSWERS:
97
+ bad("cards", q["path"], "`answer:` is yes, no or mixed, written by `lab answer`")
98
+ if q.get("answer") in R.ANSWERS: # what `lab answer` requires holds for an answer however it got on the card
99
+ waiting = [x["id"] for x in q["items"] if x["state"] not in R.CLOSED]
96
100
  if waiting:
97
101
  bad("questions", q["path"], f"is answered while {', '.join(waiting)} is not done")
98
- if not any(x["state"] == "done" and x["type"] == "experiment" for x in q["items"]):
102
+ if not any(x["state"] == "done" and x["type"] == "experiment" and x["label"] != "void" for x in q["items"]):
99
103
  bad("questions", q["path"], "is answered with no finished experiment to rest the answer on; a reading suggests and answers nothing")
100
104
  if not R.day(q.get("answered")) or not any(l["about"] == q["id"] and l["kind"] == "agent" and l["what"].startswith(f"Answered {q['id']} {q['answer']}.") for l in lab.lines):
101
105
  bad("questions", q["path"], "its answer was not recorded by `lab answer`: the log holds no line for it, or the card no `answered:` day")
@@ -105,6 +109,17 @@ def run(lab, rederive=True):
105
109
  for need in x["needs"]:
106
110
  if nodes.get(need, {}).get("type") not in R.STEPS:
107
111
  bad("links", x["path"], f"needs {need}, which is not an experiment, a build or a reading")
112
+ named = sorted(set(LAB_ID.findall(str(x.get("waiting_on") or ""))) & set(nodes))
113
+ if named: # a wait on the lab's own work clears by itself only through `needs:` or a decision's `holds:`
114
+ bad("cards", x["path"], f"`waiting_on:` names {', '.join(named)}, which is part of the lab: put a step under `needs:`, and let a decision hold it with `holds:`; `waiting_on:` is for something outside the lab")
115
+ for q in lab.questions: # So far says what was learned; the pages say where each step stands
116
+ so_far = R.flat(q["slots"].get("So far", ""))
117
+ for words in STATE_WORDS:
118
+ if re.search(rf"\b{words}\b", so_far, flags=re.I):
119
+ bad("questions", q["path"], f"So far says {words!r}: the pages show where each step stands, so So far says only what was learned")
120
+ break
121
+ for q, step, at in history.stale_so_far(lab):
122
+ bad("questions", q["path"], f"So far was last committed before the result of {step} ({at}): bring it up to date with what that result taught")
108
123
  for n in lab.questions + lab.items: # nothing needs itself, directly or through what it needs
109
124
  seen, todo = set(), list(n["needs"])
110
125
  while todo:
@@ -131,6 +146,11 @@ def run(lab, rederive=True):
131
146
  bad("links", d["path"], f"{key} names {i}, which is not under `about:`: a decision that parks a question or brings it back is about it")
132
147
  for i in sorted(set(d["parks"]) & set(d["unparks"])):
133
148
  bad("links", d["path"], f"both parks and unparks {i}")
149
+ for i in d["drops"]: # a decision drops steps and questions, and is about what it drops
150
+ if nodes.get(i, {}).get("type") not in ("question",) + R.STEPS:
151
+ bad("links", d["path"], f"drops names {i!r}, which is not a question or a step of the lab")
152
+ elif i not in d["about"]:
153
+ bad("links", d["path"], f"drops names {i}, which is not under `about:`: a decision that drops something is about it")
134
154
  for i in d["order"]: # the order of the work names what it orders: goals, questions and steps, each once
135
155
  if nodes.get(i, {}).get("type") not in ("goal", "question") + R.STEPS:
136
156
  bad("links", d["path"], f"order names {i!r}, which is not a goal, a question or a step of the lab")
@@ -181,7 +201,7 @@ def run(lab, rederive=True):
181
201
  if stray:
182
202
  bad("locks", p, f"plan/ holds a compiled file outside __pycache__, {stray[0]}: Python would import it, and a `.pyc` is not pinned")
183
203
  if x["lock"]:
184
- if lab.nodes[x["question"]]["state"] == "under discussion":
204
+ if lab.nodes[x["question"]]["state"] == "waiting":
185
205
  bad("locks", p, f"is locked under {x['question']}, whose decision is not settled")
186
206
  if not x["lock"].get("unreadable") and not lab.lock_holds(x):
187
207
  bad("locks", p, "what it demands (a bar's role, result, comparison or number, an arm's name) or the resources it uses changed after the lock; that is a new experiment")
@@ -267,7 +287,7 @@ def run(lab, rederive=True):
267
287
  bad("results", p, "its results or its run changed after the review that passed them")
268
288
  elif any(R.flat(x["slots"].get(k, "")) for k in ("Found", "Means")):
269
289
  bad("cards", p, "says what was found with no result behind it")
270
- if x["state"] == "review failed" and (R.flat(x["slots"].get("Found", "")) or R.flat(x["slots"].get("Means", ""))):
290
+ if x["label"] == "void" and (R.flat(x["slots"].get("Found", "")) or R.flat(x["slots"].get("Means", ""))):
271
291
  bad("cards", p, "its results failed their review, so the card says nothing was found: replace the experiment")
272
292
  for r in lab.runs:
273
293
  if r.get("experiment") not in nodes:
@@ -283,8 +303,9 @@ def run(lab, rederive=True):
283
303
  if not row:
284
304
  bad("names", n["path"], f"{slot} names {written}, which is not a result" + ("" if home or ":" in written else " (a question names it in full: {G1.Q1.2:name})"))
285
305
  elif not row["usable"]:
286
- state = nodes[row["experiment"]]["state"]
287
- bad("names", n["path"], f"{slot} names {written}, whose experiment is {state}" + ("" if state in ("replaced", "dropped", "review failed") else " and not yet reviewed"))
306
+ owner = nodes[row["experiment"]]
307
+ state = "void: its results review failed" if owner["label"] == "void" else owner["state"]
308
+ bad("names", n["path"], f"{slot} names {written}, whose experiment is {state}" + ("" if owner["state"] in ("replaced", "dropped") or owner["label"] == "void" else " and not yet reviewed"))
288
309
  typed = set(re.findall(r"(?<![\w.{:])\d+\.\d+%?", R.NAMED.sub("", text)))
289
310
  for row in every:
290
311
  forms = {row["value"], R.shown(row).split(" ")[0].lstrip("+\u2212")}
@@ -319,7 +340,7 @@ def run(lab, rederive=True):
319
340
  d = nodes.get(m["carries"])
320
341
  if not d or d["type"] != "decision":
321
342
  bad("missions", where, f"`carries:` names the decision it carries out; {m['carries'] or 'nothing'!r} is not one")
322
- elif m["state"] == "current" and d["state"] != "decided":
343
+ elif m["state"] == "current" and d["state"] != "done":
323
344
  bad("missions", where, f"is current and carries {d['id']}, which is still open: a mission carries out a settled decision")
324
345
  words = len(m["description"].split())
325
346
  if not words:
@@ -20,7 +20,7 @@ To write
20
20
  lab new experiment|build|reading <question> "<title>" [--replaces <experiment> --because "<why>"]
21
21
  lab log <id> doing "<what you are starting on>" "<why now>"
22
22
  lab log <id> agent|result|stuck "<what happened>" ["<so what>"]
23
- lab answer <question> yes|no "<what the answer rests on>"
23
+ lab answer <question> yes|no|mixed "<what the answer rests on>"
24
24
  To carry out a decision
25
25
  lab mission [<mission>] [--all] the open missions (--all: the closed too), or one whole: its rules, its steps, its log
26
26
  lab mission new "<title>" --carries <decision> save a mission; it is next until launched
@@ -128,6 +128,9 @@ def main(argv=None):
128
128
  if not 3 <= len(rest) <= 4:
129
129
  raise SystemExit(USAGE)
130
130
  print(f"added to {write.log(lab, rest[0], rest[1], rest[2], rest[3] if len(rest) == 4 else '')}")
131
+ q = lab.question_of(rest[0]) if rest[1] == "result" else None
132
+ if q and q["id"] != rest[0]:
133
+ print(f"now bring So far of {q['id']} {q['title']} up to date with what this result taught: `lab check` reports it until then")
131
134
  elif cmd == "decide":
132
135
  with_ = flag("--with")
133
136
  if len(rest) != 2: