lab-kit-cli 1.5.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.5.0 → lab_kit_cli-1.7.0}/.github/workflows/ci.yml +1 -1
  2. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/.github/workflows/policy.yml +5 -3
  3. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/.github/workflows/release.yml +1 -1
  4. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/AGENTS.md +7 -4
  5. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/CHANGELOG.md +45 -0
  6. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/PKG-INFO +3 -3
  7. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/README.md +1 -1
  8. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/docs/model.md +115 -38
  9. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/method/METHOD.md +7 -3
  10. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/pyproject.toml +3 -3
  11. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/skills/lab-work/SKILL.md +24 -8
  12. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/__init__.py +1 -1
  13. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/checks.py +39 -14
  14. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/cli.py +4 -1
  15. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/history.py +26 -3
  16. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/record.py +84 -59
  17. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/runs.py +2 -2
  18. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/site.py +264 -138
  19. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/views.py +9 -9
  20. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/write.py +13 -7
  21. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_flow.py +7 -7
  22. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_integrity.py +1 -1
  23. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_needs.py +1 -1
  24. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_order.py +1 -1
  25. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_parked.py +5 -2
  26. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_refusals.py +2 -2
  27. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_site.py +58 -15
  28. lab_kit_cli-1.7.0/tests/test_states.py +138 -0
  29. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/.gitignore +0 -0
  30. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/CLAUDE.md +0 -0
  31. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/CONTRIBUTING.md +0 -0
  32. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/LICENSE +0 -0
  33. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/agents/reviewer.md +0 -0
  34. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/skills/lab-mission/SKILL.md +0 -0
  35. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/skills/lab-review/SKILL.md +0 -0
  36. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/skills/lab-set-up/SKILL.md +0 -0
  37. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/skills/lab-talk/SKILL.md +0 -0
  38. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/supervise.py +0 -0
  39. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_held.py +0 -0
  40. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_mission.py +0 -0
  41. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_vocabulary.py +0 -0
  42. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_wording.py +0 -0
  43. {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.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
@@ -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
@@ -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:
@@ -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,50 @@
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
+
19
+ ## 1.6.0
20
+
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
22
+ Now page is a dashboard and its rail is the tree of goals, questions and steps; the Graph page is gone. It needs
23
+ folio 0.7.0, whose rail draws the tree. The skill `lab-work` and the method changed: run `lab init` in a lab after
24
+ upgrading.
25
+
26
+ - **Seven states, the same for every kind of card:** open, waiting, running, parked, done, replaced, dropped. What
27
+ was `planned`, `active` or `in progress` is open or running; `built` and `reached` are done; `under discussion`
28
+ is waiting. A done card may carry a label: a question's answer (yes, no or mixed) and an experiment's outcome
29
+ (confirmed, refuted, unclear, or void when its results review failed). `lab show` and `lab now` print
30
+ `done, confirmed`. A decision is open or done.
31
+ - **A failed results review makes an experiment done and void,** not a step to replace. No page uses its numbers,
32
+ and what it made may still be used.
33
+ - **`lab answer <question> yes|no|mixed`.** An answer rests on a done experiment that is not void.
34
+ - **A need is met by a done step, and by a replaced or dropped experiment whose run finished:** a later step may
35
+ use what such an experiment made (a frozen program), and says so with `needs:`.
36
+ - **`drops:` on a decision** drops the questions and steps it names once it is settled, like `parks:`. It is frozen
37
+ with the rest of what a settled decision says.
38
+ - **`waiting_on:` is for what is outside the lab.** `lab check` refuses one that names a goal, question, step or
39
+ decision: that wait never clears by itself. Builds and readings may carry it too.
40
+ - **So far says what was learned.** `lab check` refuses a question's So far with words that say where a step
41
+ stands ("is running", "is next", "no result yet"), and reports a So far last committed before a `result` line
42
+ about a step under the question, or one it names. `lab log <step> result` says so.
43
+ - **The site.** Now shows what is live with a pulsing sign (runs, the current mission, what the agent is on), what
44
+ needs the operator, what is next for the agent in the agreed order, a tile per question with one sign per step,
45
+ the resources and the latest events. The rail nests goal, question and step, opens on the current page, marks each
46
+ with a sign for its state, folds what was replaced, dropped or set aside, and ends with a key.
47
+
3
48
  ## 1.5.0
4
49
 
5
50
  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.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
@@ -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 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 yes-or-no question: 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
@@ -9,14 +9,48 @@ 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, 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
+ | **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, 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
50
+ label is its outcome: **confirmed**, **refuted** or **unclear**, read against the bars set before the
51
+ run, or **void** when its results review failed, so that its numbers cannot be cited. A decision is open,
52
+ then done; a mission's `status:` (next, current, done, stopped) reads on the pages as open, running,
53
+ done and dropped.
20
54
 
21
55
  Goal, question, experiment, run, result: each sits inside the one before it. Ids spell the path: `G1`,
22
56
  `G1.Q2`, `G1.Q2.3`, and a result is `G1.Q2.3:attack-success`. Decisions are `D1`, `D2`.
@@ -94,7 +128,7 @@ what it means and what was found, then says how many bars were met and names the
94
128
  outcome. There are no confidence numbers and no score sheet. A caveat the results raise goes in
95
129
  *Means*; what the experiment could never show is its Limits, written before the run.
96
130
 
97
- A build has no lock, no lines and no result. It ends as built, naming its commits and its tests.
131
+ A build has no lock, no lines and no result. It is done once it names its commits and its tests.
98
132
 
99
133
  A reading has no lock, no lines, no run and no review. It exists because much of what a lab learns
100
134
  comes from reading what it already has: why each failure failed, which tasks a defence costs, what
@@ -203,10 +237,11 @@ Each arrow is a command that refuses when the step before it is missing. You see
203
237
  or from a trial run that measured it. A trial that only showed the apparatus starts does not count.
204
238
  5. a failed run's partial numbers were read before the apparatus was changed for the next run.
205
239
 
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.
240
+ A plan review that fails is fixed before the lock, and read again. A results review that fails ends
241
+ the experiment as done with the outcome **void**: its run finished, but no card may name its results.
242
+ The plan and the rows stay as they are. A new experiment may name the one it replaces; the site then
243
+ folds the old one under it, and the old results keep re-deriving. What the void experiment made (a
244
+ frozen program, a built file) may still be used by later steps, which name it under `needs:`.
210
245
 
211
246
  A card never types a result's number. It names the result, and the value is filled in when the card is
212
247
  shown, written the way its row says it reads: a share as a percentage, a difference between two shares
@@ -243,11 +278,15 @@ approval: an experiment added later under a settled question is the agent's to p
243
278
 
244
279
  **Parking a question.** A question can be set aside without being dropped: not now, perhaps later. A settled
245
280
  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.
281
+ 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
282
  Nothing under it moves: `lab new` refuses a step under it, and `lab lock` and `lab run` refuse its experiments. It
248
283
  comes back only by a later settled decision that lists it under `unparks:`. The last settled decision, by number,
249
284
  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
285
+ never come back, with `dropped: <why>` on its card; park one that may.
286
+
287
+ **Dropping by a decision.** A settled decision may drop steps and questions by listing them under `drops:`
288
+ (each also under `about:`). A step or a question a settled decision drops is dropped, with that decision as
289
+ 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
290
  `dropped: <why>`, and a dropped goal drops every question under it.
252
291
 
253
292
  **The order of the work.** What the agent takes up first is agreed with you, and a settled decision records
@@ -265,13 +304,13 @@ work (a decision with a new `order:`), stop a run. Say it, and the agent records
265
304
  you as for the agent: a locked plan is changed by a new experiment that replaces it, and an outcome is
266
305
  worked out from the results, not decided.
267
306
 
268
- **A settled decision stays as it was settled.** Its `decided:`, its `about:`, its `parks:`, its `unparks:`, its `order:` and its Decided text never
307
+ **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
308
  change once committed; a change of mind is a new decision. `lab check` holds this against the lab's
270
309
  history. So a decision cannot be made, afterwards, to be about something it never discussed.
271
310
 
272
311
  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
274
- 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
275
314
  when no experiment of it is done: a reading alone answers nothing. `lab check` asks the same of every
276
315
  answered question, and that the log holds the line `lab answer` wrote. It never asks you to check
277
316
  its work, which is the review's job, and it never opens a decision for something that is its own to
@@ -356,7 +395,7 @@ missions before it takes a machine.
356
395
  `log` and `close` may leave out the mission while only one is current, and refuse to guess when several are.
357
396
  `lab now` names every open mission under **Right now**. A mission is not part of the record: `lab check` checks its
358
397
  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.
398
+ 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
399
 
361
400
  The log is one file. Every line carries its time. A line is one of five kinds: a decision was
362
401
  recorded, the agent decided, a result, something is stuck, and what the agent is starting on now.
@@ -431,8 +470,29 @@ A folder is named after its card's title, so a short title gives a short path.
431
470
 
432
471
  ## 7. The site
433
472
 
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.
473
+ Now (the dashboard), a page per goal, question, experiment, build, reading and decision, Decisions,
474
+ Log, Resources, Glossary. Every page has the copy-path control.
475
+
476
+ **The rail** on the left of every page is the lab as a tree: each goal, its questions under it, and
477
+ each question's steps under that. A row shows a mark for its type (G, Q, E, B, R), its short id, its
478
+ title and a mark for its state, whose colour and shape follow the state and, on done, the label; the
479
+ word is on hover. A running step's mark pulses. A goal or a question opens and closes, and a closed
480
+ one shows how many of the steps under it are in each state. The page being read is always opened in
481
+ place and marked, with its goal, its question and its siblings in view. A question's replaced and
482
+ dropped steps fold into one line at its end; a goal's parked and dropped questions into one line at
483
+ its end.
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.
436
496
 
437
497
  **How a page of a card reads.** Every page of a goal, a question or a step reads in the same order:
438
498
 
@@ -466,11 +526,14 @@ and where each stands, what it costs, what it cannot show, where to look. Half o
466
526
  the same briefing as text, which is what the agent says in chat when asked what is going on: the page
467
527
  and the answer in chat cannot differ. An experiment's page is the evidence behind one step.
468
528
 
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.
529
+ **Now** is the dashboard, read top to bottom in the order the operator asks, and all of it worked out:
530
+ what is live at this moment (each run going, the current mission with the last line of its log, what
531
+ the agent says it is on), each with a pulsing mark, and when the record last moved; what needs you (the
532
+ open decisions) and what is next for the agent, in the agreed order of the work; the map, one row per
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
536
+ latest events. There is no graph page: the rail is the tree and Now is the map.
474
537
 
475
538
  **An example on every question.** A question's page carries one case, step by step, as a numbered
476
539
  list that says who does what: the user, the agent, the tools, the gate, the scorer. A real episode
@@ -479,7 +542,7 @@ each role, states the design before the approximation, and lists its vocabulary:
479
542
  uses the same way, each drawn with the glossary's definition.
480
543
 
481
544
  **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
545
+ 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
546
  question with the decision that parked it and the first sentence of what was decided, then the dropped
484
547
  questions and the closed goals, folded. A goal's page folds its parked and its dropped questions; a parked
485
548
  question's page says, at the top, which decision parked it and why. `lab now` lists the parked questions in
@@ -537,17 +600,17 @@ and its sealed runs across as what they were.
537
600
  **A card** is front matter, then its description as a paragraph, then `## Slot` sections. It never
538
601
  holds an id, a state or an outcome. Every file of a lab is UTF-8 text; line ends of either kind
539
602
  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`,
603
+ the first two lines that are exactly `---`. A key that holds a list (`needs`, `uses`, `see`, `about`, `holds`, `parks`, `unparks`, `drops`, `order`, `commits`,
541
604
  `tests`) is written as one, `[a, b]`; every other key holds one value.
542
605
 
543
606
  | Card | Front matter | Slots (word budget) |
544
607
  | --- | --- | --- |
545
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) |
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) |
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) |
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) |
611
+ | `reading.md` | `title:`, `needs:`, `waiting_on:`, `dropped: <why>` | description (70), Looks at: what, and where it is (120), Seen (360), Suggests (150) |
612
+ | `build.md` | `title:`, `needs:`, `waiting_on:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
613
+ | `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
614
 
552
615
  **Why these budgets.** A budget is a ceiling. In 1.3.0 the budgets of the slots that hold a table or a
553
616
  numbered list (an experiment's Compares, Cases, Outcomes and So far, a question's So far and How we
@@ -563,6 +626,14 @@ plan, so it may change after the lock; a card written before 1.3.0 may leave it
563
626
  carry a Note: one or two sentences a reader of the pages it is about must know. While a card's So far
564
627
  says nothing, its page shows there the Notes of the settled decisions about it.
565
628
 
629
+ **So far says what was learned, never where a step stands.** The pages draw each step's state from the
630
+ record, so a So far that says a step "is running", "is next" or has "no result yet" can only go stale,
631
+ and `lab check` reports those words in a question's So far. It also reports a question whose card was
632
+ last committed before the newest `result` line about a step under it, or about a step its So far names:
633
+ the result came in and the question was not brought up to date. `lab log <step> result` says which
634
+ question to bring up to date. Where git cannot tell (no history, the card changed and not committed),
635
+ nothing is reported.
636
+
566
637
  **A picture.** Any goal, question, experiment, build or reading may have a `picture.svg` beside its
567
638
  card. It is drawn inline at the top of its page, after the title and the lead. It shows the whole
568
639
  work as numbered steps: what goes in, who does what, the checks, the tools, how it is counted, the
@@ -660,7 +731,7 @@ A test is a result's name, one of `<`, `<=`, `>`, `>=`, and a number. At most si
660
731
  **A named result** on a card is `{name}` inside its own experiment and `{G1.Q1.2:name}` elsewhere.
661
732
 
662
733
  **`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
734
+ 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
735
  plain number), `reads` (`percent` for a share, `points` for a difference between two shares, or empty),
665
736
  `versus` (what it is compared with), `command` (run from the lab's root with `RUN` set to the finished
666
737
  run's folder; prints `value` exactly, and reads `$RUN`, or it would not be printing from the sealed
@@ -771,20 +842,26 @@ holds the line `launched`, else next, and `lab check` asks for the status to be
771
842
  reports a mission that breaks any of this, one whose `carries:` is not a decision, and a current mission whose
772
843
  decision is still open.
773
844
 
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.
845
+ **Worked-out states.** A goal is open until `reached: true` makes it done or `dropped:` drops it. A
846
+ question is waiting while the decision it came from is open, then open, then done with its answer; it
847
+ is parked while the last settled decision that parks or brings it back parks it. A step is waiting while
848
+ something holds it: a step it needs, an open decision, its question or goal not being open, or its
849
+ `waiting_on:`. A build or a reading is running once the log has a line about it; a build is done once
850
+ it names its commits, a reading once it says what was seen and what it suggests. An experiment is running
851
+ while a run of it is going, and done once its results are reviewed (its label is the outcome) or its
852
+ results review failed (its label is void).
778
853
 
779
854
  **What a step needs.** `needs:` on an experiment, a build or a reading names other steps, anywhere in
780
855
  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
856
+ while one it needs is not done, and `lab lock` and `lab run` refuse it until then. An experiment that
857
+ was replaced or dropped after a run of it finished made what it made: a need on it is met, and its page
858
+ lists the steps that use it. Each
782
859
  step's state is worked out after the state of everything it needs, wherever that sits, so the order
783
860
  of the cards changes nothing: a build under the second question that needs a reading under the third
784
861
  moves as soon as that reading is done. Every view says the same: `lab now`, `lab show`, `lab brief`,
785
862
  and the site's pages and rail. Steps that need each other in a circle are a problem `lab check`
786
863
  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
864
+ 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
865
  for ever, so what it waits on says so, and says what to do: remove the need or replace it. A need
789
866
  that names nothing in the lab, or something that is not a step, holds the step in `lab lock` and
790
867
  `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.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" }]
@@ -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
@@ -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
@@ -178,6 +181,10 @@ until that decision is settled; after that it needs no further yes.
178
181
  9. Once the review has passed, write **Found** and **Means** on the card. Name each result instead
179
182
  of typing its number: `{attack-success}`. It is shown the way its row says it reads. Bring the
180
183
  experiment's **So far** up to date, and rewrite the question's **So far** the same way, with full names: `{G1.Q1.2:attack-success}`.
184
+ So far says what was learned, never where a step stands ("is running", "is next", "no result yet"):
185
+ the pages draw each step's state. `lab check` reports a question's So far that was last committed
186
+ before a result under it, or one it names. Give each result a label that says what it counts and
187
+ of how many, in a set of cases the lab names once ("of the 20 checks the solver leaves open").
181
188
  10. `lab log <experiment> result "<what was found, in a sentence, without numbers>" "<so what>"`.
182
189
 
183
190
  The outcome is worked out from the lines: you never write it.
@@ -232,8 +239,11 @@ repository, tests first. When it works, put `commits:` and `tests:` on the card
232
239
 
233
240
  ## When all experiments of a question are done
234
241
 
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
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
246
+ void. If they do not answer it, add the next experiment. An answer usually changes
237
247
  what should come next: open a decision.
238
248
 
239
249
  ## When something is in the way
@@ -241,9 +251,15 @@ what should come next: open a decision.
241
251
  - **It is yours to decide.** Decide, `lab log <id> agent "<what you decided>" "<why>"`, go on.
242
252
  - **It is the operator's** (direction or resources). Open a decision, then work on what it does not
243
253
  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.
254
+ - **It waits on something outside the lab** (an account, a person, a machine being repaired). Put
255
+ `waiting_on: <what>` on the card, log a `stuck` line, and remove both when it clears. A wait on the
256
+ lab's own work is a `needs:`, or a decision's `holds:`: `lab check` refuses a `waiting_on:` that
257
+ names a goal, question, step or decision.
258
+ - **It will not be done.** Put `dropped: <why>` on the card and log it. When a decision drops it,
259
+ the decision lists it under `drops:`, and the card needs nothing more.
260
+ - **A later step uses what a replaced or void step made** (a frozen program, a data set). Put the
261
+ step under `needs:`: a need is met by a done step, and by a replaced or dropped experiment whose
262
+ run finished.
247
263
  - **A run's process died.** `lab runs close <run> "<why>"`. It stops whatever the run left going and
248
264
  reads the run's `used.json`. If the run used a metered resource and wrote none, say what it used:
249
265
  `--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.7.0"