lab-kit-cli 1.0.1__tar.gz → 1.0.3__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 (37) hide show
  1. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/CHANGELOG.md +63 -0
  2. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/PKG-INFO +1 -1
  3. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/docs/model.md +81 -8
  4. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/pyproject.toml +1 -1
  5. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/skills/lab-set-up/SKILL.md +4 -1
  6. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/skills/lab-work/SKILL.md +10 -4
  7. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/__init__.py +1 -1
  8. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/checks.py +33 -16
  9. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/history.py +36 -2
  10. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/record.py +89 -12
  11. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/runs.py +3 -1
  12. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/site.py +21 -3
  13. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/views.py +25 -2
  14. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/write.py +2 -0
  15. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tests/test_held.py +174 -1
  16. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tests/test_integrity.py +23 -0
  17. lab_kit_cli-1.0.3/tests/test_needs.py +148 -0
  18. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tests/test_refusals.py +1 -1
  19. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tests/test_site.py +25 -3
  20. lab_kit_cli-1.0.3/tests/test_vocabulary.py +116 -0
  21. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/.github/workflows/ci.yml +0 -0
  22. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/.github/workflows/policy.yml +0 -0
  23. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/.github/workflows/release.yml +0 -0
  24. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/.gitignore +0 -0
  25. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/AGENTS.md +0 -0
  26. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/CLAUDE.md +0 -0
  27. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/CONTRIBUTING.md +0 -0
  28. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/LICENSE +0 -0
  29. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/README.md +0 -0
  30. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/agents/reviewer.md +0 -0
  31. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/method/METHOD.md +0 -0
  32. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/skills/lab-review/SKILL.md +0 -0
  33. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/skills/lab-talk/SKILL.md +0 -0
  34. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/cli.py +0 -0
  35. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/src/lab_kit/supervise.py +0 -0
  36. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tests/test_flow.py +0 -0
  37. {lab_kit_cli-1.0.1 → lab_kit_cli-1.0.3}/tools/import_run.py +0 -0
@@ -1,5 +1,68 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.0.3
4
+
5
+ A word is now defined in one place, `GLOSSARY.md`. Before, the glossary and the goal's Vocabulary
6
+ both said what a word means, and the two could drift. The skills `lab-work` and `lab-set-up` changed:
7
+ run `lab init` in a lab after upgrading, or `lab check` reports that they differ from the installed
8
+ kit. Change the goal's Vocabulary to names, too: see below.
9
+
10
+ - A glossary entry may carry two more lines beside `- code:`. `- avoid: gate, filter, policy` lists
11
+ the words not to use for the thing; `- see: entries/kna-gate` (or a page of a library the charter
12
+ names, such as `pier-folio:/content/concepts/lora/`) names a page that explains the concept.
13
+ `lab define` prints both, and the glossary page shows the avoid words in small type and the page as a
14
+ link. The hover on a term stays the definition alone. `lab check` checks a `see` as it checks a
15
+ card's `see:`. It does not flag avoid words used in cards: a word to avoid for one thing is often right
16
+ for another.
17
+ - The goal's Vocabulary is a list of names only (`- field`). The goal's page and `lab show` draw
18
+ each with its glossary definition. `lab check` reports a name that is not a glossary term. A goal
19
+ written the old way (`- word: meaning`) still shows the glossary's definition, never the card's, and
20
+ `lab check` reports it: list the name only, and add the term to the glossary if it is missing there.
21
+ An existing lab must change its goal's Vocabulary to names.
22
+
23
+ ## 1.0.2
24
+
25
+ One defect found while rehearsing a real lab, four follow-ups from 1.0.1, and three larger word
26
+ budgets. The skill `lab-work` changed with the budgets: run `lab init` in a lab after upgrading, or
27
+ `lab check` reports that the skill differs from the installed kit.
28
+
29
+ - A step may need a step that sits later in the tree, such as a build under the second question
30
+ that needs a reading under the third. States used to be worked out in the order of the cards, so
31
+ the earlier step never saw that the later one was done: it stayed under "Not yours to move yet",
32
+ waiting on a step that was done, and `lab lock` and `lab run` refused it. Each step's state is now
33
+ worked out after everything it needs, wherever that sits. `lab now`, `lab show`, `lab brief` and
34
+ the site agree, since they read the same states.
35
+ - Steps that need each other in a circle were already a problem in `lab check`. Now none of them
36
+ moves until the circle is broken, even when one of them is done, and each says which need leads
37
+ back to it.
38
+ - Rows that a committed review passed stay. A reviewed `results.tsv` could be emptied together with
39
+ the card's Found and Means, committed, and later filled with other rows and reviewed again, with
40
+ `lab check` sound at every step. Once a results review that passed is committed with the rows it
41
+ read, those rows are held, whatever the card and the file say later. A draft row committed after
42
+ a review, which that review never read, may still be corrected.
43
+ - A step that needs one that is dropped or replaced says so in what it waits on, with what to do:
44
+ remove the need or replace it. A need that names nothing in the lab, or something that is not a
45
+ step, now holds the step in `lab lock` and `lab run`, as `lab check` already reported it.
46
+ - A `.pyc` file in `plan/` outside `__pycache__` is refused by `lab lock` and `lab run` and reported
47
+ by `lab check`, as a link is: Python would import it, and the plan's hash does not cover it.
48
+ - `lab check` says in a note when the repository is a shallow clone, and fails with `--strict`: the
49
+ history check needs every commit, and CI should fetch all of the history (`fetch-depth: 0`). The
50
+ model also says that the history read is that of the record under the lab's root as it is now,
51
+ so moving the root inside the repository starts again what is held.
52
+ - A plan that 1.0.0 locked or ran while a `__pycache__` sat in `plan/` verifies again. 1.0.0 counted
53
+ those files in the plan's hash and 1.0.1 does not, so such a record could never match. When a
54
+ hash of `plan/` does not match and the experiment's lock was made by 1.0.0, the folder is hashed
55
+ once more the way 1.0.0 did before a change is reported. It applies to no other lock, and only
56
+ while the cache files are still there as they were.
57
+ - `lab show <experiment>` says of each run how many files it holds, how many at the top of its
58
+ folder and how many under each folder there. It used to list ten files and leave out `work/`, so
59
+ a run whose output was all in `work/` looked nearly empty.
60
+ - Three word budgets are larger, because real cards were hitting them and ending in fragments: an
61
+ experiment's Found goes from 130 words to 180 and its Means from 90 to 150, and a question's So
62
+ far from 120 to 180. A budget is a ceiling against sprawl. If a card needs its last words cut
63
+ into fragments to fit, it is saying too much for one slot or the budget is wrong, and full
64
+ sentences win.
65
+
3
66
  ## 1.0.1
4
67
 
5
68
  Three defects found by moving a real repository to 1.0.0, and one message.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.0.1
3
+ Version: 1.0.3
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
@@ -32,7 +32,9 @@ leads to is complete: it never points at something it does not explain ("the sev
32
32
  reproduction's setting", "our loop") without saying what that is in the same place. An experiment
33
33
  names each arm and says what it is. A term is explained in the sentence that first uses it; the
34
34
  glossary is a second chance, not the explanation. A slot may hold paragraphs and a list when that
35
- is clearer than one long sentence. The word budgets are ceilings against sprawl, not targets.
35
+ is clearer than one long sentence. The word budgets are ceilings against sprawl, not targets. If a
36
+ card needs its last words cut into fragments to fit, the card is saying too much for one slot or
37
+ the budget is wrong, and full sentences win.
36
38
 
37
39
  A run's id is `<date>-<time>_<experiment>_<four random characters>`, for example
38
40
  `20261110-1432_G1.Q2.3_k7f2`. It sorts by time, and two machines starting runs in the same minute cannot
@@ -149,6 +151,19 @@ Each arrow is a command that refuses when the step before it is missing. You see
149
151
  `lab now` and `lab check` say which locks and lists of runs are not committed yet. With no commit
150
152
  at all nothing is held, and `lab check` says that too; `--strict` turns each of these into a
151
153
  failure.
154
+ **Reviewed rows stay.** The rows of `results.tsv` may change until a review passes them. Once a
155
+ results review that passed is committed together with the rows it read, those rows stay, each as
156
+ it was, whatever happens to the card and to the reviews after it. Emptying the file or removing it
157
+ together with Found and Means, and filling it later with other rows for a new review, is a
158
+ problem `lab check` reports at every step: a different result is a new experiment. A review is
159
+ bound to the rows it read by its `of`, so only those are held: a draft row committed after a
160
+ review, which that review never read, may still be corrected before the next review reads it.
161
+ **The history that is read.** The check reads the history of the record under the lab's root as
162
+ that root is now. Moving the lab's root inside its repository, or to another repository, starts
163
+ again what is held: what was committed under the old root is not compared. And it needs the
164
+ repository's full history. A shallow clone holds only its last commits, so against it almost
165
+ nothing is held: `lab check` says so in a note, and fails with `--strict`. CI fetches all of the
166
+ history before it checks (`fetch-depth: 0` in `actions/checkout`).
152
167
  **Where the record is.** The check reads the history of the lab's own record and of nothing else:
153
168
  `log.md` and `resources.toml` at the lab's root, `decisions/D<n>-<name>.md`, and each experiment's
154
169
  `lock.json`, `runs.tsv`, `results.tsv` and `reviews.tsv` in its folder,
@@ -265,7 +280,10 @@ that resource, under `about:`.
265
280
  ## 5. What the agent uses
266
281
 
267
282
  - **To look:** `lab now`, `lab show <id or path>`, `lab brief <question>`, `lab since`, `lab define <term>`. Each shows one level,
268
- so the agent reads a card before it opens a file.
283
+ so the agent reads a card before it opens a file. Of each run, `lab show <experiment>` says how
284
+ many files it holds and where: how many at the top of its folder, and how many under each folder
285
+ there, `work/` included. It lists none of them, so a run whose output is all in `work/` does not
286
+ look empty.
269
287
  - **To write:** `lab new` (a goal, a question, an experiment, a build, a reading, a decision),
270
288
  `lab log`, `lab decide`, `lab answer`.
271
289
  - **To be seen:** `lab log <id> doing "<what>" "<why now>"` whenever it starts on a card. It is the
@@ -307,7 +325,7 @@ Seven rules:
307
325
  Never record a decision that was not discussed with them.
308
326
  7. Say what you are on. When you start on a card, log what you are doing and why now.
309
327
 
310
- `lab check` holds what can be held mechanically: ids and links, a title and a description on every
328
+ `lab check` holds what can be held mechanically: ids and links, the goal's vocabulary being terms of the glossary, a title and a description on every
311
329
  card, short cards that write only their own front matter, a test on every line, a reason on every
312
330
  replacement, unchanged locks, sealed runs, results that still re-derive and were reviewed, use inside
313
331
  the resources' amounts, a decision behind every goal, question and metered amount, an experiment
@@ -317,7 +335,7 @@ file that is not text) is a problem it reports; no command stops on it.
317
335
 
318
336
  `lab check` runs the command of every row in every `results.tsv`, as a shell command, each for at
319
337
  most `rederive_timeout` seconds (`lab.toml`, 120 unless set). Run it only on a lab you trust, as
320
- you would its code; `--no-rederive` runs none of them. Where the lab has no commit, the store
338
+ you would its code; `--no-rederive` runs none of them. Where the lab has no commit or its repository is a shallow clone, the store
321
339
  is not mounted, or another library that a card's `see:` points into is not on the machine, the check
322
340
  says in a note what it could not check and still passes; with `--strict` that is a failure, which is
323
341
  what CI wants.
@@ -369,7 +387,8 @@ resource. Nothing on it is static text except one line per goal.
369
387
  **An example on every question.** A question's page carries one case, step by step, as a numbered
370
388
  list that says who does what: the user, the agent, the tools, the gate, the scorer. A real episode
371
389
  where one exists, and said to be only the flow where none does. The goal's page says once who plays
372
- each role, states the design before the approximation, and pins the vocabulary.
390
+ each role, states the design before the approximation, and lists its vocabulary: the words every card
391
+ uses the same way, each drawn with the glossary's definition.
373
392
 
374
393
  **What was dropped** stays in the record: a dropped goal or question keeps its card and its page,
375
394
  and leaves Now, the rail and the graph.
@@ -431,9 +450,9 @@ the first two lines that are exactly `---`. A key that holds a list (`needs`, `u
431
450
 
432
451
  | Card | Front matter | Slots (word budget) |
433
452
  | --- | --- | --- |
434
- | `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, `- <word>: <what it means>`, the few words every card uses the same way (260) |
435
- | `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 (130), How we would know (150), Example: one case step by step, a numbered list (380), We expect (70), Wrong if (70), So far (120) |
436
- | `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:`, `dropped: <why>` | description (70), Compares: the comparison in a sentence (80), Arms (260), Cases (100), Confirmed if (150), Refuted if (110), Outcomes (200), Limits (120), Found (130), Means (90) |
453
+ | `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) |
454
+ | `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 (130), How we would know (150), Example: one case step by step, a numbered list (380), We expect (70), Wrong if (70), So far (180) |
455
+ | `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:`, `dropped: <why>` | description (70), Compares: the comparison in a sentence (80), Arms (260), Cases (100), Confirmed if (150), Refuted if (110), Outcomes (200), Limits (120), Found (180), Means (150) |
437
456
  | `reading.md` | `title:`, `needs:`, `dropped: <why>` | description (70), Looks at: what, and where it is (110), Seen (320), Suggests (150) |
438
457
  | `build.md` | `title:`, `needs:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
439
458
  | `D<n>-<slug>.md` | `title:`, `about:` (the goals, questions, experiments or resources it concerns), `date:`, `holds:`; `decided: {date, with}` is written by `lab decide` | Seen (120), Options: a list, one option an item (200), Recommendation (80), Decided (120) |
@@ -450,6 +469,36 @@ as in CI, which checks out the lab alone, the page cannot be looked for: that is
450
469
  failure only with `--strict`. When the folder is there and the page is not, or the charter names no
451
470
  such library, it is a problem.
452
471
 
472
+ **The glossary** is `GLOSSARY.md`, the only place a word is defined. A group is a `# Group` heading
473
+ and a term a `## Term` heading under it, followed by its definition as a paragraph and these optional
474
+ lines, each `- key: value`:
475
+
476
+ ```
477
+ ## Guard
478
+ The part that reads every call and refuses the ones the contract forbids.
479
+ - code: kna.gate:Guard
480
+ - avoid: gate, filter, policy
481
+ - see: entries/kna-gate
482
+ ```
483
+
484
+ `code:` is where the term is in the code. `avoid:` lists, separated by commas, the words not to use
485
+ for this thing. `see:` names a page that explains the concept: a page of the lab's own library
486
+ (`entries/kna-gate`) or of a library the charter names (`pier-folio:/content/concepts/lora/`), the
487
+ same targets a card's `see:` takes. `lab define <term>` prints all of it. The glossary page shows the
488
+ definition, the code, the page as a link and the avoid words in small type; the hover on a term in
489
+ prose is the definition alone.
490
+
491
+ A word is defined once, in the glossary. A card that needs a word adds it there first, then uses it;
492
+ no card defines a word of its own. A concept that is not this lab's own (a method, a paper's idea) gets
493
+ a one-line entry and a `see:` link to the page that explains it, not a new explanation. The goal's
494
+ Vocabulary lists terms by name, and the goal's page and `lab show` draw each with the glossary's
495
+ definition and avoid words. `lab check` holds this: a name in Vocabulary that is not a term of the
496
+ glossary is a problem, and so is an item written with a meaning (`- word: what it means`): the part
497
+ before the colon is taken as the name, the glossary's text is what is shown, and the card must list the
498
+ name only. It checks an entry's `see:` as it checks a card's, including the note, and no failure, when
499
+ the other library is not on the machine. It does not look for avoid words in cards: a word to avoid for
500
+ one thing is often the right word for another, so `avoid:` is for the writer and the reviewer to read.
501
+
453
502
  **An arm** is a list item under Arms: its name, a colon, and what it is, so that a reader who has
454
503
  never seen it knows what was run.
455
504
 
@@ -518,6 +567,16 @@ it imports a script, which is no part of the plan: a folder named `__pycache__`
518
567
  it, and any file whose name ends in `.pyc`, wherever it sits. Nothing else is left out; a hidden
519
568
  file is hashed like any other.
520
569
 
570
+ One exception, for what lab-kit 1.0.0 made. That version did hash those files, so a plan locked or
571
+ run while a `__pycache__` sat in `plan/` holds a hash that counts them. When a hash of `plan/` held
572
+ by a lock or a run does not match and the experiment's lock says `"kit": "1.0.0"`, the folder is
573
+ hashed once more the way 1.0.0 did, those files included, before a change is reported. It applies
574
+ to no other lock, and it verifies only while those files are still there as they were.
575
+
576
+ A `.pyc` file in `plan/` that is not inside a `__pycache__` is refused, as a link is: Python would
577
+ import it in place of a script, and no hash covers it. `lab lock` and `lab run` refuse the plan and
578
+ `lab check` reports it. Under a lock that 1.0.0 made, whose hash did count such a file, it stays.
579
+
521
580
  **`runs.tsv`**, beside the lock and in git, is written by `lab run` and by the run as it ends: `run`
522
581
  (its id), `kind` (run, trial), `what` (started, ended, lost), `at`, on the ended row `exit` and `seal`,
523
582
  and on a lost row `used` (`{"<resource>": <amount>}`, or empty) and `note` (why it is lost). When a
@@ -537,3 +596,17 @@ starting on and why now. A line written before the kit kept the time has none.
537
596
  open, then yes or no; a page calls an open question with nothing under it "not started". A build is in
538
597
  progress once the log has a line about it, and built once it names its commits. An experiment whose
539
598
  results review failed shows as review failed until it is replaced or dropped.
599
+
600
+ **What a step needs.** `needs:` on an experiment, a build or a reading names other steps, anywhere in
601
+ the tree: under its own question or another, before it or after it. A step is not the agent's to move
602
+ while one it needs is neither done nor built, and `lab lock` and `lab run` refuse it until then. Each
603
+ step's state is worked out after the state of everything it needs, wherever that sits, so the order
604
+ of the cards changes nothing: a build under the second question that needs a reading under the third
605
+ moves as soon as that reading is done. Every view says the same: `lab now`, `lab show`, `lab brief`,
606
+ and the site's pages and rail. Steps that need each other in a circle are a problem `lab check`
607
+ reports. Until the circle is broken none of them moves, whatever the others' states, and each says
608
+ which of its needs leads back to it. A step that needs one that is dropped or replaced would wait
609
+ for ever, so what it waits on says so, and says what to do: remove the need or replace it. A need
610
+ that names nothing in the lab, or something that is not a step, holds the step in `lab lock` and
611
+ `lab run` as `lab check` reports it. A question's `needs:` names the questions it builds on, for its
612
+ briefing; it changes no state.
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  dynamic = ["readme"]
7
7
  name = "lab-kit-cli"
8
- version = "1.0.1"
8
+ version = "1.0.3"
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" }]
@@ -37,7 +37,10 @@ You set the lab up in one discussion with the operator, so that everything it se
37
37
  9. Fill `lab.toml` (`code` for the code repository, `store` if the runs live elsewhere) and the
38
38
  local rules in `AGENTS.md`.
39
39
  10. Start `GLOSSARY.md`: each term the cards use that an outsider would not know, one sentence, with
40
- its name in the code when it has one.
40
+ its name in the code when it has one (`- code: module:Name`), the words not to use for it
41
+ (`- avoid: a, b`) and a page that explains it (`- see: <page>`) when there is one. The glossary is the
42
+ only place a word is defined: the goal's Vocabulary lists names, and a card that needs a word adds it
43
+ here first.
41
44
  11. The site: the lab's `docs/` folder is a folio library whose charter lists `lab_kit.site` under
42
45
  `views:`. Set it up with folio's own skill if it is not there.
43
46
 
@@ -36,14 +36,20 @@ The operator reads every card on the site, usually days later and without you. W
36
36
  - A paper, a method or a tool the reader may not know gets a few words saying what it is, and a
37
37
  link where it is first named: `[PISmith](pier-folio:/content/readings/...)` for a page of a
38
38
  library the charter names, or a web address. Put the same page under `see:`.
39
- - Use the goal's vocabulary. The goal's card pins the few words the lab uses for its own things;
40
- use those words, the same way, on every card, and add a word there before you use a new one.
39
+ - A word is defined once, in `GLOSSARY.md`, and nowhere else. Use the goal's vocabulary: the goal's
40
+ card lists, by name only (`- field`), the few words the lab uses for its own things; use those words,
41
+ the same way, on every card, and read a term's `avoid:` words as the ones not to use for it. When a
42
+ card needs a new word, add it to the glossary first, then list it on the goal if every card uses it.
43
+ A generic concept that is not this lab's own gets a one-line glossary entry and a `- see:` link to the
44
+ page that explains it, not a new explanation.
41
45
  - Say the design before the approximation: what the idea wants, then how this lab builds it and
42
46
  where it knowingly differs. A shortcut of the implementation is never the definition.
43
47
  - Say what is measured and what is your reading of it, in so many words.
44
48
  - Use a list when the content is a list (arms, options, steps), and a second paragraph when one
45
49
  sentence is carrying too much. The word budgets are ceilings, not targets: short is good only
46
- while nothing is missing.
50
+ while nothing is missing. A budget is there against sprawl. If a card needs its last words cut
51
+ into fragments to fit, the card is saying too much for one slot or the budget is wrong, and full
52
+ sentences win.
47
53
  - Read the card as someone who was not there. If a question comes to mind, the card answers it.
48
54
 
49
55
  ## When to open a decision
@@ -206,7 +212,7 @@ what should come next: open a decision.
206
212
  - Never write that the operator decided something outside a decision recorded with `lab decide` (the
207
213
  lab-talk skill).
208
214
  - Open `plan/` and `runs/` only for the experiment you are working on.
209
- - A term an outsider would not know goes in `GLOSSARY.md`, once, and is used the same way everywhere.
215
+ - A term an outsider would not know goes in `GLOSSARY.md`, once, and is used the same way everywhere. A card never defines a word itself, and the goal's Vocabulary holds names, not meanings.
210
216
 
211
217
  ## Before you stop
212
218
 
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.0.1"
2
+ __version__ = "1.0.3"
@@ -27,6 +27,22 @@ def run(lab, rederive=True):
27
27
  unchecked = True
28
28
 
29
29
  absent = {} # the libraries the charter names whose folder is not on this machine
30
+
31
+ def see(where, page, who=""):
32
+ """A page a card's `see:` or a glossary entry's `- see:` names is there."""
33
+ if ":" in str(page): # a page of another library the charter names, such as background reading
34
+ from . import site
35
+ name, _, path = str(page).partition(":")
36
+ lib = site.libraries(lab).get(name)
37
+ if not lib:
38
+ bad("links", where, f"{who}see names {page}, which is not a page of a library the charter names")
39
+ elif not os.path.isdir(lib["path"]): # the other library is not on this machine, as in CI: nothing to look in
40
+ absent.setdefault(name, lib["path"])
41
+ elif not os.path.exists(os.path.join(lib["path"], path.lstrip("/"))):
42
+ bad("links", where, f"{who}see names {page}, and the library {name} holds no such page")
43
+ elif not os.path.exists(os.path.join(library, str(page).split("#")[0], "index.html")):
44
+ bad("links", where, f"{who}see names the page {page}, which is not in the library")
45
+
30
46
  # cards: each has its slots, stays short, and writes only what is its to write
31
47
  for n in lab.goals + lab.questions + lab.items + lab.decisions:
32
48
  try:
@@ -51,20 +67,18 @@ def run(lab, rederive=True):
51
67
  if n["type"] in ("goal", "question") and nodes.get(str(n.get("from")), {}).get("type") != "decision":
52
68
  bad("links", n["path"], f"`from:` names the decision it came out of; {n.get('from')!r} is not one")
53
69
  for page in n.get("see") or []:
54
- if ":" in str(page): # a page of another library the charter names, such as background reading
55
- from . import site
56
- name, _, path = str(page).partition(":")
57
- lib = site.libraries(lab).get(name)
58
- if not lib:
59
- bad("links", n["path"], f"see names {page}, which is not a page of a library the charter names")
60
- elif not os.path.isdir(lib["path"]): # the other library is not on this machine, as in CI: nothing to look in
61
- absent.setdefault(name, lib["path"])
62
- elif not os.path.exists(os.path.join(lib["path"], path.lstrip("/"))):
63
- bad("links", n["path"], f"see names {page}, and the library {name} holds no such page")
64
- elif not os.path.exists(os.path.join(library, str(page).split("#")[0], "index.html")):
65
- bad("links", n["path"], f"see names the page {page}, which is not in the library")
70
+ see(n["path"], page)
71
+ if n["type"] == "goal": # the words a goal lists are names; GLOSSARY.md is the only place a word is defined
72
+ for w in lab.vocabulary(n):
73
+ if not w["entry"]:
74
+ bad("cards", n["path"], f"Vocabulary lists {w['name']!r}, which is not a term in GLOSSARY.md: add it there first, and list the name only")
75
+ elif w["old"]:
76
+ bad("cards", n["path"], f"Vocabulary lists {w['name']!r} with a meaning: list the name only, `- {w['name']}`; GLOSSARY.md defines it")
77
+ for g in lab.glossary:
78
+ if g["see"]:
79
+ see("GLOSSARY.md", g["see"], f"{g['term']}: ")
66
80
  for name, path in sorted(absent.items()):
67
- notes.append(f"the library {name} is not here ({path}): the pages cards name in it under `see:` could not be checked here")
81
+ notes.append(f"the library {name} is not here ({path}): the pages cards and the glossary name in it under `see:` could not be checked here")
68
82
  unchecked = True
69
83
  for d in {os.path.dirname(x["path"]) for x in lab.items}:
70
84
  if sum(os.path.exists(os.path.join(root, d, f"{kind}.md")) for kind in R.STEPS) > 1:
@@ -150,6 +164,9 @@ def run(lab, rederive=True):
150
164
  links = R.symlinks(os.path.join(d, "plan"))
151
165
  if links:
152
166
  bad("locks", p, f"plan/ holds a link, {links[0]}: what a link points at is not in plan/ and is not pinned")
167
+ stray = R.compiled(os.path.join(d, "plan")) if (x["lock"] or {}).get("kit") != "1.0.0" else [] # 1.0.0 hashed such a file with the plan
168
+ if stray:
169
+ bad("locks", p, f"plan/ holds a compiled file outside __pycache__, {stray[0]}: Python would import it, and a `.pyc` is not pinned")
153
170
  if x["lock"]:
154
171
  if lab.nodes[x["question"]]["state"] == "under discussion":
155
172
  bad("locks", p, f"is locked under {x['question']}, whose decision is not settled")
@@ -162,13 +179,13 @@ def run(lab, rederive=True):
162
179
  bad("locks", p, "is locked with no refuted-if line")
163
180
  if any(lab.metered(r) for r in x["uses"]) and not any(r.get("stage") == "plan" and r.get("verdict") == "pass" for r in x["reviews"]):
164
181
  bad("locks", p, "uses a metered resource and was locked with no passed review of its plan")
165
- if x["finished"] and x["finished"].get("plan") and x["finished"]["plan"] != lab.plan_hash(x, x["finished"]["how"]):
182
+ if x["finished"] and x["finished"].get("plan") and not lab.plan_is(x, x["finished"]["plan"], x["finished"]["how"]):
166
183
  bad("locks", p, f"plan/ changed after {x['finished']['id']}, the run its results come from; the apparatus of a finished run stays as it ran")
167
184
  ran = [r for r in x["runs"] if not r["missing"]]
168
- if ran and x["lock"].get("plan") and ran[0]["how"] == x["lock"]["hash"] and ran[0].get("plan") != x["lock"]["plan"] and not R.flat(ran[0].get("changed") or ""):
185
+ if ran and x["lock"].get("plan") and ran[0]["how"] == x["lock"]["hash"] and lab.plans_differ(x, ran[0].get("plan"), x["lock"]["plan"], ran[0]["how"]) and not R.flat(ran[0].get("changed") or ""):
169
186
  bad("runs", ran[0]["dir"], "ran a plan/ that differs from the one that was locked and does not say what changed and why")
170
187
  for before, after in zip(ran, ran[1:]):
171
- if before["how"] == after["how"] and before.get("plan") != after.get("plan") and not R.flat(after.get("changed") or ""):
188
+ if before["how"] == after["how"] and lab.plans_differ(x, before.get("plan"), after.get("plan"), after["how"]) and not R.flat(after.get("changed") or ""):
172
189
  bad("runs", after["dir"], f"ran a plan/ that differs from {before['id']}'s and does not say what changed and why")
173
190
  finished = [r for r in x["runs"] if r["state"] == "finished"]
174
191
  if len(finished) > 1:
@@ -11,7 +11,9 @@ same place: what was committed under the old name is held under the new one.
11
11
 
12
12
  - A committed `lock.json` is byte for byte its first committed version.
13
13
  - `log.md`, `reviews.tsv` and `runs.tsv` only grow: no committed line is removed or changed.
14
- - A `results.tsv` that a review has passed keeps every committed row.
14
+ - A `results.tsv` that a review has passed keeps every committed row. Once a results review that passed is committed
15
+ together with the rows it read, those rows stay, whatever the card and the file say later. Rows committed while
16
+ the last passed review was of other rows, such as a draft row added after it, were never reviewed and are not held.
15
17
  - A settled decision keeps its `decided:`, its `about:` and its Decided text as first committed.
16
18
  - A resource, once committed, is never removed. A metered resource's `granted`, `per_run` and `unit` change only together
17
19
  with `from`, which then names another settled decision that lists the resource. Its `other_use` rows only grow.
@@ -179,6 +181,10 @@ def check(lab):
179
181
  bad = lambda where, what: problems.append(f"history: {where}: {what}")
180
182
  if not committed(root):
181
183
  return [], ["this lab is not in git, or has no commit: permanence against history was not checked, and nothing recorded is held yet"]
184
+ notes = []
185
+ if (git(root, "rev-parse", "--is-shallow-repository") or "").strip() == "true":
186
+ notes.append("this repository is a shallow clone: the history check needs every commit, and compared the record with the few that are here. "
187
+ "Fetch the full history (`git fetch --unshallow`; in CI, `fetch-depth: 0`)")
182
188
  versions, now = held(root, "log.md", "decisions", "goals"), present(root)
183
189
  reviewed = {os.path.join(x["dir"], "results.tsv") for x in lab.experiments if x["reviewed"]}
184
190
  for where, commits in sorted(versions.items()):
@@ -203,6 +209,34 @@ def check(lab):
203
209
  bad(mine(path), f"a line committed in {c[:8]}{named(path)} is gone or changed: {lost[:70]!r}")
204
210
  break
205
211
 
212
+ # A results review that passed, once committed with the rows it read, holds those rows: emptying the file with
213
+ # Found and Means leaves the experiment unreviewed now, and the rows are held all the same. The review is bound to
214
+ # what it read by its `of`, the hash `lab review` wrote: of results.tsv and of the seal of the finished run, both
215
+ # as that commit has them. Rows in a commit whose last passed review is of other rows were never reviewed.
216
+ for where, commits in sorted(versions.items()):
217
+ if os.path.basename(commits[-1][1]) != "reviews.tsv":
218
+ continue
219
+ rows, read = where.rsplit("/", 1)[0] + "/results.tsv", set()
220
+ if rows not in now:
221
+ continue # never committed, so nothing is held; or committed and gone, which is said above
222
+ for c, path in reversed(commits + versions.get(rows, [])): # every commit that touched the reviews or the rows
223
+ folder = os.path.dirname(path)
224
+ if c in read:
225
+ continue
226
+ read.add(c)
227
+ passed = [r for r in R.table(git(root, "show", f"{c}:./{folder}/reviews.tsv") or "", R.COLUMNS["reviews.tsv"]) if r.get("stage") == "results" and r.get("verdict") == "pass"]
228
+ was = git(root, "show", f"{c}:./{folder}/results.tsv") if passed else None
229
+ if was is None:
230
+ continue
231
+ listed = [l.split("\t") for l in (git(root, "show", f"{c}:./{folder}/runs.tsv") or "").split("\n")]
232
+ seals = [l[5] for l in listed if len(l) >= 6 and l[1] == "run" and l[2] == "ended" and l[4] == "0"] # the finished run, as that commit lists it
233
+ if passed[-1].get("of") not in {R.text_hash(R.text_hash(was) + str(seal))[:16] for seal in seals}:
234
+ continue # the last review that passed there read other rows than these
235
+ lost = subsequence(was.splitlines(), R.read(os.path.join(root, now[rows][0])).splitlines())
236
+ if lost is not None:
237
+ bad(now[rows][0], f"a row that a review had passed in {c[:8]} is gone or changed: {lost[:70]!r}. Reviewed rows stay; a different result is a new experiment")
238
+ break
239
+
206
240
  problems += decisions(lab, versions, now)
207
241
  problems += resources(lab)
208
- return sorted(set(problems)), []
242
+ return sorted(set(problems)), notes
@@ -17,8 +17,8 @@ KINDS = ["decision", "agent", "result", "stuck", "doing"] # a decision recorded
17
17
  CLOSES = ("agent", "result", "stuck") # a later line of these kinds about the same card ends a `doing` line
18
18
  SLOTS = { # every slot a card has, with its word budget
19
19
  "goal": (("Claim", 90), ("Example", 260), ("Approach", 340), ("Roles", 170), ("Vocabulary", 260)),
20
- "question": (("How we would know", 150), ("Example", 380), ("We expect", 70), ("Wrong if", 70), ("So far", 120)),
21
- "experiment": (("Compares", 80), ("Arms", 260), ("Cases", 100), ("Confirmed if", 150), ("Refuted if", 110), ("Outcomes", 200), ("Limits", 120), ("Found", 130), ("Means", 90)),
20
+ "question": (("How we would know", 150), ("Example", 380), ("We expect", 70), ("Wrong if", 70), ("So far", 180)),
21
+ "experiment": (("Compares", 80), ("Arms", 260), ("Cases", 100), ("Confirmed if", 150), ("Refuted if", 110), ("Outcomes", 200), ("Limits", 120), ("Found", 180), ("Means", 150)),
22
22
  "build": (("How it works", 200), ("Works when", 80)),
23
23
  "reading": (("Looks at", 110), ("Seen", 320), ("Suggests", 150)),
24
24
  "decision": (("Seen", 120), ("Options", 200), ("Recommendation", 80)),
@@ -143,6 +143,16 @@ def symlinks(folder):
143
143
  return sorted(out)
144
144
 
145
145
 
146
+ def compiled(folder):
147
+ """Every `.pyc` file under a folder that is not inside a `__pycache__`. Python imports such a file as it would the
148
+ script of the same name, and no hash of the folder covers it."""
149
+ out = []
150
+ for top, dirs, files in os.walk(folder):
151
+ dirs[:] = [d for d in dirs if d != "__pycache__"]
152
+ out += [os.path.relpath(os.path.join(top, n), folder) for n in files if n.endswith(".pyc")]
153
+ return sorted(out)
154
+
155
+
146
156
  def sha(path):
147
157
  return hashlib.sha256(open(path, "rb").read()).hexdigest()
148
158
 
@@ -151,17 +161,18 @@ def text_hash(text):
151
161
  return hashlib.sha256(text.encode()).hexdigest()
152
162
 
153
163
 
154
- def tree_hash(folder, how=HASH):
164
+ def tree_hash(folder, how=HASH, cache=False):
155
165
  """One hash over a folder: every file's path and bytes, each preceded by its length, so that no two folders give
156
166
  the same hash. The first way (`how` 1: the path, a newline, the bytes) is kept to verify what was made with it.
157
167
  What Python leaves when it imports a script is not part of the folder, in either way: a `__pycache__` folder with
158
- everything under it, and a `*.pyc` file wherever it sits."""
168
+ everything under it, and a `*.pyc` file wherever it sits. With `cache` those are hashed too, which is what
169
+ lab-kit 1.0.0 did: kept only to verify a plan that 1.0.0 locked or ran while such files sat in it."""
159
170
  h, walked = hashlib.sha256(), []
160
171
  for root, dirs, files in os.walk(folder):
161
- dirs[:] = [d for d in dirs if d != "__pycache__"] # as the walk goes: sorting the walk first would read them all
172
+ dirs[:] = [d for d in dirs if cache or d != "__pycache__"] # as the walk goes: sorting the walk first would read them all
162
173
  walked.append((root, files))
163
174
  for root, files in sorted(walked):
164
- for name in sorted(f for f in files if not f.endswith(".pyc")):
175
+ for name in sorted(f for f in files if cache or not f.endswith(".pyc")):
165
176
  p = os.path.join(root, name)
166
177
  path, data = os.path.relpath(p, folder).encode(), open(p, "rb").read()
167
178
  h.update(path + b"\n" + data if how == 1 else len(path).to_bytes(8, "big") + path + len(data).to_bytes(8, "big") + data)
@@ -324,7 +335,8 @@ class Lab:
324
335
  self.results[row["ref"]] = row
325
336
  for q in self.questions:
326
337
  q["state"] = self._question_state(q)
327
- for x in self.items: # needs look at earlier items, so builds and experiments are settled in tree order
338
+ self.reach = self._reach()
339
+ for x in self._in_order(): # a step after everything it needs, wherever that sits in the tree
328
340
  x["state"], x["next"], x["mine"] = {"build": self._build_state, "reading": self._reading_state, "experiment": self._experiment_state}[x["type"]](x)
329
341
  for row in self.results.values(): # a number may be used on a card once its experiment is reviewed, and until it is replaced
330
342
  x = self.nodes[row["experiment"]]
@@ -458,9 +470,20 @@ class Lab:
458
470
  group = block[2:].strip()
459
471
  elif block.startswith("## "):
460
472
  head, _, rest = block[3:].partition("\n")
461
- code = re.search(r"^- code: (.+)$", rest, flags=re.M)
473
+ code, avoid, see = (re.search(rf"^- {key}: (.+)$", rest, flags=re.M) for key in ("code", "avoid", "see"))
462
474
  definition = " ".join(l for l in rest.split("\n") if l.strip() and not l.startswith("- ")).strip()
463
- out.append({"term": head.strip(), "group": group, "definition": definition, "code": code.group(1).strip("` ") if code else ""})
475
+ out.append({"term": head.strip(), "group": group, "definition": definition, "code": code.group(1).strip("` ") if code else "",
476
+ "avoid": [w for w in (w.strip("` ") for w in re.split(r"[,;]", avoid.group(1))) if w] if avoid else [], "see": see.group(1).strip("` ") if see else ""})
477
+ return out
478
+
479
+ def vocabulary(self, goal):
480
+ """The names a goal's Vocabulary lists, each with its glossary entry (None when the glossary lacks it) and whether
481
+ it was written the old way, with a meaning after a colon. The meaning is never read: only the glossary defines."""
482
+ by = {g["term"].lower(): g for g in self.glossary}
483
+ out = []
484
+ for item in items(goal["slots"].get("Vocabulary", "")):
485
+ name, colon, _ = item.partition(":")
486
+ out.append({"name": name.strip(), "entry": by.get(name.strip().lower()), "old": bool(colon)})
464
487
  return out
465
488
 
466
489
  def _lines(self, text):
@@ -715,9 +738,22 @@ class Lab:
715
738
  def before_hash(self, x):
716
739
  return text_hash("\n".join(f"{k}\n{flat(x['slots'].get(k, ''))}" for k in BEFORE))
717
740
 
718
- def plan_hash(self, x, how=HASH):
741
+ def plan_hash(self, x, how=HASH, cache=False):
719
742
  d = os.path.join(self.root, x["dir"], "plan")
720
- return tree_hash(d, how) if os.path.isdir(d) else "-"
743
+ return tree_hash(d, how, cache) if os.path.isdir(d) else "-"
744
+
745
+ def plan_is(self, x, pinned, how=HASH):
746
+ """Whether a hash of plan/ that a lock or a run holds is plan/ as it is now. lab-kit 1.0.0 hashed what Python
747
+ leaves in a folder, and no later kit does: under a lock that 1.0.0 made, a hash that does not match is tried
748
+ once more the way 1.0.0 hashed, before a change is reported."""
749
+ if pinned == self.plan_hash(x, how):
750
+ return True
751
+ return (x.get("lock") or {}).get("kit") == "1.0.0" and pinned == self.plan_hash(x, how, cache=True)
752
+
753
+ def plans_differ(self, x, a, b, how=HASH):
754
+ """Whether two hashes of plan/, held by a lock and a run or by two runs, are of two different plans. Under a
755
+ lock that 1.0.0 made, one may count what Python left and the other not: both are then plan/ as it is now."""
756
+ return a != b and not (self.plan_is(x, a, how) and self.plan_is(x, b, how))
721
757
 
722
758
  def content(self, x, stage, how=HASH):
723
759
  """One hash of what a review of this stage reads: the lines and the plan, or the results and the run they come
@@ -776,6 +812,41 @@ class Lab:
776
812
  return q["answer"]
777
813
  return "open" if self.settled(q) else "under discussion"
778
814
 
815
+ def _reach(self):
816
+ """For each step, every step it needs, directly or through what it needs: {id: {ids}}. A step that is in its
817
+ own set needs itself, which `lab check` reports."""
818
+ needs = {x["id"]: [i for i in x["needs"] if self.nodes.get(i, {}).get("type") in STEPS] for x in self.items}
819
+ out = {}
820
+ for ident in needs:
821
+ seen, todo = set(), list(needs[ident])
822
+ while todo:
823
+ i = todo.pop()
824
+ if i not in seen:
825
+ seen.add(i)
826
+ todo += needs[i]
827
+ out[ident] = seen
828
+ return out
829
+
830
+ def _in_order(self):
831
+ """The steps in the order their states are worked out: each after every step it needs, earlier or later in the
832
+ tree, and otherwise in tree order. Steps that need each other in a circle have no such order: the walk does not
833
+ go round, and `_blocked` holds each of them whatever the others' states."""
834
+ by, out, met = {x["id"]: x for x in self.items}, [], set()
835
+ for first in self.items:
836
+ if first["id"] in met:
837
+ continue
838
+ met.add(first["id"])
839
+ path = [(first, iter(first["needs"]))]
840
+ while path:
841
+ x, needs = path[-1]
842
+ need = next((by[i] for i in needs if i in by and i not in met), None)
843
+ if need is None:
844
+ out.append(path.pop()[0])
845
+ else:
846
+ met.add(need["id"])
847
+ path.append((need, iter(need["needs"])))
848
+ return out
849
+
779
850
  def _blocked(self, x):
780
851
  """Why nothing under this item may move yet, or None."""
781
852
  q, g = self.nodes[x["question"]], self.nodes[x["goal"]]
@@ -787,7 +858,13 @@ class Lab:
787
858
  return f"{q['id']} is {'answered ' + q['state'] if q['state'] in ('yes', 'no') else q['state']}"
788
859
  for need in x.get("needs") or []:
789
860
  n = self.nodes.get(need)
790
- if n and n.get("state") not in ("done", "built", "yes", "no"):
861
+ if n and x["id"] in self.reach.get(need, {need} if need == x["id"] else ()): # a circle of needs: nothing in it moves
862
+ return f"{need} {n['title']}, which needs {x['id']} in turn: no step in a circle of needs can move" if need != x["id"] else f"{need}, which is itself: a step cannot need itself"
863
+ if not n or n["type"] not in STEPS: # held here as `lab check` reports it: a need names a step
864
+ return f"{need}, which {'is not an experiment, a build or a reading' if n else 'does not exist'}: correct the need or remove it"
865
+ if n.get("state") in ("dropped", "replaced"): # it will never be done: waiting on it is waiting for ever
866
+ return f"{need} {n['title']}, which is {n['state']}: remove the need or replace it"
867
+ if n.get("state") not in ("done", "built"):
791
868
  return f"{need} {n['title']}"
792
869
  return None
793
870