lab-kit-cli 1.6.0__tar.gz → 1.7.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.6.0 → lab_kit_cli-1.7.0}/.github/workflows/policy.yml +5 -3
  2. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/AGENTS.md +7 -4
  3. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/CHANGELOG.md +16 -0
  4. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/PKG-INFO +2 -2
  5. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/README.md +1 -1
  6. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/docs/model.md +35 -10
  7. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/pyproject.toml +1 -1
  8. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/skills/lab-work/SKILL.md +9 -5
  9. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/src/lab_kit/__init__.py +1 -1
  10. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/src/lab_kit/checks.py +6 -2
  11. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/src/lab_kit/cli.py +1 -1
  12. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/src/lab_kit/record.py +10 -4
  13. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/src/lab_kit/site.py +111 -37
  14. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/src/lab_kit/write.py +7 -1
  15. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_site.py +24 -0
  16. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_states.py +20 -0
  17. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/.github/workflows/ci.yml +0 -0
  18. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/.github/workflows/release.yml +0 -0
  19. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/.gitignore +0 -0
  20. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/CLAUDE.md +0 -0
  21. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/CONTRIBUTING.md +0 -0
  22. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/LICENSE +0 -0
  23. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/agents/reviewer.md +0 -0
  24. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/method/METHOD.md +0 -0
  25. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/skills/lab-mission/SKILL.md +0 -0
  26. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/skills/lab-review/SKILL.md +0 -0
  27. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/skills/lab-set-up/SKILL.md +0 -0
  28. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/skills/lab-talk/SKILL.md +0 -0
  29. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/src/lab_kit/history.py +0 -0
  30. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/src/lab_kit/runs.py +0 -0
  31. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/src/lab_kit/supervise.py +0 -0
  32. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/src/lab_kit/views.py +0 -0
  33. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_flow.py +0 -0
  34. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_held.py +0 -0
  35. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_integrity.py +0 -0
  36. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_mission.py +0 -0
  37. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_needs.py +0 -0
  38. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_order.py +0 -0
  39. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_parked.py +0 -0
  40. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_refusals.py +0 -0
  41. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_vocabulary.py +0 -0
  42. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tests/test_wording.py +0 -0
  43. {lab_kit_cli-1.6.0 → lab_kit_cli-1.7.0}/tools/import_run.py +0 -0
@@ -1,10 +1,11 @@
1
1
  name: policy
2
2
 
3
- # Runs on pull requests only: a push straight to main is checked by the pre-push hook on the
4
- # machine that pushes (setup-machine), so GitHub spends no minutes on it (decision 0033).
3
+ # Runs on ready pull requests only: a push straight to main is checked by the pre-push hook on the
4
+ # machine that pushes (setup-machine), so GitHub spends no minutes on it (decision 0033). A draft
5
+ # cannot merge, so it is skipped, and marking it ready runs the check.
5
6
  on:
6
7
  pull_request:
7
- types: [opened, edited, synchronize, reopened]
8
+ types: [opened, edited, synchronize, reopened, ready_for_review]
8
9
 
9
10
  concurrency:
10
11
  group: policy-${{ github.event.pull_request.number }}
@@ -15,6 +16,7 @@ permissions:
15
16
 
16
17
  jobs:
17
18
  policy:
19
+ if: ${{ !github.event.pull_request.draft }}
18
20
  runs-on: ubuntu-latest
19
21
  steps:
20
22
  - uses: actions/checkout@v5
@@ -44,8 +44,11 @@ Every change goes through a pull request; `main` accepts nothing else.
44
44
 
45
45
  Run the gate before every push; CI also runs it on every pull request.
46
46
 
47
- **Authorship.** Every commit is authored with the repository owner's git identity. No co-author
48
- line, tool or agent name, "generated with" footer or session link appears in a commit message, a
49
- branch name or a pull request. The pre-push hook enforces it on every push, and a required `policy`
50
- check on every pull request.
47
+ **Authorship.** This repository is public. Every commit is authored with the repository owner's
48
+ git identity. No co-author line, tool or agent name, "generated with" footer or session link
49
+ appears in a commit message, a branch name or a pull request: name a branch after the task, never
50
+ `claude/…` or another tool's prefix. The pre-push hook (on every machine, and in cloud sessions
51
+ from their environment's setup script) enforces it on every push, ops' land-job `pr-check.sh`
52
+ checks a pull request's text before it is opened, and a required `policy` check runs on every ready
53
+ pull request.
51
54
  <!-- ops:lanes:end -->
@@ -1,5 +1,21 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.7.0
4
+
5
+ Two kinds of question, and the site draws every state with one mark, the same on every page.
6
+
7
+ - **A question is a test or an estimate** (`kind:` on its card; test is the default). A test asks whether something
8
+ holds and is answered yes, no or mixed. An estimate asks how much, which or what, and is answered `found`, with
9
+ the finding itself: `lab answer <question> found "<the finding, with its range, and what it rests on>"`. `lab
10
+ answer` and `lab check` refuse the other kind's answers. Its mark is F. The skill `lab-work` changed: run `lab
11
+ init` in a lab after upgrading.
12
+ - **One mark per state and label,** on Now, in the rail, in the page header, in the lists of steps, runs and reviews:
13
+ the shape carries the meaning and the colour follows it. Waiting is ‖, parked ◇, a decision to discuss ◆; a run or a
14
+ review that failed is ✗. Where a page writes a state out, it shows the mark and the word together, in its colour.
15
+ - **A goal or a question with a step running under it shows as running,** its mark pulsing, on Now and in the rail.
16
+ - **Now has the key** above the map of the lab, grouped by the kind of card; the rail's key is the same.
17
+ - A log line's kind is drawn without colour: colour is kept for states.
18
+
3
19
  ## 1.6.0
4
20
 
5
21
  One set of states for every card, and the checks that keep a card from saying what the record does not. The site's
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.6.0
3
+ Version: 1.7.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
@@ -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 question answered yes, no or mixed: what we expect, what would prove us wrong, what we know so far
36
+ Question a test (answered yes, no or mixed) or an estimate (answered with what was found): 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 question answered yes, no or mixed: what we expect, what would prove us wrong, what we know so far
18
+ Question a test (answered yes, no or mixed) or an estimate (answered with what was found): 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
@@ -10,7 +10,7 @@ A lab is a tree, and the decisions that shaped it.
10
10
  | Thing | What it says | States |
11
11
  | --- | --- | --- |
12
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 |
13
+ | **Question** | A short name, and a 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. A test is answered yes, no or mixed; an estimate is answered with what was found. | open, waiting, parked, done (yes, no, mixed or found), dropped |
14
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
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
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 |
@@ -31,10 +31,22 @@ seven words, and each type uses only those it can be in:
31
31
  | replaced | redone by a newer experiment | | | yes | | |
32
32
  | dropped | will not be done | yes | yes | yes | yes | yes |
33
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
34
+ Two types carry a label on done. A question's is its answer, and what it can be depends on the
35
+ question's kind, set when it is written (`kind:`):
36
+
37
+ - **A test** (the default) asks whether something holds: "Does the error halve when the sample
38
+ quadruples?" Its answer is **yes**, **no** or **mixed**, read against its We expect and Wrong if, with
39
+ one sentence on what it rests on. Mixed says which part held and which did not, and usually leads to
40
+ a narrower question.
41
+ - **An estimate** asks how much, which or what: "How little feedback does a session need?", "What did
42
+ the solver's search depend on?" Its answer is **found**, with the finding itself in one or two
43
+ sentences: a number with its range, or a short description, and what it rests on. Its We expect says
44
+ roughly what size or shape is expected, and its Wrong if what would surprise. An estimate is never
45
+ squeezed into yes or no, which would throw away the size and how sure it is.
46
+
47
+ Either kind is answered only from done experiments that are not void; the bars that confirm or refute
48
+ stay on the experiments. An answer is a finding, never good or bad: no is not a failure. A question has
49
+ no "unclear": while the evidence cannot answer it, it is open. An experiment's
38
50
  label is its outcome: **confirmed**, **refuted** or **unclear**, read against the bars set before the
39
51
  run, or **void** when its results review failed, so that its numbers cannot be cited. A decision is open,
40
52
  then done; a mission's `status:` (next, current, done, stopped) reads on the pages as open, running,
@@ -297,8 +309,8 @@ change once committed; a change of mind is a new decision. `lab check` holds thi
297
309
  history. So a decision cannot be made, afterwards, to be about something it never discussed.
298
310
 
299
311
  The agent decides everything else and records each choice in the log. It drops an experiment or a
300
- build that will not be done, saying why. It answers a question itself, yes, no or mixed, with `lab answer`, and
301
- the command refuses while an experiment of that question is neither done, replaced nor dropped, and
312
+ build that will not be done, saying why. It answers a question itself with `lab answer`: a test yes, no or mixed, an estimate found. The command refuses the other kind's answers, and
313
+ it refuses while an experiment of that question is neither done, replaced nor dropped, and
302
314
  when no experiment of it is done: a reading alone answers nothing. `lab check` asks the same of every
303
315
  answered question, and that the log holds the line `lab answer` wrote. It never asks you to check
304
316
  its work, which is the review's job, and it never opens a decision for something that is its own to
@@ -470,6 +482,18 @@ place and marked, with its goal, its question and its siblings in view. A questi
470
482
  dropped steps fold into one line at its end; a goal's parked and dropped questions into one line at
471
483
  its end.
472
484
 
485
+ **One mark for each state, everywhere.** Every word a page uses for where something stands has one
486
+ mark, a shape in a colour, and it is the same on Now, in the rail, in the page header, in a list of
487
+ steps and in a list of runs: open ○, waiting ‖, running ● (it pulses), parked ◇, done ✓, replaced and
488
+ dropped –; a question answered yes, no, mixed or found Y, N, M, F, all in the ink's colour, since an answer is a
489
+ finding and never good or bad; an experiment confirmed ✓, refuted ✗, unclear ?, void !; a decision to
490
+ discuss ◆ or decided ✓; a run running, finished ✓ or failed ✗, and a review passed ✓ or failed ✗. The
491
+ shape carries the meaning, so colour is never the only signal. Where a page writes a state out, it
492
+ writes the mark and the word, in the mark's colour. A goal or a question that is open or waiting with a
493
+ step running under it shows as running, its mark pulsing, with the running steps named on hover; its
494
+ state in the record does not change. A log line's kind (found, stuck, decided) is a kind of event, not
495
+ a state, and is drawn without colour. Now carries the key, and so does the rail, folded.
496
+
473
497
  **How a page of a card reads.** Every page of a goal, a question or a step reads in the same order:
474
498
 
475
499
  1. The title, and the lead: a step's or a goal's description, a question's `asks:` line.
@@ -506,8 +530,9 @@ and the answer in chat cannot differ. An experiment's page is the evidence behin
506
530
  what is live at this moment (each run going, the current mission with the last line of its log, what
507
531
  the agent says it is on), each with a pulsing mark, and when the record last moved; what needs you (the
508
532
  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
533
+ goal with its mark and how many of its questions are answered, and one tile per live question with its
534
+ mark and its state written out (its answer once answered) and one mark per step in tree order, above
535
+ them the key; what each resource has used of its grant, as a bar; the
511
536
  latest events. There is no graph page: the rail is the tree and Now is the map.
512
537
 
513
538
  **An example on every question.** A question's page carries one case, step by step, as a numbered
@@ -581,7 +606,7 @@ the first two lines that are exactly `---`. A key that holds a list (`needs`, `u
581
606
  | Card | Front matter | Slots (word budget) |
582
607
  | --- | --- | --- |
583
608
  | `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) |
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) |
609
+ | `question.md` | `title:` (a short name), `asks:` (the question in full), `kind:` (test, the default, or estimate), `from:`, `needs:`; `dropped: <why>`; `answer:` (yes, no or mixed for a test, found for an estimate) 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
610
  | `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
611
  | `reading.md` | `title:`, `needs:`, `waiting_on:`, `dropped: <why>` | description (70), Looks at: what, and where it is (120), Seen (360), Suggests (150) |
587
612
  | `build.md` | `title:`, `needs:`, `waiting_on:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  dynamic = ["readme"]
7
7
  name = "lab-kit-cli"
8
- version = "1.6.0"
8
+ version = "1.7.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" }]
@@ -115,11 +115,14 @@ parked question, and never take it up because it looks open: it is listed under
115
115
  records what was decided.
116
116
 
117
117
  A goal or a question is made out of a decision: `lab new question <goal> "<short name>" --asks "<the
118
- question, in full>" --from <decision>`. Its description is the motivation: why we ask, and what
118
+ question, in full>" --from <decision>`. Say its kind in the card's front matter: a **test** asks
119
+ whether something holds and is answered yes, no or mixed (the default, `kind: test`); an **estimate**
120
+ asks how much, which or what and is answered with what was found (`kind: estimate`). Never bend an
121
+ estimate into a yes-or-no question. Its description is the motivation: why we ask, and what
119
122
  depends on the answer. **How we would know** is the idea of the test in plain words, before any
120
123
  experiment exists. **Example** is one case, step by step, as a numbered list saying who does what:
121
124
  a real episode once there is one, and until then the flow, said to be only that. Then **We expect**
122
- and **Wrong if**. Nothing under it is locked or run
125
+ and **Wrong if** (for an estimate: roughly what size or shape is expected, and what would surprise). Nothing under it is locked or run
123
126
  until that decision is settled; after that it needs no further yes.
124
127
 
125
128
  ## An experiment
@@ -236,9 +239,10 @@ repository, tests first. When it works, put `commits:` and `tests:` on the card
236
239
 
237
240
  ## When all experiments of a question are done
238
241
 
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
+ Decide whether they answer it. For a test, `lab answer <question> yes|no|mixed "<what the answer rests
243
+ on>"`: yes and no say whether what the question expected held; mixed says part held and part did not,
244
+ and the sentence says which. For an estimate, `lab answer <question> found "<the finding, with its range
245
+ or its shape, and what it rests on>"`. Then bring **So far** up to date. An answer rests on a done experiment that is not
242
246
  void. If they do not answer it, add the next experiment. An answer usually changes
243
247
  what should come next: open a decision.
244
248
 
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.6.0"
2
+ __version__ = "1.7.0"
@@ -7,7 +7,7 @@ from . import history, 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"},
10
- "question": {"title", "asks", "from", "needs", "answer", "answered", "dropped", "see"},
10
+ "question": {"title", "asks", "kind", "from", "needs", "answer", "answered", "dropped", "see"},
11
11
  "experiment": {"title", "needs", "uses", "override", "replaces", "because", "cost", "waiting_on", "dropped", "see"},
12
12
  "build": {"title", "needs", "commits", "tests", "waiting_on", "dropped", "see"},
13
13
  "reading": {"title", "needs", "waiting_on", "dropped", "see"},
@@ -93,8 +93,12 @@ def run(lab, rederive=True):
93
93
  for need in q["needs"]:
94
94
  if nodes.get(need, {}).get("type") != "question":
95
95
  bad("links", q["path"], f"needs {need}, which is not a question")
96
+ if q.get("kind") is not None and q.get("kind") not in R.KINDS_OF_QUESTION:
97
+ bad("cards", q["path"], "`kind:` is test or estimate")
96
98
  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`")
99
+ bad("cards", q["path"], "`answer:` is yes, no or mixed for a test, or found for an estimate, written by `lab answer`")
100
+ elif q.get("answer") is not None and R.question_kind(q) in R.KINDS_OF_QUESTION and q["answer"] not in R.KINDS_OF_QUESTION[R.question_kind(q)]:
101
+ bad("questions", q["path"], f"is {'an estimate' if R.question_kind(q) == 'estimate' else 'a test'} and is answered {q['answer']}: a test is answered yes, no or mixed, an estimate found")
98
102
  if q.get("answer") in R.ANSWERS: # what `lab answer` requires holds for an answer however it got on the card
99
103
  waiting = [x["id"] for x in q["items"] if x["state"] not in R.CLOSED]
100
104
  if waiting:
@@ -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|mixed "<what the answer rests on>"
23
+ lab answer <question> yes|no|mixed|found "<what the answer rests on>" (found: for an estimate, the finding)
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
@@ -32,10 +32,11 @@ MISSION_BUDGET = {"description": 80, "Rules": 200}
32
32
  MISSION_STATES = ("next", "current", "done", "stopped") # a mission's `status:`; done and stopped are closed, and the file is kept
33
33
  STEPS = ("experiment", "build", "reading")
34
34
  # One set of states for every goal, question and step (the model, section 1). A type uses only those it can be in. On
35
- # done, a question carries its answer (yes, no or mixed) and an experiment its outcome (confirmed, refuted, unclear or
35
+ # done, a question carries its answer (yes, no or mixed for a test, found for an estimate) and an experiment its outcome (confirmed, refuted, unclear or
36
36
  # void) as its label.
37
37
  STATES = ("open", "waiting", "running", "parked", "done", "replaced", "dropped")
38
- ANSWERS = ("yes", "no", "mixed")
38
+ ANSWERS = ("yes", "no", "mixed", "found")
39
+ KINDS_OF_QUESTION = {"test": ("yes", "no", "mixed"), "estimate": ("found",)} # what each kind of question may be answered
39
40
  CLOSED = ("done", "replaced", "dropped") # a step in one of these will not move again # what sits under a question: a locked comparison, something made, a look at what already exists
40
41
  READS = ("", "percent", "points") # how a result's value reads on a page
41
42
  BEFORE = ("Compares", "Arms", "Cases", "Confirmed if", "Refuted if", "Outcomes", "Limits") # what an experiment says before it runs: its plan, which So far, Found and Means are not part of
@@ -55,7 +56,7 @@ HASH = 2 # how a folder is hashed in the locks and runs made now; one without t
55
56
  NUMBER = re.compile(r"[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?")
56
57
  LISTS = {"goal": ("see",), "question": ("needs", "see"), "experiment": ("needs", "uses", "see"), "build": ("needs", "commits", "tests", "see"),
57
58
  "reading": ("needs", "see"), "decision": ("about", "holds", "parks", "unparks", "drops", "order", "see")} # the front matter keys that hold a list
58
- TEXTS = ("title", "asks", "from", "replaces", "because", "cost", "waiting_on", "dropped", "answered") # and those that hold one value
59
+ TEXTS = ("title", "asks", "kind", "from", "replaces", "because", "cost", "waiting_on", "dropped", "answered") # and those that hold one value
59
60
 
60
61
 
61
62
  def complement(a, b):
@@ -196,6 +197,11 @@ def seal_of(record):
196
197
  return hashlib.sha256(json.dumps({k: v for k, v in record.items() if k != "seal"}, sort_keys=True).encode()).hexdigest()
197
198
 
198
199
 
200
+ def question_kind(q):
201
+ """A question's kind: a test, answered yes, no or mixed, unless its card says it is an estimate, answered found."""
202
+ return str(q.get("kind") or "test")
203
+
204
+
199
205
  def flat(text):
200
206
  return " ".join(str(text).split())
201
207
 
@@ -1021,7 +1027,7 @@ class Lab:
1021
1027
  if q["state"] == "parked":
1022
1028
  return f"{q['id']} is parked by {self.parked_by(q['id'])['id']}: a decision that unparks it comes first"
1023
1029
  if q["state"] != "open":
1024
- return f"{q['id']} is {'answered ' + q['label'] if q['state'] == 'done' else q['state']}"
1030
+ return f"{q['id']} is {('answered ' + q['label']) if q['state'] == 'done' and q['label'] != 'found' else 'answered with what was found' if q['state'] == 'done' else q['state']}"
1025
1031
  for need in x.get("needs") or []:
1026
1032
  n = self.nodes.get(need)
1027
1033
  if n and x["id"] in self.reach.get(need, {need} if need == x["id"] else ()): # a circle of needs: nothing in it moves
@@ -11,19 +11,29 @@ from . import record as L
11
11
 
12
12
  GENERIC = {"model", "field", "source", "group", "stop", "case", "score", "port", "step", "pass", "run", "result"}
13
13
  e = html.escape
14
- TONES = {"running": "info", "finished": "ok", "failed": "bad", "pass": "ok", "fail": "bad"} # a run's state and a review's verdict, as pills
15
14
  # How every state and label is drawn, on every page, on Now and in the rail: its tone (the colour) and its sign (the
16
15
  # shape), so that colour is never the only signal. On done the label decides, and an answer is a finding, never good or
17
16
  # bad: yes, no and mixed share one neutral tone.
18
- LOOK = {"open": ("plain", "\u25cb"), "waiting": ("warn", "\u2016"), "parked": ("plain", "\u2016"), "running": ("info", "\u25cf"),
17
+ LOOK = {"open": ("plain", "\u25cb"), "waiting": ("warn", "\u2016"), "parked": ("plain", "\u25c7"), "running": ("info", "\u25cf"),
19
18
  "done": ("ok", "\u2713"), "confirmed": ("ok", "\u2713"), "unclear": ("warn", "?"), "refuted": ("bad", "\u2717"), "void": ("bad", "!"),
20
- "yes": ("ink", "Y"), "no": ("ink", "N"), "mixed": ("ink", "M"), "replaced": ("gone", "\u2013"), "dropped": ("gone", "\u2013"),
21
- "to discuss": ("warn", "\u25cf"), "decided": ("ok", "\u2713")}
22
- ORDER = ("running", "waiting", "open", "done", "confirmed", "yes", "no", "mixed", "unclear", "refuted", "void", "parked", "replaced", "dropped") # how counts are listed
19
+ "yes": ("ink", "Y"), "no": ("ink", "N"), "mixed": ("ink", "M"), "found": ("ink", "F"), "replaced": ("gone", "\u2013"), "dropped": ("gone", "\u2013"),
20
+ "to discuss": ("warn", "\u25c6"), "decided": ("ok", "\u2713"),
21
+ "finished": ("ok", "\u2713"), "failed": ("bad", "\u2717"), "pass": ("ok", "\u2713"), "fail": ("bad", "\u2717")}
22
+ ORDER = ("running", "waiting", "open", "done", "confirmed", "yes", "no", "mixed", "found", "unclear", "refuted", "void", "parked", "replaced", "dropped") # how counts are listed
23
23
  MARK = {"goal": "G", "question": "Q", "experiment": "E", "build": "B", "reading": "R", "decision": "D"}
24
24
  MEANS = {"running": "running", "waiting": "waiting", "open": "open", "done": "done", "confirmed": "confirmed", "yes": "answered yes", "no": "answered no",
25
- "mixed": "answered mixed", "unclear": "unclear", "refuted": "refuted", "void": "void: its results review failed", "parked": "parked",
26
- "replaced": "replaced", "dropped": "dropped"}
25
+ "mixed": "answered mixed", "found": "found", "unclear": "unclear", "refuted": "refuted", "void": "void", "parked": "parked",
26
+ "replaced": "replaced", "dropped": "dropped", "to discuss": "to discuss", "decided": "decided",
27
+ "finished": "finished", "failed": "failed", "pass": "passed", "fail": "failed"}
28
+ # The key, on Now and in the rail: one group per kind of card, each word with the mark it has everywhere.
29
+ LEGEND = (("Any card", ("open", "waiting", "running", "parked", "done", "replaced", "dropped")),
30
+ ("A question, answered", ("yes", "no", "mixed", "found")),
31
+ ("An experiment, done", ("confirmed", "refuted", "unclear", "void")),
32
+ ("A decision", ("to discuss", "decided")),
33
+ ("A run, a review", ("running", "finished", "pass", "failed")))
34
+ HINT = {"running": "work under way; on a goal or a question, a step under it is running", "waiting": "held by a step it needs, a decision or something outside the lab",
35
+ "parked": "set aside by a decision", "void": "its results review failed: its numbers are never used", "replaced": "redone by a newer experiment",
36
+ "dropped": "will not be done", "to discuss": "open: waits for you", "found": "an estimate, answered with what was found", "failed": "a run that stopped with an error, or a review that did not pass"}
27
37
 
28
38
 
29
39
  def nice(day):
@@ -68,20 +78,36 @@ def ordinal(n):
68
78
  return {1: "first", 2: "second", 3: "third", 4: "fourth", 5: "fifth", 6: "sixth"}.get(n, f"{n}th")
69
79
 
70
80
 
81
+ def running_under(n):
82
+ """The steps running under a goal or a question, in tree order."""
83
+ if n.get("type") == "question":
84
+ return [x for x in n.get("items") or [] if x["state"] == "running"]
85
+ if n.get("type") == "goal":
86
+ return [x for q in n.get("questions") or [] for x in running_under(q)]
87
+ return []
88
+
89
+
71
90
  def key(n):
72
- """The word a node's look is read from: its label on done (an answer, an outcome), else its state."""
91
+ """The word a node's look is read from: its label on done (an answer, an outcome), else its state. A goal or a
92
+ question that is open or waiting with a step running under it reads as running, so that the work shows at every
93
+ level of the tree; its state in the record is unchanged."""
73
94
  if n.get("type") == "decision":
74
95
  return "decided" if n["state"] == "done" else "to discuss"
96
+ if n.get("state") in ("open", "waiting") and running_under(n):
97
+ return "running"
75
98
  return n["label"] if n.get("state") == "done" and n.get("label") else n["state"]
76
99
 
77
100
 
78
101
  def label(n):
79
- """A node's state as the operator reads it: on done, a question shows its answer and an experiment its outcome."""
80
- if n.get("type") == "decision":
81
- return "decided" if n["state"] == "done" else "open"
82
- if n["state"] == "done" and n.get("label"):
83
- return f"answered {n['label']}" if n["type"] == "question" else n["label"]
84
- return n["state"]
102
+ """A node's state as the operator reads it, in the words of the key: on done, a question shows its answer and an
103
+ experiment its outcome."""
104
+ return MEANS.get(key(n), key(n))
105
+
106
+
107
+ def hint(n):
108
+ """What a mark says on hover: the word, and for a goal or a question shown as running, what runs under it."""
109
+ under = running_under(n) if n.get("type") in ("goal", "question") and key(n) == "running" else []
110
+ return label(n) + (": " + ", ".join(x["id"] for x in under) + " running" if under else "")
85
111
 
86
112
 
87
113
  def tone(n):
@@ -101,9 +127,48 @@ def pill(text, t="plain"):
101
127
  return f'<span class="pill t-{t}">{e(str(text))}</span>'
102
128
 
103
129
 
104
- def dot(n):
105
- """A node's state as a sign in its tone: the same shape and colour as in the rail. A running step's sign pulses."""
106
- return f'<span class="sg t-{tone(n)}{" live" if n.get("state") == "running" else ""}" title="{e(label(n))}">{sign(n)}</span>'
130
+ def mark(k, title=""):
131
+ """The mark of a word of the key: its sign in its tone, the same shape and colour on every page and in the rail.
132
+ Running pulses."""
133
+ t, g = LOOK.get(k, ("plain", "\u25cb"))
134
+ return f'<span class="sg t-{t}{" live" if k == "running" else ""}" title="{e(title or MEANS.get(k, k))}">{g}</span>'
135
+
136
+
137
+ def dot(n, title=""):
138
+ """A node's mark."""
139
+ return mark(key(n), title or hint(n))
140
+
141
+
142
+ def status(n):
143
+ """A node's mark and its word, in its tone: how a state is written out wherever a page names it."""
144
+ h = hint(n)
145
+ return word(key(n), h if h != label(n) else "")
146
+
147
+
148
+ def word(k, title=""):
149
+ """A word of the key written out: its mark and the word, in its tone."""
150
+ t = LOOK.get(k, ("plain", ""))[0]
151
+ return f'<span class="stw t-{t}" title="{e(title or HINT.get(k, MEANS.get(k, k)))}">{mark(k, title)}{e(MEANS.get(k, k))}</span>'
152
+
153
+
154
+ def legend_html():
155
+ """The key on Now: every mark the site draws, by the kind of card it is on."""
156
+ rows = "".join(f'<div><b>{e(group)}</b>' + "".join(word(k) for k in keys) + "</div>" for group, keys in LEGEND)
157
+ return f'<div class="legend">{rows}</div>'
158
+
159
+
160
+ def header_css():
161
+ """folio's page header shows the view's status as a pill: draw it with the same mark and tone as everywhere else."""
162
+ soft = {"ok": "ok-soft", "warn": "warn-soft", "bad": "bad-soft", "info": "info-soft"}
163
+ out = []
164
+ for k, (t, g) in LOOK.items():
165
+ fg = {"plain": "ink-3", "gone": "ink-3", "ink": "ink"}.get(t, t)
166
+ sel = f'.f-status[data-s="{MEANS.get(k, k)}"]'
167
+ out.append(f'{sel}{{background:var(--{soft.get(t, "sunk")});color:var(--{fg})}}'
168
+ f'{sel}::before{{content:"{g}";width:auto;height:auto;border-radius:0;background:none;opacity:1;font-weight:700}}')
169
+ if k == "running":
170
+ out.append(f"@media (prefers-reduced-motion:no-preference){{{sel}::before{{animation:lv-pulse 1.6s ease-in-out infinite}}}}")
171
+ return "".join(out)
107
172
 
108
173
 
109
174
  def libraries(lab):
@@ -326,6 +391,11 @@ CSS = """
326
391
  .lv .t-ink{background:var(--sunk);color:var(--ink)}
327
392
  .lv .t-gone{background:none;color:var(--ink-3);text-decoration:line-through}
328
393
  .lv .live{animation:lv-pulse 1.6s ease-in-out infinite}
394
+ .lv .stw{display:inline-flex;gap:.25rem;align-items:baseline;background:none;font:600 .78rem/1.4 var(--sans);white-space:nowrap}
395
+ .lv .stw.t-plain,.lv .stw.t-gone{color:var(--ink-3);text-decoration:none}.lv .stw.t-ink{color:var(--ink)}
396
+ .lv .legend{display:flex;flex-wrap:wrap;gap:.35rem 1.4rem;margin:.2rem 0 .8rem;padding:.5rem .8rem;border:1px solid var(--rule);border-radius:8px;background:var(--surface);font:400 .78rem var(--sans)}
397
+ .lv .legend>div{display:flex;flex-wrap:wrap;gap:.2rem .7rem;align-items:baseline}
398
+ .lv .legend b{font:650 .66rem var(--sans);text-transform:uppercase;letter-spacing:.08em;color:var(--ink-3);margin-right:.1rem}
329
399
  @keyframes lv-pulse{0%,100%{opacity:1}50%{opacity:.3}}
330
400
  @media (prefers-reduced-motion:reduce){.lv .live{animation:none}}
331
401
  .lv .dash-live{background:var(--surface);border:1px solid var(--rule);border-left:3px solid var(--info);border-radius:8px;padding:.7rem 1rem;margin:.2rem 0 1rem;font:400 .95rem/1.5 var(--sans)}
@@ -346,7 +416,7 @@ CSS = """
346
416
  .lv .tile:hover{border-color:var(--accent)}
347
417
  .lv .tile.t-done{background:var(--sunk)}
348
418
  .lv .tile .top{display:flex;gap:.4rem;align-items:baseline}
349
- .lv .tile .id{font:500 .74rem var(--mono);color:var(--ink-3)}
419
+ .lv .tile .id{font:500 .74rem var(--mono);color:var(--ink-3);white-space:nowrap}
350
420
  .lv .tile .ttl{font-weight:600;color:var(--ink)}
351
421
  .lv .tile .st{margin:.15rem 0 .3rem;font-size:.78rem;color:var(--ink-3)}
352
422
  .lv .tile .marks{display:flex;flex-wrap:wrap;gap:.15rem .3rem;font-size:.95rem}
@@ -645,11 +715,10 @@ def log_html(lab, T, lines, with_about=True):
645
715
  return '<p class="muted">Nothing yet.</p>'
646
716
  out = ['<ul class="log">']
647
717
  for l in reversed(lines):
648
- kind_tone = {"result": "ok", "stuck": "bad", "decision": "info", "agent": "plain", "doing": "plain"}.get(l["kind"], "plain")
649
718
  who = {"decision": "decided", "agent": "agent", "doing": "started"}.get(l["kind"], l["kind"])
650
719
  so = f'<span class="so">{T(l["so"])}</span>' if l["so"] else ""
651
720
  about = ref(lab, l["about"]) if with_about else ""
652
- out.append(f'<li><span class="d">{clock(l["at"])}</span><span>{pill(who, kind_tone)}</span><span>{about}</span><span>{T(l["what"])}{so}</span></li>')
721
+ out.append(f'<li><span class="d">{clock(l["at"])}</span><span>{pill(who)}</span><span>{about}</span><span>{T(l["what"])}{so}</span></li>')
653
722
  return "".join(out) + "</ul>"
654
723
 
655
724
 
@@ -814,7 +883,7 @@ def qcard(lab, T, q):
814
883
  body = asks + (block(T, q["slots"].get("So far", "")) if live else f'<p class="muted">{T(q["description"])}</p>')
815
884
  count = f"{done} of {len(live)} steps done" if live else ""
816
885
  return (f'<div class="qrow"><div><h3>{dot(q)} <a href="/{q["id"]}">{e(q["title"])}</a></h3>{body}</div>'
817
- f'<div class="side">{pill(label(q), tone(q))}<br>{count}</div></div>')
886
+ f'<div class="side">{status(q)}<br>{count}</div></div>')
818
887
 
819
888
 
820
889
  def live_box(lab, T):
@@ -823,15 +892,15 @@ def live_box(lab, T):
823
892
  for x in lab.experiments:
824
893
  for r in x["runs"] + x["trials"]:
825
894
  if r["state"] == "running" and not r["orphan"]:
826
- rows.append(f'<p><span class="who">running</span><span class="sg t-info live">\u25cf</span> {named(lab, x["id"])}, since {clock(r["started"])}'
895
+ rows.append(f'<p><span class="who">running</span>{mark("running")} {named(lab, x["id"])}, since {clock(r["started"])}'
827
896
  + (f' on {e(", ".join(x["uses"]))}' if x["uses"] else "") + ".</p>")
828
897
  for m in [m for m in lab.missions if m["state"] == "current"]:
829
898
  last = next((l for l in reversed(m["log"]) if l.get("what")), None)
830
- rows.append(f'<p><span class="who">mission</span><span class="sg t-info live">\u25cf</span> {e(m["id"])} {e(m["title"])}'
899
+ rows.append(f'<p><span class="who">mission</span>{mark("running")} {e(m["id"])} {e(m["title"])}'
831
900
  + (f' <span class="muted">last, {nice(last["day"])} {e(last["time"])}: {T(last["what"])}</span>' if last else "") + "</p>")
832
901
  d = lab.doing()
833
902
  if d:
834
- rows.append(f'<p><span class="who">the agent</span><span class="sg t-info live">\u25cf</span> on {named(lab, d["about"])}: {T(d["what"])} <span class="muted">Why now:</span> {T(d["so"])} <span class="muted">Since {clock(d["at"])}.</span></p>')
903
+ rows.append(f'<p><span class="who">the agent</span>{mark("running")} on {named(lab, d["about"])}: {T(d["what"])} <span class="muted">Why now:</span> {T(d["so"])} <span class="muted">Since {clock(d["at"])}.</span></p>')
835
904
  elif rows:
836
905
  rows.append('<p><span class="who">the agent</span><span class="muted">has not said it is on anything.</span></p>')
837
906
  if not rows:
@@ -872,11 +941,11 @@ def tile(lab, T, q):
872
941
  """A question on Now: its state and answer, and one sign per step in tree order; what was replaced or dropped is a count."""
873
942
  live = [x for x in q["items"] if x["state"] not in ("replaced", "dropped")]
874
943
  gone = len(q["items"]) - len(live)
875
- marks = "".join(f'<span class="sg t-{tone(x)}{" live" if x["state"] == "running" else ""}" title="{e(x["id"])} {e(x["title"])}: {e(label(x))}">{sign(x)}</span>' for x in live)
944
+ marks = "".join(dot(x, f'{x["id"]} {x["title"]}: {label(x)}') for x in live)
876
945
  marks += f'<span class="gone" title="replaced or dropped">\u2013{gone}</span>' if gone else ""
877
946
  marks = marks or '<span class="muted" style="font-size:.78rem">nothing under it yet</span>'
878
- return (f'<a class="tile t-{q["state"]}" href="/{q["id"]}" title="{e(q["asks"])}"><div class="top">{dot(q)}<span class="id">{e(q["id"].split(".")[-1])}</span>'
879
- f'<span class="ttl">{e(q["title"])}</span></div><div class="st">{e(label(q))}</div><div class="marks">{marks}</div></a>')
947
+ return (f'<a class="tile t-{q["state"]}" href="/{q["id"]}" title="{e(q["asks"])}"><div class="top"><span class="id">{e(q["id"].split(".")[-1])}</span>'
948
+ f'<span class="ttl">{e(q["title"])}</span></div><div class="st">{status(q)}</div><div class="marks">{marks}</div></a>')
880
949
 
881
950
 
882
951
  def lab_map(lab, T):
@@ -931,7 +1000,7 @@ def home(lab, T):
931
1000
  talk = [decision_box(lab, T, d) for d in lab.open_decisions()]
932
1001
  if talk:
933
1002
  out.append("<h2>To discuss with you</h2>" + "".join(talk))
934
- out.append("<h2>The lab</h2>" + lab_map(lab, T))
1003
+ out.append("<h2>The lab</h2>" + legend_html() + lab_map(lab, T))
935
1004
  if lab.resources:
936
1005
  out.append('<h2>Resources</h2>' + resources_table(lab))
937
1006
  latest = happened(lab.lines)[-5:]
@@ -959,7 +1028,7 @@ def set_aside_html(lab, T):
959
1028
  f'<p>{named(lab, q["id"])}: {T(str(q.get("dropped") or lab.nodes[q["goal"]].get("dropped") or ""))}</p>' for q in aside["dropped"]) + "</details>")
960
1029
  if aside["goals"]:
961
1030
  out.append(f'<details class="old"><summary>Closed goals ({len(aside["goals"])})</summary>' + "".join(
962
- f'<p>{named(lab, g["id"])}: {e(label(g))}{". " + T(str(g["dropped"])) if g.get("dropped") else ""}</p>' for g in aside["goals"]) + "</details>")
1031
+ f'<p>{named(lab, g["id"])}: {status(g)}{". " + T(str(g["dropped"])) if g.get("dropped") else ""}</p>' for g in aside["goals"]) + "</details>")
963
1032
  return "".join(out)
964
1033
 
965
1034
 
@@ -1020,7 +1089,7 @@ def step_row(lab, T, x):
1020
1089
  tries = len(lab.chain(x)) + 1 if x["type"] == "experiment" else 1
1021
1090
  tag = f'<span class="tries">{ordinal(tries)} plan</span>' if tries > 1 else ""
1022
1091
  tag = f'<span class="kind">{x["type"]}</span>' + tag
1023
- return (f'<details class="row"><summary>{dot(x)}<b>{e(x["title"])}{tag}</b><span>{pill(label(x), tone(x))}</span><span>{item_line(lab, T, x) or T(x["description"])}</span></summary>'
1092
+ return (f'<details class="row"><summary>{dot(x)}<b>{e(x["title"])}{tag}</b><span>{status(x)}</span><span>{item_line(lab, T, x) or T(x["description"])}</span></summary>'
1024
1093
  f'<div class="in"><p class="desc">{T(x["description"])}</p>{slot_text(lab, T, x)}{earlier(lab, T, x) if x["type"] == "experiment" else ""}<a href="/{x["id"]}" style="font:.85rem var(--sans)">Open {x["id"]}</a></div></details>')
1025
1094
 
1026
1095
 
@@ -1034,12 +1103,15 @@ def question_page(lab, T, q):
1034
1103
  body = [f'<h1>{e(q["title"])}</h1>']
1035
1104
  if q.get("asks") and q["asks"] != q["title"]:
1036
1105
  body.append(f'<p class="lead">{T(q["asks"])}</p>')
1106
+ kind = ("An estimate: answered with what was found, a number with its range or a description." if L.question_kind(q) == "estimate"
1107
+ else "A test: answered yes, no or mixed, against what we expect and what would prove us wrong.")
1108
+ body.append(f'<p class="muted" style="font:.84rem var(--sans);margin-top:-.4rem">{kind}</p>')
1037
1109
  if q["state"] == "parked":
1038
1110
  d = lab.parked_by(q["id"])
1039
1111
  body.append(f'<div class="box"><b>Set aside</b> by {named(lab, d["id"])}: nothing under it moves until a decision brings it back. {T(L.flat(d["slots"].get("Decided", "")))}</div>')
1040
1112
  body.append(picture(lab, q))
1041
1113
  before = [lab.nodes[i] for i in q["needs"] if i in lab.nodes]
1042
- body.append(slots(slot("Where we are coming from", "".join(f'<p>{named(lab, n["id"])} ({e(label(n))}).</p>' for n in before), "full") if before else "",
1114
+ body.append(slots(slot("Where we are coming from", "".join(f'<p>{named(lab, n["id"])} {status(n)}</p>' for n in before), "full") if before else "",
1043
1115
  so_far(lab, T, q)))
1044
1116
  body.append("<h2>The question, as asked</h2>" + slots(
1045
1117
  boxed(T, "Why we ask", q["description"]),
@@ -1148,7 +1220,7 @@ def runs_html(lab, T, x):
1148
1220
  changed = f'<br><span class="lbl">Changed since {since}</span> {T(r["changed"])}' if r.get("changed") else ""
1149
1221
  if r["missing"] and not r["lost"]:
1150
1222
  how += ' <span class="muted">It is listed in the experiment\'s record of runs, and its folder is not in the store here.</span>'
1151
- rows.append(f'<li><b>{name}</b> <span class="muted">{clock(r["started"])} UTC' + (f' on {e(", ".join(x["uses"]))}' if x["uses"] else "") + f'</span><br>{pill(r["state"], TONES.get(r["state"], "plain"))} {how}{changed}{folder}</li>')
1223
+ rows.append(f'<li><b>{name}</b> <span class="muted">{clock(r["started"])} UTC' + (f' on {e(", ".join(x["uses"]))}' if x["uses"] else "") + f'</span><br>{word(r["state"])} {how}{changed}{folder}</li>')
1152
1224
  note = ('<p class="muted" style="font:.84rem var(--sans)">An experiment is run until one run finishes. Between runs the apparatus may be fixed, and each run says what changed; '
1153
1225
  "what the experiment demands stays as it was locked. The first run that finishes is the only source of its results. "
1154
1226
  "A run's folder is in the lab's store, outside git.</p>") if n > 1 else ""
@@ -1159,7 +1231,7 @@ def reviews_html(x):
1159
1231
  if not x["reviews"]:
1160
1232
  return ""
1161
1233
  return ('<h3>Reviews</h3><table class="t"><tr><th>Reviewed</th><th>What</th><th>Verdict</th><th>By</th><th>Note</th></tr>' + "".join(
1162
- f'<tr><td>{nice(r["date"])}</td><td>the {e(r["stage"])}</td><td>{pill(r["verdict"], TONES.get(r["verdict"], "plain"))}</td><td>{e(r["by"])}</td><td>{review_note(r["note"])}</td></tr>' for r in x["reviews"]) + "</table>")
1234
+ f'<tr><td>{nice(r["date"])}</td><td>the {e(r["stage"])}</td><td>{word(r["verdict"])}</td><td>{e(r["by"])}</td><td>{review_note(r["note"])}</td></tr>' for r in x["reviews"]) + "</table>")
1163
1235
 
1164
1236
 
1165
1237
  def experiment_page(lab, T, x):
@@ -1181,7 +1253,7 @@ def experiment_page(lab, T, x):
1181
1253
  body.append(picture(lab, x))
1182
1254
  if x["state"] == "done" and x["label"] != "void": # what was observed comes first, apart from the plan
1183
1255
  body.append(slots(boxed(T, "What it means", s.get("Means", ""), "full key", x["id"]), boxed(T, "What was found", s.get("Found", ""), "full key", x["id"])))
1184
- body.append(f'<p class="outcome-line">{pill(x["outcome"], tone(x))} {e(decided_by(lab, x))}</p>')
1256
+ body.append(f'<p class="outcome-line">{status(x)} {e(decided_by(lab, x))}</p>')
1185
1257
  body.append(slots(so_far(lab, T, x, x["id"])))
1186
1258
  body.append(("<h2>The plan, as locked</h2>" if x["lock"] else "<h2>The plan, not locked yet</h2>") + slots(
1187
1259
  boxed(T, "What it compares", s.get("Compares", ""), extra=arms_table(lab, T, x)),
@@ -1391,7 +1463,7 @@ class Provider:
1391
1463
  body = re.sub(r"<h1>.*?</h1>", "", page["body"], count=1, flags=re.S)
1392
1464
  panels = [(title, _links(f'<div class="lv panelbox">{block}</div>')) for title, block in re.findall(r"<h4>(.*?)</h4>(.*?)(?=<h4>|$)", page["panel"], flags=re.S)]
1393
1465
  return View(title=page["title"], main=_links(f'<div class="lv">{body}</div>'), description=L.flat(description),
1394
- genre=genre, status=status, head=f"<style>{CSS}</style>", panels=panels, path=path)
1466
+ genre=genre, status=status, head=f"<style>{CSS}{header_css()}</style>", panels=panels, path=path)
1395
1467
 
1396
1468
  def rail(self):
1397
1469
  """The lab as a tree: each goal, its questions, each question's steps. Each row has the mark of its kind, its short
@@ -1401,7 +1473,7 @@ class Provider:
1401
1473
 
1402
1474
  def row(n, short):
1403
1475
  return {"title": n["title"], "url": f"/lab/{n['id']}/", "id": short, "kind": n["type"], "status": label(n), **({"mark": MARK[n["type"]]} if n["type"] in L.STEPS else {}),
1404
- "tone": tone(n), "sign": sign(n), "pulse": n["state"] == "running", "gone": n["state"] in ("replaced", "dropped")}
1476
+ "tone": tone(n), "sign": sign(n), "pulse": key(n) == "running", "gone": n["state"] in ("replaced", "dropped")}
1405
1477
 
1406
1478
  def summary(steps):
1407
1479
  out = {} # done and confirmed share a sign: one count
@@ -1429,7 +1501,9 @@ class Provider:
1429
1501
  questions.append({"title": f"set aside ({len(aside)})", "key": f"{g['id']}:aside", "fold": True, "items": [row(q, q["id"].split(".")[-1]) for q in aside]})
1430
1502
  out.append({**row(g, g["id"]), "items": questions, "summary": summary(under)})
1431
1503
  legend = [{"mark": MARK[k], "text": k} for k in L.STEPS]
1432
- legend += [{"sign": LOOK[k][1], "tone": LOOK[k][0], "status": MEANS[k], "text": MEANS[k]} for k in ORDER]
1504
+ seen = set()
1505
+ for _, keys in LEGEND:
1506
+ legend += [{"sign": LOOK[k][1], "tone": LOOK[k][0], "status": MEANS[k], "text": MEANS[k] + (f": {HINT[k]}" if k in HINT else "")} for k in keys if not (k in seen or seen.add(k))]
1433
1507
  out.append({"title": "Key", "legend": legend})
1434
1508
  return out
1435
1509
 
@@ -234,9 +234,15 @@ def answer(lab, target, verdict, text):
234
234
  """The agent's answer to a question, once its experiments are done."""
235
235
  n = lab.nodes.get(target)
236
236
  if verdict not in R.ANSWERS:
237
- stop("an answer is yes, no or mixed: mixed when part of what was expected held and part did not, saying which")
237
+ stop("an answer is yes, no or mixed for a test (mixed when part of what was expected held and part did not, saying which), or found for an estimate")
238
238
  if not n or n["type"] != "question":
239
239
  stop(f"no question {target}")
240
+ kind = R.question_kind(n)
241
+ if kind not in R.KINDS_OF_QUESTION:
242
+ stop(f"{target} has `kind: {kind}`: a question is a test or an estimate")
243
+ if verdict not in R.KINDS_OF_QUESTION.get(kind, ()):
244
+ stop(f"{target} is an estimate: it is answered `found`, with the finding itself" if kind == "estimate"
245
+ else f"{target} is a test: it is answered yes, no or mixed; an estimate (`kind: estimate` on its card) is answered found")
240
246
  if not R.flat(text):
241
247
  stop("an answer says what it rests on")
242
248
  if n["state"] != "open":
@@ -436,3 +436,27 @@ def test_a_table_with_no_rows_and_a_title_that_ends_in_a_mark_are_drawn(tmp_path
436
436
  assert "What we know so far" in page
437
437
  other = Provider(root).get("G1.Q1.3").main
438
438
  assert '<a class="page" href="/lab/G1.Q1/"' in other and ">Does the error halve when the sample quadruples?</a>" in other
439
+
440
+
441
+ def test_every_state_has_one_mark_on_every_page_and_now_carries_the_key(tmp_path):
442
+ from lab_kit import site as S
443
+ root, ident, d, command = locked(tmp_path)
444
+ lab(root, "run", ident, "--wait", "--", *command)
445
+ from test_integrity import done
446
+ done(root, ident, d)
447
+ lab(root, "answer", "G1.Q1", "no", "It halves at 400 flips, so the law does not need a correction.")
448
+ site = Provider(root)
449
+ question = next(r for r in site.rail() if r.get("kind") == "goal")["items"][0]
450
+ no = S.LOOK["no"]
451
+ assert (question["status"], question["tone"], question["sign"]) == ("answered no", no[0], no[1]) # the rail
452
+ now = site.get("").main
453
+ tile = now[now.index('class="tile'):]
454
+ assert f'<span class="stw t-{no[0]}"' in tile and f">{no[1]}</span>answered no" in tile # the tile on Now: the same mark and word
455
+ assert site.get("G1.Q1").status == "answered no" and 'data-s="answered no"' in S.header_css() # the page header draws the same mark
456
+ assert '<div class="legend">' in now and now.index('<div class="legend">') < now.index('class="goalrow"')
457
+ assert all(k in S.LOOK and k in S.MEANS for _, keys in S.LEGEND for k in keys)
458
+ assert len({S.LOOK[k] for k in ("open", "waiting", "running", "parked", "done", "dropped", "to discuss")}) == 7 # no two states share a mark
459
+ busy = {"type": "question", "state": "open", "items": [{"id": "G1.Q1.2", "state": "running"}]}
460
+ assert S.key(busy) == "running" and "G1.Q1.2 running" in S.dot(busy) and " live" in S.dot(busy) # a question with a running step pulses
461
+ assert S.key({"type": "goal", "state": "open", "questions": [busy]}) == "running"
462
+ assert S.key({**busy, "state": "parked"}) == "parked"
@@ -116,3 +116,23 @@ def test_a_need_is_met_by_what_a_replaced_experiment_made(tmp_path):
116
116
  front(reading, needs="[G1.Q1.2]")
117
117
  front(never, dropped='"Not needed after all."') # dropped with no finished run: what needs it waits for ever
118
118
  assert "which is dropped: remove the need or replace it" in lab(root, "show", "G1.Q1.3")
119
+
120
+
121
+ def test_a_test_is_answered_yes_no_or_mixed_and_an_estimate_with_what_was_found(tmp_path):
122
+ root = str(tmp_path)
123
+ qdir = open_question(root)
124
+ ident, d, command = experiment(root, command=WRITES % "0.5")
125
+ lab(root, "lock", ident)
126
+ lab(root, "run", ident, "--wait", "--", *command)
127
+ done(root, ident, d)
128
+ assert "is a test: it is answered yes, no or mixed" in lab(root, "answer", "G1.Q1", "found", "The ratio is 0.5.", ok=False)
129
+ front(f"{qdir}/question.md", kind="estimate")
130
+ assert "is an estimate: it is answered `found`" in lab(root, "answer", "G1.Q1", "yes", "It halves.", ok=False)
131
+ lab(root, "answer", "G1.Q1", "found", "The error at 400 flips is 0.5 of the error at 100, on one seed.")
132
+ assert "G1.Q1 (done, found)" in lab(root, "show", "G1.Q1") and "the record is sound" in lab(root, "check", "--no-rederive")
133
+ front(f"{qdir}/question.md", kind="test")
134
+ assert "is a test and is answered found" in lab(root, "check", "--no-rederive", ok=False)
135
+ front(f"{qdir}/question.md", kind="guess")
136
+ assert "`kind:` is test or estimate" in lab(root, "check", "--no-rederive", ok=False)
137
+ front(f"{qdir}/question.md", kind="[estimate]")
138
+ assert "`kind:` holds one value, not a list" in lab(root, "check", "--no-rederive", ok=False) # reported, not a crash
File without changes
File without changes
File without changes
File without changes