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.
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/.github/workflows/ci.yml +1 -1
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/.github/workflows/policy.yml +5 -3
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/.github/workflows/release.yml +1 -1
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/AGENTS.md +7 -4
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/CHANGELOG.md +45 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/PKG-INFO +3 -3
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/README.md +1 -1
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/docs/model.md +115 -38
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/method/METHOD.md +7 -3
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/pyproject.toml +3 -3
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/skills/lab-work/SKILL.md +24 -8
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/__init__.py +1 -1
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/checks.py +39 -14
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/cli.py +4 -1
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/history.py +26 -3
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/record.py +84 -59
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/runs.py +2 -2
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/site.py +264 -138
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/views.py +9 -9
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/write.py +13 -7
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_flow.py +7 -7
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_integrity.py +1 -1
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_needs.py +1 -1
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_order.py +1 -1
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_parked.py +5 -2
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_refusals.py +2 -2
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_site.py +58 -15
- lab_kit_cli-1.7.0/tests/test_states.py +138 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/.gitignore +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/CLAUDE.md +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/CONTRIBUTING.md +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/LICENSE +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/agents/reviewer.md +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/skills/lab-mission/SKILL.md +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/skills/lab-review/SKILL.md +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/skills/lab-set-up/SKILL.md +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/skills/lab-talk/SKILL.md +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/src/lab_kit/supervise.py +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_held.py +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_mission.py +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_vocabulary.py +0 -0
- {lab_kit_cli-1.5.0 → lab_kit_cli-1.7.0}/tests/test_wording.py +0 -0
- {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.
|
|
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.
|
|
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
|
|
48
|
-
line, tool or agent name, "generated with" footer or session link
|
|
49
|
-
branch name or a pull request
|
|
50
|
-
|
|
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.
|
|
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.
|
|
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
|
|
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
|
|
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. |
|
|
13
|
-
| **Question** | A short name, and a
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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,
|
|
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
|
|
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
|
|
207
|
-
|
|
208
|
-
the rows stay as they are.
|
|
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
|
|
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.
|
|
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
|
|
274
|
-
|
|
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
|
|
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
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
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
|
|
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
|
|
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
|
|
17
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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.
|
|
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`:
|
|
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>`.
|
|
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
|
|
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
|
|
236
|
-
|
|
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
|
|
245
|
-
line, and remove both when it clears.
|
|
246
|
-
|
|
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.
|
|
2
|
+
__version__ = "1.7.0"
|