lab-kit-cli 1.1.0__tar.gz → 1.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/CHANGELOG.md +52 -0
  2. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/PKG-INFO +1 -1
  3. lab_kit_cli-1.3.0/agents/reviewer.md +13 -0
  4. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/docs/model.md +120 -26
  5. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/method/METHOD.md +8 -6
  6. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/pyproject.toml +1 -1
  7. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/skills/lab-review/SKILL.md +37 -1
  8. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/skills/lab-talk/SKILL.md +16 -4
  9. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/skills/lab-work/SKILL.md +46 -6
  10. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/src/lab_kit/__init__.py +1 -1
  11. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/src/lab_kit/checks.py +11 -6
  12. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/src/lab_kit/history.py +4 -3
  13. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/src/lab_kit/record.py +87 -16
  14. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/src/lab_kit/runs.py +2 -2
  15. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/src/lab_kit/site.py +313 -104
  16. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/src/lab_kit/views.py +8 -2
  17. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/src/lab_kit/write.py +2 -2
  18. lab_kit_cli-1.3.0/tests/test_order.py +85 -0
  19. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/tests/test_parked.py +2 -2
  20. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/tests/test_refusals.py +1 -1
  21. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/tests/test_site.py +89 -1
  22. lab_kit_cli-1.3.0/tests/test_wording.py +100 -0
  23. lab_kit_cli-1.1.0/agents/reviewer.md +0 -11
  24. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/.github/workflows/ci.yml +0 -0
  25. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/.github/workflows/policy.yml +0 -0
  26. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/.github/workflows/release.yml +0 -0
  27. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/.gitignore +0 -0
  28. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/AGENTS.md +0 -0
  29. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/CLAUDE.md +0 -0
  30. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/CONTRIBUTING.md +0 -0
  31. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/LICENSE +0 -0
  32. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/README.md +0 -0
  33. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/skills/lab-set-up/SKILL.md +0 -0
  34. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/src/lab_kit/cli.py +0 -0
  35. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/src/lab_kit/supervise.py +0 -0
  36. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/tests/test_flow.py +0 -0
  37. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/tests/test_held.py +0 -0
  38. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/tests/test_integrity.py +0 -0
  39. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/tests/test_needs.py +0 -0
  40. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/tests/test_vocabulary.py +0 -0
  41. {lab_kit_cli-1.1.0 → lab_kit_cli-1.3.0}/tools/import_run.py +0 -0
@@ -1,5 +1,57 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.3.0
4
+
5
+ A new page style, and a lock that holds what a plan demands rather than its words. Before, every page of a card
6
+ mixed what was observed with the plan, a term was linked only the first time it was used, and a locked card
7
+ could not be made clearer by one word without becoming a new experiment. The method and the skills `lab-work`,
8
+ `lab-review` and `lab-talk`, and the reviewer role, changed: run `lab init` in a lab after upgrading, or
9
+ `lab check` reports that they differ from the installed kit.
10
+
11
+ - **The page style.** A goal, question, experiment, build or reading page reads: the title and the lead (a
12
+ question's `asks:` line), its picture, a tinted **What we know so far**, then the plan under one heading ("The
13
+ plan, as locked", "The question, as asked") with every slot in its box under a fixed label, then the steps,
14
+ the cost and the results, and the record (runs, reviews, earlier plans, files, log) folded at the bottom. A
15
+ done experiment shows What it means and What was found above the plan.
16
+ - **A picture.** A `picture.svg` beside a card is drawn inline at the top of its page, in the site's colours,
17
+ scrolling sideways on a narrow screen. It is parsed and written again from an allowlist of drawing elements and
18
+ attributes, with links only inside the picture and its style sheet kept to it; a file that does not parse as
19
+ one `<svg>` is not drawn, and the page says so.
20
+ - **So far on an experiment.** An experiment card may carry `## So far`, outside the plan: it may change after
21
+ the lock. `lab new experiment` writes it. When it is empty, the Notes of settled decisions about the node
22
+ are shown there; a decision may carry `## Note`.
23
+ - **Links in prose.** A node's exact title of two words or more, with its id in brackets or not, becomes one
24
+ link to its page. Every use of a glossary term, inside bold and italic too, links to its entry with the
25
+ definition on hover. `check` is no longer left out as generic. A slot draws pipe tables and `### ` heading
26
+ lines; a heading the card starts a slot with is dropped, since the label is the heading.
27
+ - **The glossary** takes `- example:` (one concrete case, nothing observed) and `- also:` (other names that
28
+ link to the same entry). Its page shows every group open, each entry with its example and its other names.
29
+ - **The lock holds machine terms.** `lab lock` writes `terms` in `lock.json`: a hash of each bar's role,
30
+ result, comparison and number, by side, and each arm's name. The lock holds while those and `uses:` are as locked;
31
+ the words around them may be made clearer, and a reviewer reads that. A lock made before 1.3.0 reads its
32
+ terms from the version of the card that git holds with the locked hash; where git has none, the whole plan
33
+ is held word for word as before. `lock.json` is never written again, so every run stays under its lock.
34
+ - **Word budgets.** Raised where a slot holds a table or a numbered list, or where cards sat exactly at the
35
+ ceiling: an experiment's description 80, Compares 300, Cases 120, Outcomes 260, Limits 160, So far 300; a
36
+ question's description 150, How we would know 180, So far 220; a reading's Looks at 120, Seen 360; a
37
+ decision's Seen 150, Decided 150, Note 60. `docs/model.md` says why.
38
+
39
+ ## 1.2.0
40
+
41
+ The order of the work can be agreed with the operator and recorded by a decision. Before, `lab now` and the
42
+ site listed next steps in the order of the tree, and an agreed order lived only as prose in a lab's
43
+ `AGENTS.md`, where a new session could miss it. The skills `lab-work` and `lab-talk` changed: run `lab init` in
44
+ a lab after upgrading, or `lab check` reports that they differ from the installed kit.
45
+
46
+ - A decision card may carry `order: [<ids>]`: goals, questions and steps, first to last. Once the decision is
47
+ settled, "Yours next" and "Not yours to move yet" in `lab now`, and Next and the idle line on the site's Now
48
+ page, list steps in that order. A step takes its own place if the order names it, else its question's, else
49
+ its goal's; steps sharing a place, and steps not named, keep the tree's order, the unnamed after the named.
50
+ The last settled decision, by number, that carries an `order:` has the say. An open decision orders nothing.
51
+ - `lab now` says which decision set the order; `lab show <decision>` and the decision's page list the order.
52
+ - `lab check` reports an `order:` that names something other than a goal, a question or a step, or names one
53
+ twice. A settled decision's `order:` is held against the lab's history, like its `about:`.
54
+
3
55
  ## 1.1.0
4
56
 
5
57
  A question can be parked: set aside by a decision, not dropped, and brought back only by another. Before, a
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.1.0
3
+ Version: 1.3.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
@@ -0,0 +1,13 @@
1
+ ---
2
+ name: reviewer
3
+ description: >-
4
+ Reads one experiment's plan or results with fresh context and records a verdict. Use for every
5
+ results review, for a plan review before a run that uses a metered resource, and for a rewording
6
+ of a locked card or a page's style. Give it only the experiment's id and the stage. Never use it
7
+ in the session that did the work.
8
+ ---
9
+
10
+ You review one experiment. You did not plan it, build it or run it, and you were told nothing about
11
+ it except its id and the stage. Follow `.agents/skills/lab-review/SKILL.md`. Write nothing in the lab
12
+ except your verdict on a plan or on results, through `lab review`. A verdict on a rewording or on a
13
+ page's style is given to whoever asked, and written nowhere by you.
@@ -30,8 +30,9 @@ for it.
30
30
  **Every page stands on its own.** The reader was not there. A list is short, and the page a list
31
31
  leads to is complete: it never points at something it does not explain ("the seven-arm run", "the
32
32
  reproduction's setting", "our loop") without saying what that is in the same place. An experiment
33
- names each arm and says what it is. A term is explained in the sentence that first uses it; the
34
- glossary is a second chance, not the explanation. A slot may hold paragraphs and a list when that
33
+ names each arm and says what it is. Another page is named by its exact title, which the site turns into
34
+ a link. A term is the glossary's: every use of it on a page links to its entry, with its definition on
35
+ hover, and no card defines it again. A slot may hold paragraphs and a list when that
35
36
  is clearer than one long sentence. The word budgets are ceilings against sprawl, not targets. If a
36
37
  card needs its last words cut into fragments to fit, the card is saying too much for one slot or
37
38
  the budget is wrong, and full sentences win.
@@ -90,8 +91,8 @@ unclear when it is missed.
90
91
  The outcome is worked out, never written: confirmed when every confirmed-if line holds and no
91
92
  refuted-if line does, refuted when any refuted-if line holds, unclear in between. The page leads with
92
93
  what it means and what was found, then says how many bars were met and names the one that decided the
93
- outcome. There are no confidence numbers, no score sheet and no "what it cannot show" section; a caveat
94
- that matters goes in *Means*.
94
+ outcome. There are no confidence numbers and no score sheet. A caveat the results raise goes in
95
+ *Means*; what the experiment could never show is its Limits, written before the run.
95
96
 
96
97
  A build has no lock, no lines and no result. It ends as built, naming its commits and its tests.
97
98
 
@@ -113,9 +114,12 @@ Each arrow is a command that refuses when the step before it is missing. You see
113
114
  - **Trial run.** A run before the lock, to test that the apparatus works. It is sealed like any run,
114
115
  listed when the plan is locked, and never gives a result. On a metered resource it comes after the
115
116
  review of the plan, like the run itself.
116
- - **Lock.** What the experiment demands is hashed: what it compares, each arm, the cases, the bars,
117
- what each outcome would mean, and its limits. That never changes. To change it, the agent starts a
118
- new experiment that replaces the old one and says why in one sentence (`because:`). The replaced
117
+ - **Lock.** What the experiment demands is held in machine terms: each bar's role, its result, its
118
+ comparison and its number, on its side; the name of each arm; and the resources it uses. That never changes. The
119
+ words of the plan around them (what it compares, what each arm is, the cases, what each outcome
120
+ would mean, its limits, each bar's sentence) may be made clearer after the lock, and must keep
121
+ their meaning: that is the review's to judge, not a command's. To change what it demands, the agent
122
+ starts a new experiment that replaces the old one and says why in one sentence (`because:`). The replaced
119
123
  one stays in the tree with its results, folded under the new one with that sentence, and off the
120
124
  Now page. The lock also records the hash of `plan/` as it was locked, which is the plan the
121
125
  reviewer read: the first run is held against it as every later run is held against the run before.
@@ -129,8 +133,8 @@ Each arrow is a command that refuses when the step before it is missing. You see
129
133
  one sentence what changed and why (`lab run --changed`); `lab run` refuses a changed `plan/`
130
134
  without it, for the first run too, whose "before" is the plan that was locked. `plan/` holds files
131
135
  and no links: what a link points at would not be pinned. The test for "another run or a new
132
- experiment" is whether the comparison, the arms, the cases and the bars can stay word for word as
133
- they are locked.
136
+ experiment" is whether the comparison, the arms, the cases and the bars can stay, in what they
137
+ demand, as they are locked.
134
138
  **Every run is listed.** The store is outside git, so the experiment's folder keeps `runs.tsv`, in
135
139
  git: one row when a run or a trial starts, and one when it ends, with how it ended and its seal.
136
140
  Rows are only added. `lab run` reads that list as well as the store, so a clone without the store
@@ -246,12 +250,22 @@ that parks or brings back a question has the say. An open decision parks nothing
246
250
  never come back, with `dropped: <why>` on its card; park one that may. A goal is closed by `reached: true` or
247
251
  `dropped: <why>`, and a dropped goal drops every question under it.
248
252
 
253
+ **The order of the work.** What the agent takes up first is agreed with you, and a settled decision records
254
+ it: `order:` lists goals, questions and steps, first to last. `lab now` ("Yours next", "Not yours to move yet")
255
+ and the site's Now page list steps in that order. A step takes the place of its own id where the order names it,
256
+ else of its question's, else of its goal's; steps that share a place, and every step the order does not name,
257
+ keep the order of the tree, the unnamed ones after the named. The last settled decision, by number, that carries
258
+ an `order:` has the say; an open decision orders nothing yet. The order only sorts: it moves nothing a step's
259
+ state holds, and a step under a parked or dropped question stays off the list wherever the order puts it. Each
260
+ id is a goal, a question or a step of the lab, named once. A step never carries its own place: the order is
261
+ worked out from the decision, never written on a card.
262
+
249
263
  You may also decide something nobody raised: add, change or drop an experiment or a build, reorder the
250
- work, stop a run. Say it, and the agent records it as a decision and follows it. Two things hold for
264
+ work (a decision with a new `order:`), stop a run. Say it, and the agent records it as a decision and follows it. Two things hold for
251
265
  you as for the agent: a locked plan is changed by a new experiment that replaces it, and an outcome is
252
266
  worked out from the results, not decided.
253
267
 
254
- **A settled decision stays as it was settled.** Its `decided:`, its `about:`, its `parks:`, its `unparks:` and its Decided text never
268
+ **A settled decision stays as it was settled.** Its `decided:`, its `about:`, its `parks:`, its `unparks:`, its `order:` and its Decided text never
255
269
  change once committed; a change of mind is a new decision. `lab check` holds this against the lab's
256
270
  history. So a decision cannot be made, afterwards, to be about something it never discussed.
257
271
 
@@ -325,7 +339,8 @@ Seven rules:
325
339
 
326
340
  1. Say what would refute it before you run.
327
341
  2. A number counts only as a reviewed result of a locked plan.
328
- 3. A miss is recorded like a hit, and nothing locked or recorded is edited.
342
+ 3. A miss is recorded like a hit, and nothing recorded is edited. What a locked plan demands is never
343
+ changed; its words may be made clearer.
329
344
  4. Write for a reader who was not there: every page stands on its own, in plain words and the
330
345
  glossary's terms, and a number is said once.
331
346
  5. Decide everything that is not direction or resources, and never wait idle. For those two, open a
@@ -373,6 +388,8 @@ docs/ the folio library: explanatory pages, and the site
373
388
  .ignore keeps plan/ and runs/ out of default searches
374
389
  ```
375
390
 
391
+ Beside the card of a goal, a question or a step, `picture.svg` is its picture (section 9).
392
+
376
393
  A folder is named after its card's title, so a short title gives a short path.
377
394
 
378
395
  ## 7. The site
@@ -380,6 +397,30 @@ A folder is named after its card's title, so a short title gives a short path.
380
397
  Now, Graph, a page per goal, question, experiment, build, reading and decision, Decisions, Log,
381
398
  Resources, Glossary. Every page has the copy-path control.
382
399
 
400
+ **How a page of a card reads.** Every page of a goal, a question or a step reads in the same order:
401
+
402
+ 1. The title, and the lead: a step's or a goal's description, a question's `asks:` line.
403
+ 2. Its picture, when the card has one, drawn inline (section 9). On a narrow screen it scrolls
404
+ sideways rather than shrink its words.
405
+ 3. **What we know so far**, in a tinted box: everything observed (section 9), and on a finished
406
+ experiment what it means and what was found, above it, with the bar that decided the outcome.
407
+ 4. The plan, under one heading: "The plan, as locked" on an experiment ("not locked yet" before its
408
+ lock), "The question, as asked" on a question. Each slot is in its own box, under the same fixed
409
+ label on every page: on an experiment *What it compares* (with the arms as a table), *Run on*,
410
+ *How the answer is read* (with the bars, each ticked once the results are reviewed) and *What it
411
+ cannot show*; on a question *Why we ask*, *How it works*, *One real case, step by step*, *We
412
+ expect* and *Wrong if*. A heading line a card starts a slot with is not drawn: the label is the
413
+ heading. A goal's Claim, Example and Approach, a build's slots and a reading's slots are boxed the
414
+ same way.
415
+ 5. What is worked out: what is needed from you, the steps, what it costs, the results.
416
+ 6. The record, folded at the bottom: runs, reviews, earlier plans, where to look, the log.
417
+
418
+ In prose, a slot may hold paragraphs, lists, tables written with pipes, and `### ` heading lines. A
419
+ node's exact title of two words or more, with its id in brackets after it or not, is one link to
420
+ its page; and every glossary term is a link to its entry (section 9), inside bold and italic text
421
+ too. A decision's page keeps its own order: what is to discuss or what was decided, then its Note,
422
+ then what was seen, the options and the recommendation.
423
+
383
424
  **A question's page is its briefing.** The question is the unit the operator follows, so its page
384
425
  joins everything under it, in the order they ask: where we are coming from (what the questions it
385
426
  needs established), what we know so far, why we ask, how it works, what is needed from you, the steps
@@ -389,7 +430,8 @@ the same briefing as text, which is what the agent says in chat when asked what
389
430
  and the answer in chat cannot differ. An experiment's page is the evidence behind one step.
390
431
 
391
432
  **Now** is read top to bottom in the order the operator asks: what is happening at this moment and
392
- how fresh the record is; what there is to discuss with you; what is next and who moves it; where each
433
+ how fresh the record is; what there is to discuss with you; what is next and who moves it, in the agreed
434
+ order of the work and naming the decision that set it; where each
393
435
  question stands (what is known so far, and nothing else); the latest events; what is left of each
394
436
  resource. Nothing on it is static text except one line per goal.
395
437
 
@@ -458,17 +500,46 @@ and its sealed runs across as what they were.
458
500
  **A card** is front matter, then its description as a paragraph, then `## Slot` sections. It never
459
501
  holds an id, a state or an outcome. Every file of a lab is UTF-8 text; line ends of either kind
460
502
  read the same, and so hash the same where a review is bound to a file. The front matter sits between
461
- the first two lines that are exactly `---`. A key that holds a list (`needs`, `uses`, `see`, `about`, `holds`, `parks`, `unparks`, `commits`,
503
+ the first two lines that are exactly `---`. A key that holds a list (`needs`, `uses`, `see`, `about`, `holds`, `parks`, `unparks`, `order`, `commits`,
462
504
  `tests`) is written as one, `[a, b]`; every other key holds one value.
463
505
 
464
506
  | Card | Front matter | Slots (word budget) |
465
507
  | --- | --- | --- |
466
508
  | `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) |
467
- | `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) |
468
- | `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) |
469
- | `reading.md` | `title:`, `needs:`, `dropped: <why>` | description (70), Looks at: what, and where it is (110), Seen (320), Suggests (150) |
509
+ | `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) |
510
+ | `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:`, `dropped: <why>` | description (80), So far: optional, everything observed since the plan was written (300), Compares: the comparison, in a sentence or a numbered list of the whole work (300), Arms (260), Cases (120), Confirmed if (150), Refuted if (110), Outcomes (260), Limits (160), Found (180), Means (150) |
511
+ | `reading.md` | `title:`, `needs:`, `dropped: <why>` | description (70), Looks at: what, and where it is (120), Seen (360), Suggests (150) |
470
512
  | `build.md` | `title:`, `needs:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
471
- | `D<n>-<slug>.md` | `title:`, `about:` (the goals, questions, experiments or resources it concerns), `date:`, `holds:`; `parks:` and `unparks:` (questions, each also under `about:`); `decided: {date, with}` is written by `lab decide` | Seen (120), Options: a list, one option an item (200), Recommendation (80), Decided (120) |
513
+ | `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) |
514
+
515
+ **Why these budgets.** A budget is a ceiling. In 1.3.0 the budgets of the slots that hold a table or a
516
+ numbered list (an experiment's Compares, Cases, Outcomes and So far, a question's So far and How we
517
+ would know) were raised, and so were those where several cards of a working lab sat exactly at the
518
+ ceiling (a question's and an experiment's description, a reading's Seen and Looks at, a decision's
519
+ Seen and Decided): a card that sits at its ceiling has usually been cut to fit, and full sentences
520
+ win. The slots that are one bar or one claim (We expect, Wrong if, Claim, the lines) kept theirs.
521
+
522
+ **What we know so far.** A question's So far and an experiment's So far hold everything observed:
523
+ where it stands, what was learned after the plan was written, later decisions and how they change
524
+ the reading, reference runs. The plan holds nothing observed. An experiment's So far is outside its
525
+ plan, so it may change after the lock; a card written before 1.3.0 may leave it out. A decision may
526
+ carry a Note: one or two sentences a reader of the pages it is about must know. While a card's So far
527
+ says nothing, its page shows there the Notes of the settled decisions about it.
528
+
529
+ **A picture.** Any goal, question, experiment, build or reading may have a `picture.svg` beside its
530
+ card. It is drawn inline at the top of its page, after the title and the lead. It shows the whole
531
+ work as numbered steps: what goes in, who does what, the checks, the tools, how it is counted, the
532
+ reference. It shows only what the card states, and no result. It uses the site's colours (`var(--ink)`,
533
+ `var(--accent)`, `var(--surface)`, `var(--rule)`), so it reads in light and dark. It is parsed as XML
534
+ and written again from an allowlist, so nothing outside its one `<svg>` element reaches the page:
535
+ the drawing elements (`svg`, `g`, `defs`, `marker`, `rect`, `circle`, `ellipse`, `line`, `path`,
536
+ `polygon`, `polyline`, `text`, `tspan`, `title`, `desc`, `style`), each with its geometry and
537
+ presentation attributes; no event handler, a link only to `#` inside the picture, no `url(` but
538
+ `url(#id)`, and no value that reads `javascript:` once its entities and spaces are taken out. An
539
+ element that is not allowed is left out with everything inside it. A `<style>` is kept only when it
540
+ has no at-rule, no `url(` to anything outside, no markup and no `expression`, and every selector is a
541
+ class selector; each rule is then kept to the picture (`figure.pic .name`). A file that does not
542
+ parse, that is not one `<svg>`, or that declares a document type is not drawn, and the page says so.
472
543
 
473
544
  Any card may carry `see:`, a list of pages that explain it: pages of the lab's own library, and pages
474
545
  of another library its charter names, written as folio writes them (`pier-folio:/content/readings/...`),
@@ -492,14 +563,19 @@ The part that reads every call and refuses the ones the contract forbids.
492
563
  - code: kna.gate:Guard
493
564
  - avoid: gate, filter, policy
494
565
  - see: entries/kna-gate
566
+ - example: a call that writes to a file the contract does not name is refused
567
+ - also: guards
495
568
  ```
496
569
 
497
- `code:` is where the term is in the code. `avoid:` lists, separated by commas, the words not to use
570
+ `example:` is one concrete case of the term, with nothing observed in it: a result is never an
571
+ example. `also:` lists, separated by commas, other names the cards use for the same thing; each links
572
+ to this entry as the term does. `code:` is where the term is in the code. `avoid:` lists, separated by commas, the words not to use
498
573
  for this thing. `see:` names a page that explains the concept: a page of the lab's own library
499
574
  (`entries/kna-gate`) or of a library the charter names (`pier-folio:/content/concepts/lora/`), the
500
- same targets a card's `see:` takes. `lab define <term>` prints all of it. The glossary page shows the
501
- definition, the code, the page as a link and the avoid words in small type; the hover on a term in
502
- prose is the definition alone.
575
+ same targets a card's `see:` takes. `lab define <term>` prints all of it. The glossary page shows every group open, and each
576
+ entry with its definition, its example, the code, the page as a link, its other names and the avoid
577
+ words in small type. In prose, every time a term or one of its other names is written, on every
578
+ page, it is a link to its entry, and the hover on it is the definition alone.
503
579
 
504
580
  A word is defined once, in the glossary. A card that needs a word adds it there first, then uses it;
505
581
  no card defines a word of its own. A concept that is not this lab's own (a method, a paper's idea) gets
@@ -519,8 +595,9 @@ never seen it knows what was run.
519
595
  - contract only: the gate's planning request, then a guard that reads every call and refuses nothing
520
596
  ```
521
597
 
522
- The lock holds Compares, Arms, Cases, the lines, Outcomes and Limits, and refuses an experiment with
523
- no arm or no cases.
598
+ `lab lock` refuses an experiment with no arm or no cases. What it then holds is in section 3: the
599
+ role, result, comparison and number of each line, the name of each arm and `uses:`; the words may be made
600
+ clearer later.
524
601
 
525
602
  **What a bar is for.** A confirmed-if line may open with its role: `answer:` for the one comparison
526
603
  the experiment exists to make, `readable:` for a bar without which that comparison says nothing (the
@@ -530,7 +607,7 @@ so the reader sees which line is the answer. The outcome is worked out as before
530
607
 
531
608
  **Outcomes** is a list: each outcome the bars allow, what it would mean, and what would be done
532
609
  next. **Limits** is a list of the two or three things the experiment cannot show that a reader
533
- would otherwise assume. Both are written before the run and held by the lock. `cost:` in the front
610
+ would otherwise assume. Both are written before the run, and what they mean does not change after the lock. `cost:` in the front
534
611
  matter is one or two sentences on how large the run is and why it needs the resource it uses; the
535
612
  amounts used and still allowed are worked out beside it.
536
613
 
@@ -564,10 +641,27 @@ sentences), `retired` (why, once it is no longer used), and for a metered resour
564
641
  outside any run, such as a machine woken when nothing ran, is a line the agent adds under
565
642
  `other_use`: `{date, amount, what}`. What is used is the runs' use plus these lines.
566
643
 
644
+ **What a lock holds.** `lab lock` writes `lock.json` once, and nothing writes it again. Besides the
645
+ hash of the whole plan as it was locked (`card`: Compares, Arms, Cases, the lines, Outcomes and
646
+ Limits), a lock made by 1.3.0 or later holds `terms`: one hash of the plan's machine terms, which are
647
+ the result, comparison and number of every confirmed-if and refuted-if line, by side, and the name
648
+ of every arm, each list sorted, so that putting the lines or the arms in another order changes
649
+ nothing. A line's role (`answer:`, `readable:`, `counts:`, or none) is part of it: which bar is
650
+ the answer is part of what the plan demands. A line with no test counts as one. The lock holds when `uses:` is what was locked and the
651
+ terms of the card now hash to `terms`. A lock made before 1.3.0 has only `card`. Its terms are read
652
+ from git: of the versions of the card that git holds, the one whose whole plan hashes to `card` is
653
+ the card as it was locked, and its terms are the locked terms. No commit has to be trusted for it:
654
+ the hash says which version it is. When git holds no such version (no repository, a shallow clone, a
655
+ card changed before it was ever committed as it was locked), the whole plan is held as it was locked,
656
+ word for word, as before 1.3.0. Every run records the `card` of the lock it ran under, and
657
+ `lab check` holds it against the lock's `card`; neither changes when the words do, so a run stays a
658
+ run under its lock after the words are made clearer.
659
+
567
660
  **A run's record**, `run.json`, holds the hash of `plan/` as it ran (`plan`) and what changed since
568
661
  the run before, or for the first run since the lock (`changed`). Its seal is one hash over that
569
662
  record, which lists the hash of every other file in the run's folder. `lock.json` holds the version of
570
- the kit that made it (`kit`), when the experiment was locked, the hash of the demand (`card`), the
663
+ the kit that made it (`kit`), when the experiment was locked, the hash of the plan as it was locked
664
+ (`card`), from 1.3.0 the hash of its machine terms (`terms`), the
571
665
  hash of `plan/` as it was locked (`plan`), the resources it uses (`uses`) and the trial runs that
572
666
  existed. A lock that names its kit and lacks one of these is not a lock the kit wrote, and
573
667
  `lab check` says so.
@@ -11,17 +11,19 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
11
11
  do the work. Until then it is not written on a card, in a message or in the log. A count made
12
12
  in a reading is said as what it is, on the reading's own card, and confirms nothing. *Held by
13
13
  `lab check`; the review itself is judged.*
14
- 3. **A miss is recorded like a hit, and nothing locked or recorded is edited.** A failed run is kept. A
15
- refuted line is an outcome like any other. A changed plan, a failed review or a partial score is
16
- a new experiment that replaces the old one and says why in a sentence. What an experiment demands is
17
- locked once; it is run until one run finishes, and a run after a fix says what changed. Once a
14
+ 3. **A miss is recorded like a hit, and nothing recorded is edited. What a locked plan demands is never
15
+ changed; its words may be made clearer.** A failed run is kept. A refuted line is an outcome like
16
+ any other. A changed plan, a failed review or a partial score is a new experiment that replaces the
17
+ old one and says why in a sentence. What an experiment demands (each bar's role, result, comparison and
18
+ number, each arm's name, the resources it uses) is locked once; a clearer word keeps its meaning,
19
+ 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
18
20
  run has finished, nothing more runs under it. Every run is listed in the experiment's `runs.tsv`,
19
21
  which you commit when the run starts and again when it ends: git holds only what it has been
20
22
  given, and a run is never removed. *Held by `lab run`, `lab new` and
21
23
  `lab check`.*
22
24
  4. **Write for a reader who was not there.** Every page stands on its own: it says what each thing it
23
- mentions is, names each arm of an experiment and what it is, and explains a term where it first
24
- uses it. A number is said once: it lives in its result row, and a card names it. A state is
25
+ mentions is, names each arm of an experiment and what it is, names another page by its exact
26
+ 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
25
27
  worked out, never written. *The numbers and the budgets are held by `lab check`; whether a page
26
28
  can be read cold is judged, and the reviewer reads for it.*
27
29
  5. **Decide everything that is not direction or resources, and never wait idle.** Direction is the
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  dynamic = ["readme"]
7
7
  name = "lab-kit-cli"
8
- version = "1.1.0"
8
+ version = "1.3.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" }]
@@ -50,8 +50,44 @@ When you read a plan, also read the card as someone who was not there. If an arm
50
50
  explained, or the card points at something it does not say, say so in the note: it does not fail the
51
51
  review, and the author fixes it before the lock.
52
52
 
53
+ ## A rewording of a locked card
54
+
55
+ After the lock, the words of a plan may be made clearer; what it demands may not. `lab check` holds
56
+ the machine terms (each bar's role, result, comparison and number, each arm's name, `uses:`). You read the
57
+ rest. Compare the card as it was locked (`git log -p -- <card>`, from the commit that holds its lock)
58
+ with the card now:
59
+
60
+ 1. Slot by slot, the meaning is unchanged: the same comparison, the same arms doing the same things,
61
+ the same cases, the same outcomes and limits. A clearer sentence passes; a narrower or wider one
62
+ fails.
63
+ 2. Every number in a line's sentence matches its test, and its test is the one locked.
64
+ 3. Nothing observed is in the plan or in the picture: no status, no result, no "since the lock".
65
+ What was observed goes in So far.
66
+ 4. The picture shows only what the card states.
67
+ 5. Every dotted word on the page (a glossary link) means the lab's meaning where it is used. A word
68
+ used in its everyday sense that links to a lab term is a fault.
69
+
70
+ Give the verdict, pass or fail, with one sentence per fault, to whoever asked. You write nothing in
71
+ the lab: the author logs the rewording with your verdict
72
+ (`lab log <experiment> agent "Reworded the locked card: <what>" "Reviewed by <you>: pass"`).
73
+
74
+ ## A page's style
75
+
76
+ Open the page on the site and read it top to bottom as the operator would:
77
+
78
+ - the picture comes first, numbered, showing the whole work and only what the card states;
79
+ - What we know so far holds everything observed, and the plan below it holds nothing observed;
80
+ - each slot sits in its box under its fixed label, with no heading of the card's own above it;
81
+ - every other page is named by its exact title, so it is a link;
82
+ - every glossary word is a link and means the lab's meaning there, and no word is defined on the
83
+ page that is not in the glossary;
84
+ - sentences are plain, one idea each; items compared are in a table; options are named in words,
85
+ never letters.
86
+
87
+ Report each fault with where it is. Fix nothing yourself.
88
+
53
89
  ## Rules
54
90
 
55
- - Do not fix anything. Do not edit a card, a plan or a row.
91
+ - Do not fix anything. Do not edit a card, a picture, a plan or a row.
56
92
  - Do not read the author's log lines or messages before you have read the files.
57
93
  - If you cannot re-run a command or open the run's output, fail it and say why.
@@ -25,7 +25,12 @@ from the record, shortest first. A decision is a discussion, not a request for a
25
25
  | what does a word mean | `lab define <term>` |
26
26
 
27
27
  - The answer first, in one or two sentences, then what it rests on: the result, by its label and value.
28
- - Plain words. No id without its title. A glossary term is used as the glossary defines it.
28
+ - Plain words, one idea a sentence. No id without its title. A glossary term is used as the glossary defines it.
29
+ - Write in chat as the pages are written. Name a goal, a question, a step or a decision by its exact
30
+ title, as a link to its page on the lab's site when the site has an address
31
+ (`[The rule pilot](<site>/lab/G4.Q1.2/)`), with its id after it. The first time a glossary term
32
+ comes up, give its definition from `lab define` in a few words. Never use a word in its everyday
33
+ sense when it is also a lab term. Compare items in a table.
29
34
  - For "where are we": each goal in a line, each open question with what is known so far, what is
30
35
  running, what is next, what there is to discuss. No more than a screen.
31
36
  - `lab brief` is the question's page as text. Give it as it is, cut to what they asked. If what you
@@ -39,7 +44,7 @@ from the record, shortest first. A decision is a discussion, not a request for a
39
44
 
40
45
  1. Say what was seen and why it matters now, with the numbers, shown here in the conversation.
41
46
  2. Lay out the options, each with what it costs and what it changes, and say which you recommend
42
- and why.
47
+ and why. Name each option in words ("read `sll` apart"), never by a letter.
43
48
  3. Discuss. Answer their questions from the record. Take their ideas seriously: an option they add
44
49
  is an option. If the discussion changes the options, rewrite the card's Options before deciding.
45
50
  4. When it is settled, write what was decided and why, in the lab's words, in two to four sentences:
@@ -63,6 +68,12 @@ clear. To park, list the question under `parks:` and `about:` on the decision be
63
68
  the Decided text why and what would bring it back. To bring one back, a new decision lists it under
64
69
  `unparks:`. To close a goal, put `reached: true` or `dropped: <why>` on its card, out of a decision.
65
70
 
71
+ When they agree an order of work ("this first, then these side by side"), record it on the decision as
72
+ `order: [<ids>]`, first to last: goals, questions or steps, each once. A question or a goal stands for every
73
+ step under it; a step named on its own takes its own place. Steps not named follow, in the tree's order. Say
74
+ the order in the Decided text too. To change it, a new decision with a new `order:`; never edit a settled one,
75
+ and never write the order anywhere else (not in `AGENTS.md`, not on a step).
76
+
66
77
  ## Rules
67
78
 
68
79
  - Never copy the operator's messages into the lab. The record says what was decided and why.
@@ -71,5 +82,6 @@ the Decided text why and what would bring it back. To bring one back, a new deci
71
82
  - Never bring them something that is yours to decide, and never ask them to check your work, to
72
83
  confirm a plan already settled, or to run a command.
73
84
  - A decision holds only what its card lists under `holds:`. Keep working on everything else.
74
- - Two things hold for them as for you: a locked plan is changed by a new experiment that replaces
75
- it, and an outcome is worked out from the results.
85
+ - Two things hold for them as for you: what a locked plan demands is changed only by a new
86
+ experiment that replaces it (its words may be made clearer), and an outcome is worked out from
87
+ the results.
@@ -17,6 +17,8 @@ discussion, recorded as a decision. What a decision settled needs no further yes
17
17
 
18
18
  `lab now`. If something is under **To discuss with the operator** and they are here, bring it to them
19
19
  first (the lab-talk skill). Otherwise take the first line under **Yours next**: it says what to do.
20
+ When a decision has set the order of the work, **Yours next** is already in that order and says which
21
+ decision set it; follow it, and bring a change of order to the operator rather than skipping ahead.
20
22
  `lab show <id>` before you touch anything.
21
23
 
22
24
  Then say what you are on, before the first edit: `lab log <id> doing "<what you are starting on>"
@@ -32,11 +34,12 @@ The operator reads every card on the site, usually days later and without you. W
32
34
  matter is the description: what it is and why it is there.
33
35
  - A page stands on its own. Never point at something the page does not explain: not "the seven-arm
34
36
  run", but what that run was; not "our loop", but "KNA's own agent loop, the one the gate plugs
35
- into". Explain a term in the sentence that first uses it, even when the glossary has it.
37
+ into".
36
38
  - A paper, a method or a tool the reader may not know gets a few words saying what it is, and a
37
39
  link where it is first named: `[PISmith](pier-folio:/content/readings/...)` for a page of a
38
40
  library the charter names, or a web address. Put the same page under `see:`.
39
- - A word is defined once, in `GLOSSARY.md`, and nowhere else. Use the goal's vocabulary: the goal's
41
+ - A word is defined once, in `GLOSSARY.md`, and nowhere else: the page links every use of a term to
42
+ its entry, with the definition on hover, so a card never explains a term itself. Use the goal's vocabulary: the goal's
40
43
  card lists, by name only (`- field`), the few words the lab uses for its own things; use those words,
41
44
  the same way, on every card, and read a term's `avoid:` words as the ones not to use for it. When a
42
45
  card needs a new word, add it to the glossary first, then list it on the goal if every card uses it.
@@ -52,6 +55,43 @@ The operator reads every card on the site, usually days later and without you. W
52
55
  sentences win.
53
56
  - Read the card as someone who was not there. If a question comes to mind, the card answers it.
54
57
 
58
+ ## The page style
59
+
60
+ Every page reads in the same order: the title and the lead, a picture, **What we know so far**, then
61
+ the plan in fixed boxes, then the steps and the record. Write the card for that page.
62
+
63
+ - **A picture first.** Draw `picture.svg` beside the card of a question or an experiment before you
64
+ write its slots. It shows the whole work as numbered steps: what goes in, who does what, the
65
+ checks, the tools, how it is counted, and the reference. It shows only what the card states, and
66
+ no result: a number observed never goes in a picture. Use the site's colours (`var(--ink)`,
67
+ `var(--ink-2)`, `var(--accent)`, `var(--surface)`, `var(--rule)`, `var(--sans)`) and never a fixed
68
+ colour, so it reads in light and dark. Keep its text at least 12 pixels at its own width.
69
+ - **What we know so far holds everything observed.** The card's `## So far`: where it stands, what
70
+ was learned after the plan was written, later decisions and what they change, reference runs. On
71
+ an experiment it sits outside the plan, so you keep it current after the lock. When a decision
72
+ changes how a node is read, give the decision a `## Note` of one or two sentences: a node whose So
73
+ far is empty shows it there.
74
+ - **The plan holds nothing observed, and what it demands is not changed after the lock.** No status,
75
+ no result, no "since then" in Compares, Arms, Cases, the lines, Outcomes or Limits. After the lock
76
+ you may make their words clearer, slot by slot, keeping the meaning; never a bar's role, result,
77
+ comparison or number, an arm's name or `uses:` (`lab check` holds those). Have a reviewer read
78
+ every such rewording (the lab-review skill).
79
+ - **Fixed boxed sections.** Each slot is drawn in its box under a fixed label: on an experiment *What
80
+ it compares*, *Run on*, *How the answer is read*, *What it cannot show*; on a question *Why we
81
+ ask*, *How it works*, *One real case, step by step*, *We expect*, *Wrong if*. Do not start a slot
82
+ with your own `### heading`: the label is the heading. Inside a slot, `### ` lines may split it.
83
+ - **Name a page by its exact title.** Write "The rule pilot (G4.Q1.2)" or "The rule pilot", never
84
+ "the pilot" or "that experiment": the exact title, with its id in brackets or not, becomes a link.
85
+ - **Glossary words are linked everywhere.** Every use of a term, and of each name under its `- also:`,
86
+ links to its entry. So add a term, with a `- example:` that shows one concrete case and nothing
87
+ observed, before you use it. Avoid a word whose everyday sense would link to the wrong lab meaning:
88
+ if "check" is a term, do not write "check" for "look at".
89
+ - **Plain sentences, one idea each.** Short sentences. A sentence that carries two ideas becomes two.
90
+ - **Tables where items are compared.** Write a pipe table (`| a | b |`, a dashes row under the header)
91
+ when several items are compared on the same points: the arms, the cases, the outcomes.
92
+ - **Options are named in words, never letters.** "Read `sll` apart", not "(a)". A decision's options
93
+ are a list, each item opening with its name in bold.
94
+
55
95
  ## When to open a decision
56
96
 
57
97
  Open one when a question is answered or an experiment refutes what was expected, when a result
@@ -132,8 +172,8 @@ until that decision is settled; after that it needs no further yes.
132
172
  the page then shows them with the number.
133
173
  8. Send a reviewer for the results.
134
174
  9. Once the review has passed, write **Found** and **Means** on the card. Name each result instead
135
- of typing its number: `{attack-success}`. It is shown the way its row says it reads. Rewrite the
136
- question's **So far** the same way, with full names: `{G1.Q1.2:attack-success}`.
175
+ of typing its number: `{attack-success}`. It is shown the way its row says it reads. Bring the
176
+ 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}`.
137
177
  10. `lab log <experiment> result "<what was found, in a sentence, without numbers>" "<so what>"`.
138
178
 
139
179
  The outcome is worked out from the lines: you never write it.
@@ -147,14 +187,14 @@ An experiment is run until one run finishes. Read why the run failed, then:
147
187
  `lab run <experiment> --changed "<what changed since the last run, and why>" -- <command>`. Write
148
188
  that sentence for the operator: it is shown beside the run on the experiment's page.
149
189
  - **What it demands has to change** (the comparison, an arm, the cases, a bar): that is a new
150
- experiment. The test is whether those can stay word for word as they are locked.
190
+ experiment. The test is whether those can stay, in what they demand, as they are locked.
151
191
 
152
192
  Never read a failed run's partial numbers to decide what to fix. Once one run has finished, the
153
193
  experiment takes no more, and `plan/` stays as that run ran it.
154
194
 
155
195
  ## When the experiment itself has to change
156
196
 
157
- What an experiment demands never changes once locked. `lab new experiment <question> "<title>"
197
+ What an experiment demands never changes once locked; its words may only be made clearer. `lab new experiment <question> "<title>"
158
198
  --replaces <old> --because "<why>"` copies the old card and plan for you to change; the old one
159
199
  stays, folded under the new with that sentence. Write the reason for the operator: what was wrong
160
200
  with what the old one asked, in plain words. The same holds when a results review fails, and when
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.1.0"
2
+ __version__ = "1.3.0"