lab-kit-cli 1.0.2__tar.gz → 1.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/.github/workflows/policy.yml +6 -2
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/AGENTS.md +4 -2
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/CHANGELOG.md +42 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/PKG-INFO +1 -1
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/docs/model.md +54 -10
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/pyproject.toml +1 -1
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/skills/lab-set-up/SKILL.md +4 -1
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/skills/lab-talk/SKILL.md +5 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/skills/lab-work/SKILL.md +13 -4
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/src/lab_kit/__init__.py +1 -1
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/src/lab_kit/checks.py +36 -14
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/src/lab_kit/history.py +4 -4
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/src/lab_kit/record.py +43 -6
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/src/lab_kit/site.py +55 -6
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/src/lab_kit/views.py +22 -2
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/src/lab_kit/write.py +2 -0
- lab_kit_cli-1.1.0/tests/test_parked.py +80 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/tests/test_site.py +6 -4
- lab_kit_cli-1.1.0/tests/test_vocabulary.py +116 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/.github/workflows/ci.yml +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/.github/workflows/release.yml +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/.gitignore +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/CLAUDE.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/CONTRIBUTING.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/LICENSE +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/README.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/agents/reviewer.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/method/METHOD.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/skills/lab-review/SKILL.md +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/src/lab_kit/cli.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/src/lab_kit/runs.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/src/lab_kit/supervise.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/tests/test_flow.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/tests/test_held.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/tests/test_integrity.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/tests/test_needs.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/tests/test_refusals.py +0 -0
- {lab_kit_cli-1.0.2 → lab_kit_cli-1.1.0}/tools/import_run.py +0 -0
|
@@ -1,10 +1,14 @@
|
|
|
1
1
|
name: policy
|
|
2
2
|
|
|
3
|
+
# Runs on pull requests only: a push straight to main is checked by the pre-push hook on the
|
|
4
|
+
# machine that pushes (setup-machine), so GitHub spends no minutes on it (decision 0033).
|
|
3
5
|
on:
|
|
4
6
|
pull_request:
|
|
5
7
|
types: [opened, edited, synchronize, reopened]
|
|
6
|
-
|
|
7
|
-
|
|
8
|
+
|
|
9
|
+
concurrency:
|
|
10
|
+
group: policy-${{ github.event.pull_request.number }}
|
|
11
|
+
cancel-in-progress: true
|
|
8
12
|
|
|
9
13
|
permissions:
|
|
10
14
|
contents: read
|
|
@@ -37,9 +37,11 @@ Every change goes through a pull request; `main` accepts nothing else.
|
|
|
37
37
|
3. When the work is done and the gate passes, squash-merge it with a clear title and description,
|
|
38
38
|
then delete the branch and the worktree.
|
|
39
39
|
|
|
40
|
-
**Gate:** `python -m pytest -q
|
|
40
|
+
**Gate:** `python -m pytest -q`.
|
|
41
|
+
Run it before every push; CI also runs it on every pull request.
|
|
41
42
|
|
|
42
43
|
**Authorship.** Every commit is authored with the repository owner's git identity. No co-author
|
|
43
44
|
line, tool or agent name, "generated with" footer or session link appears in a commit message, a
|
|
44
|
-
branch name or a pull request.
|
|
45
|
+
branch name or a pull request. The pre-push hook enforces it on every push, and a required `policy`
|
|
46
|
+
check on every pull request.
|
|
45
47
|
<!-- ops:lanes:end -->
|
|
@@ -1,5 +1,47 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.1.0
|
|
4
|
+
|
|
5
|
+
A question can be parked: set aside by a decision, not dropped, and brought back only by another. Before, a
|
|
6
|
+
question the lab chose not to pursue now stayed open, with nothing to say it was set aside on purpose, or was
|
|
7
|
+
dropped for good. The skills `lab-work` and `lab-talk` changed: run `lab init` in a lab after upgrading, or
|
|
8
|
+
`lab check` reports that they differ from the installed kit.
|
|
9
|
+
|
|
10
|
+
- A decision card may carry `parks: [<question>]` and `unparks: [<question>]`. Each question named is also
|
|
11
|
+
under `about:`. Once the decision is settled, the question is parked; a later settled decision that lists
|
|
12
|
+
it under `unparks:` brings it back. The last settled decision, by number, that names it has the say.
|
|
13
|
+
- A parked question leaves Now, the rail and the graph. `lab new` refuses a step under it, and `lab lock` and
|
|
14
|
+
`lab run` refuse its experiments, each naming the decision that parked it.
|
|
15
|
+
- `lab now` has a Set aside section: each parked question in one line with the decision that parked it, and a
|
|
16
|
+
count of the dropped questions and the closed goals. The site's front page has the same section, with the
|
|
17
|
+
first sentence of what was decided; a goal's page folds its parked questions; a parked question's page says
|
|
18
|
+
at the top which decision parked it and why; a decision shows what it parks or brings back.
|
|
19
|
+
- Steps under a parked or dropped question, or a goal that is not active, no longer show under "Not yours to
|
|
20
|
+
move yet" or as what the idle front page names next.
|
|
21
|
+
- `lab check` reports a `parks:` or `unparks:` that names something other than a question, a question not
|
|
22
|
+
under `about:`, and a question both parked and brought back by one decision. What a settled decision parks
|
|
23
|
+
or brings back is held against the lab's history, like its `about:`.
|
|
24
|
+
|
|
25
|
+
## 1.0.3
|
|
26
|
+
|
|
27
|
+
A word is now defined in one place, `GLOSSARY.md`. Before, the glossary and the goal's Vocabulary
|
|
28
|
+
both said what a word means, and the two could drift. The skills `lab-work` and `lab-set-up` changed:
|
|
29
|
+
run `lab init` in a lab after upgrading, or `lab check` reports that they differ from the installed
|
|
30
|
+
kit. Change the goal's Vocabulary to names, too: see below.
|
|
31
|
+
|
|
32
|
+
- A glossary entry may carry two more lines beside `- code:`. `- avoid: gate, filter, policy` lists
|
|
33
|
+
the words not to use for the thing; `- see: entries/kna-gate` (or a page of a library the charter
|
|
34
|
+
names, such as `pier-folio:/content/concepts/lora/`) names a page that explains the concept.
|
|
35
|
+
`lab define` prints both, and the glossary page shows the avoid words in small type and the page as a
|
|
36
|
+
link. The hover on a term stays the definition alone. `lab check` checks a `see` as it checks a
|
|
37
|
+
card's `see:`. It does not flag avoid words used in cards: a word to avoid for one thing is often right
|
|
38
|
+
for another.
|
|
39
|
+
- The goal's Vocabulary is a list of names only (`- field`). The goal's page and `lab show` draw
|
|
40
|
+
each with its glossary definition. `lab check` reports a name that is not a glossary term. A goal
|
|
41
|
+
written the old way (`- word: meaning`) still shows the glossary's definition, never the card's, and
|
|
42
|
+
`lab check` reports it: list the name only, and add the term to the glossary if it is missing there.
|
|
43
|
+
An existing lab must change its goal's Vocabulary to names.
|
|
44
|
+
|
|
3
45
|
## 1.0.2
|
|
4
46
|
|
|
5
47
|
One defect found while rehearsing a real lab, four follow-ups from 1.0.1, and three larger word
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: lab-kit-cli
|
|
3
|
-
Version: 1.0
|
|
3
|
+
Version: 1.1.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
|
|
@@ -10,7 +10,7 @@ A lab is a tree, and the decisions that shaped it.
|
|
|
10
10
|
| Thing | What it says | States |
|
|
11
11
|
| --- | --- | --- |
|
|
12
12
|
| **Goal** | A short name, what the lab wants to be able to say, and the claim: what we would report if the questions come out as expected, and against whose work. | active, reached, dropped |
|
|
13
|
-
| **Question** | A short name, and a yes-or-no question under a goal, written in full: why we ask it, how we would know, what we expect, what would prove us wrong, what we know so far. | under discussion, open, yes, no, dropped |
|
|
13
|
+
| **Question** | A short name, and a yes-or-no question under a goal, written in full: why we ask it, how we would know, what we expect, what would prove us wrong, what we know so far. | under discussion, open, parked, yes, no, dropped |
|
|
14
14
|
| **Experiment** | One thing tried to answer a question. What it is for. Before the run: what is compared, each arm by name with what it is, the cases it runs on, what would confirm, what would refute. After: what was found, what it means. | planned, running, waiting, done (confirmed, refuted or unclear), review failed, replaced, dropped |
|
|
15
15
|
| **Build** | One thing an experiment needs that has to be made first: what it is for, how it works in plain words, and how we know it works. | planned, in progress, built, dropped |
|
|
16
16
|
| **Reading** | One look at what already exists: sealed runs, traces, the benchmark's own definitions. What it looks at; then what was seen and what that suggests. It sets no bar in advance, so it can suggest and never confirm. | planned, in progress, done, dropped |
|
|
@@ -237,12 +237,21 @@ the resources it sets need no further yes. Every goal and question names the dec
|
|
|
237
237
|
nothing under a question is locked or run while that decision is still open. Nothing else asks for your
|
|
238
238
|
approval: an experiment added later under a settled question is the agent's to plan and run.
|
|
239
239
|
|
|
240
|
+
**Parking a question.** A question can be set aside without being dropped: not now, perhaps later. A settled
|
|
241
|
+
decision parks it by listing it under `parks:`, and lists it under `about:` too. The decision's Decided text says
|
|
242
|
+
why, and what would bring it back. A parked question leaves Now, the rail and the graph, as a dropped one does.
|
|
243
|
+
Nothing under it moves: `lab new` refuses a step under it, and `lab lock` and `lab run` refuse its experiments. It
|
|
244
|
+
comes back only by a later settled decision that lists it under `unparks:`. The last settled decision, by number,
|
|
245
|
+
that parks or brings back a question has the say. An open decision parks nothing yet. Drop a question that will
|
|
246
|
+
never come back, with `dropped: <why>` on its card; park one that may. A goal is closed by `reached: true` or
|
|
247
|
+
`dropped: <why>`, and a dropped goal drops every question under it.
|
|
248
|
+
|
|
240
249
|
You may also decide something nobody raised: add, change or drop an experiment or a build, reorder the
|
|
241
250
|
work, stop a run. Say it, and the agent records it as a decision and follows it. Two things hold for
|
|
242
251
|
you as for the agent: a locked plan is changed by a new experiment that replaces it, and an outcome is
|
|
243
252
|
worked out from the results, not decided.
|
|
244
253
|
|
|
245
|
-
**A settled decision stays as it was settled.** Its `decided:`, its `about:` and its Decided text never
|
|
254
|
+
**A settled decision stays as it was settled.** Its `decided:`, its `about:`, its `parks:`, its `unparks:` and its Decided text never
|
|
246
255
|
change once committed; a change of mind is a new decision. `lab check` holds this against the lab's
|
|
247
256
|
history. So a decision cannot be made, afterwards, to be about something it never discussed.
|
|
248
257
|
|
|
@@ -325,7 +334,7 @@ Seven rules:
|
|
|
325
334
|
Never record a decision that was not discussed with them.
|
|
326
335
|
7. Say what you are on. When you start on a card, log what you are doing and why now.
|
|
327
336
|
|
|
328
|
-
`lab check` holds what can be held mechanically: ids and links, a title and a description on every
|
|
337
|
+
`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
|
|
329
338
|
card, short cards that write only their own front matter, a test on every line, a reason on every
|
|
330
339
|
replacement, unchanged locks, sealed runs, results that still re-derive and were reviewed, use inside
|
|
331
340
|
the resources' amounts, a decision behind every goal, question and metered amount, an experiment
|
|
@@ -387,10 +396,15 @@ resource. Nothing on it is static text except one line per goal.
|
|
|
387
396
|
**An example on every question.** A question's page carries one case, step by step, as a numbered
|
|
388
397
|
list that says who does what: the user, the agent, the tools, the gate, the scorer. A real episode
|
|
389
398
|
where one exists, and said to be only the flow where none does. The goal's page says once who plays
|
|
390
|
-
each role, states the design before the approximation, and
|
|
399
|
+
each role, states the design before the approximation, and lists its vocabulary: the words every card
|
|
400
|
+
uses the same way, each drawn with the glossary's definition.
|
|
391
401
|
|
|
392
|
-
**What was
|
|
393
|
-
and leaves Now, the rail and the graph.
|
|
402
|
+
**What was set aside** stays in the record: a dropped goal or question, and a parked question, keeps its
|
|
403
|
+
card and its page, and leaves Now, the rail and the graph. Now lists it apart, under Set aside: each parked
|
|
404
|
+
question with the decision that parked it and the first sentence of what was decided, then the dropped
|
|
405
|
+
questions and the closed goals, folded. A goal's page folds its parked and its dropped questions; a parked
|
|
406
|
+
question's page says, at the top, which decision parked it and why. `lab now` lists the parked questions in
|
|
407
|
+
one line each and counts the rest.
|
|
394
408
|
|
|
395
409
|
**A goal's page** holds its claim and its story: one list, oldest first, of what was found, what got
|
|
396
410
|
stuck, what the agent chose and what was decided with you, each decision with its text. It is the
|
|
@@ -444,17 +458,17 @@ and its sealed runs across as what they were.
|
|
|
444
458
|
**A card** is front matter, then its description as a paragraph, then `## Slot` sections. It never
|
|
445
459
|
holds an id, a state or an outcome. Every file of a lab is UTF-8 text; line ends of either kind
|
|
446
460
|
read the same, and so hash the same where a review is bound to a file. The front matter sits between
|
|
447
|
-
the first two lines that are exactly `---`. A key that holds a list (`needs`, `uses`, `see`, `about`, `holds`, `commits`,
|
|
461
|
+
the first two lines that are exactly `---`. A key that holds a list (`needs`, `uses`, `see`, `about`, `holds`, `parks`, `unparks`, `commits`,
|
|
448
462
|
`tests`) is written as one, `[a, b]`; every other key holds one value.
|
|
449
463
|
|
|
450
464
|
| Card | Front matter | Slots (word budget) |
|
|
451
465
|
| --- | --- | --- |
|
|
452
|
-
| `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, `- <
|
|
466
|
+
| `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) |
|
|
453
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) |
|
|
454
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) |
|
|
455
469
|
| `reading.md` | `title:`, `needs:`, `dropped: <why>` | description (70), Looks at: what, and where it is (110), Seen (320), Suggests (150) |
|
|
456
470
|
| `build.md` | `title:`, `needs:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
|
|
457
|
-
| `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) |
|
|
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) |
|
|
458
472
|
|
|
459
473
|
Any card may carry `see:`, a list of pages that explain it: pages of the lab's own library, and pages
|
|
460
474
|
of another library its charter names, written as folio writes them (`pier-folio:/content/readings/...`),
|
|
@@ -468,6 +482,36 @@ as in CI, which checks out the lab alone, the page cannot be looked for: that is
|
|
|
468
482
|
failure only with `--strict`. When the folder is there and the page is not, or the charter names no
|
|
469
483
|
such library, it is a problem.
|
|
470
484
|
|
|
485
|
+
**The glossary** is `GLOSSARY.md`, the only place a word is defined. A group is a `# Group` heading
|
|
486
|
+
and a term a `## Term` heading under it, followed by its definition as a paragraph and these optional
|
|
487
|
+
lines, each `- key: value`:
|
|
488
|
+
|
|
489
|
+
```
|
|
490
|
+
## Guard
|
|
491
|
+
The part that reads every call and refuses the ones the contract forbids.
|
|
492
|
+
- code: kna.gate:Guard
|
|
493
|
+
- avoid: gate, filter, policy
|
|
494
|
+
- see: entries/kna-gate
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
`code:` is where the term is in the code. `avoid:` lists, separated by commas, the words not to use
|
|
498
|
+
for this thing. `see:` names a page that explains the concept: a page of the lab's own library
|
|
499
|
+
(`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.
|
|
503
|
+
|
|
504
|
+
A word is defined once, in the glossary. A card that needs a word adds it there first, then uses it;
|
|
505
|
+
no card defines a word of its own. A concept that is not this lab's own (a method, a paper's idea) gets
|
|
506
|
+
a one-line entry and a `see:` link to the page that explains it, not a new explanation. The goal's
|
|
507
|
+
Vocabulary lists terms by name, and the goal's page and `lab show` draw each with the glossary's
|
|
508
|
+
definition and avoid words. `lab check` holds this: a name in Vocabulary that is not a term of the
|
|
509
|
+
glossary is a problem, and so is an item written with a meaning (`- word: what it means`): the part
|
|
510
|
+
before the colon is taken as the name, the glossary's text is what is shown, and the card must list the
|
|
511
|
+
name only. It checks an entry's `see:` as it checks a card's, including the note, and no failure, when
|
|
512
|
+
the other library is not on the machine. It does not look for avoid words in cards: a word to avoid for
|
|
513
|
+
one thing is often the right word for another, so `avoid:` is for the writer and the reviewer to read.
|
|
514
|
+
|
|
471
515
|
**An arm** is a list item under Arms: its name, a colon, and what it is, so that a reader who has
|
|
472
516
|
never seen it knows what was run.
|
|
473
517
|
|
|
@@ -562,7 +606,7 @@ in UTC. The file holds no other heading, and a line no other `|`. The kinds are
|
|
|
562
606
|
starting on and why now. A line written before the kit kept the time has none.
|
|
563
607
|
|
|
564
608
|
**Worked-out states.** A question is under discussion while the decision it came from is open, then
|
|
565
|
-
open, then yes or no; a page calls an open question with nothing under it "not started". A build is in
|
|
609
|
+
open, then yes or no; it is parked while the last settled decision that parks or brings it back parks it; a page calls an open question with nothing under it "not started". A build is in
|
|
566
610
|
progress once the log has a line about it, and built once it names its commits. An experiment whose
|
|
567
611
|
results review failed shows as review failed until it is replaced or dropped.
|
|
568
612
|
|
|
@@ -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
|
|
8
|
+
version = "1.1.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" }]
|
|
@@ -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
|
|
|
@@ -58,6 +58,11 @@ resource's new amount names the decision in `from`.
|
|
|
58
58
|
`lab new decision "<what it is about>" --about <id>`, fill **Seen** with what prompted it, then
|
|
59
59
|
`lab decide` as above, and do it.
|
|
60
60
|
|
|
61
|
+
When they set a question aside: "not now, maybe later" parks it, "never" drops it. Ask which, if it is not
|
|
62
|
+
clear. To park, list the question under `parks:` and `about:` on the decision before `lab decide`, and say in
|
|
63
|
+
the Decided text why and what would bring it back. To bring one back, a new decision lists it under
|
|
64
|
+
`unparks:`. To close a goal, put `reached: true` or `dropped: <why>` on its card, out of a decision.
|
|
65
|
+
|
|
61
66
|
## Rules
|
|
62
67
|
|
|
63
68
|
- Never copy the operator's messages into the lab. The record says what was decided and why.
|
|
@@ -36,8 +36,12 @@ 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
|
-
-
|
|
40
|
-
|
|
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.
|
|
@@ -51,9 +55,14 @@ The operator reads every card on the site, usually days later and without you. W
|
|
|
51
55
|
## When to open a decision
|
|
52
56
|
|
|
53
57
|
Open one when a question is answered or an experiment refutes what was expected, when a result
|
|
54
|
-
changes what the next question should be, when you want to add, reword or drop a goal or a question,
|
|
58
|
+
changes what the next question should be, when you want to add, reword, park or drop a goal or a question,
|
|
55
59
|
or when the resources do not cover the settled work. Not for anything else.
|
|
56
60
|
|
|
61
|
+
Park a question that may come back, drop one that will not. A decision parks a question by listing it
|
|
62
|
+
under `parks:` and under `about:`; its Decided text says why, and what would bring it back. Nothing under
|
|
63
|
+
a parked question moves until a later decision lists it under `unparks:`. Never start work under a
|
|
64
|
+
parked question, and never take it up because it looks open: it is listed under Set aside in `lab now`.
|
|
65
|
+
|
|
57
66
|
1. `lab new decision "<what it is about>" --about <the goals, questions or experiments it concerns>`.
|
|
58
67
|
2. On its card write **Seen** (what was observed, naming results), **Options** (a list of two or
|
|
59
68
|
three, each item an option with what it costs and what it changes) and **Recommendation**. Put under `holds:` only the
|
|
@@ -208,7 +217,7 @@ what should come next: open a decision.
|
|
|
208
217
|
- Never write that the operator decided something outside a decision recorded with `lab decide` (the
|
|
209
218
|
lab-talk skill).
|
|
210
219
|
- Open `plan/` and `runs/` only for the experiment you are working on.
|
|
211
|
-
- A term an outsider would not know goes in `GLOSSARY.md`, once, and is used the same way everywhere.
|
|
220
|
+
- 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.
|
|
212
221
|
|
|
213
222
|
## Before you stop
|
|
214
223
|
|
|
@@ -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
|
|
2
|
+
__version__ = "1.1.0"
|
|
@@ -11,7 +11,7 @@ KEYS = { # what a card's front matter may hold; a state is never among them
|
|
|
11
11
|
"experiment": {"title", "needs", "uses", "override", "replaces", "because", "cost", "waiting_on", "dropped", "see"},
|
|
12
12
|
"build": {"title", "needs", "commits", "tests", "dropped", "see"},
|
|
13
13
|
"reading": {"title", "needs", "dropped", "see"},
|
|
14
|
-
"decision": {"title", "about", "date", "holds", "decided", "see"},
|
|
14
|
+
"decision": {"title", "about", "date", "holds", "parks", "unparks", "decided", "see"},
|
|
15
15
|
}
|
|
16
16
|
|
|
17
17
|
|
|
@@ -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
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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:
|
|
@@ -109,6 +123,14 @@ def run(lab, rederive=True):
|
|
|
109
123
|
for i in d[key]:
|
|
110
124
|
if nodes.get(i, {}).get("type") not in ("goal", "question") + R.STEPS and not (key == "about" and i in lab.resources):
|
|
111
125
|
bad("links", d["path"], f"{key} names {i!r}, which does not exist")
|
|
126
|
+
for key in ("parks", "unparks"): # only a question is parked, and a decision that parks it or brings it back is about it
|
|
127
|
+
for i in d[key]:
|
|
128
|
+
if nodes.get(i, {}).get("type") != "question":
|
|
129
|
+
bad("links", d["path"], f"{key} names {i!r}, which is not a question: only a question is parked")
|
|
130
|
+
elif i not in d["about"]:
|
|
131
|
+
bad("links", d["path"], f"{key} names {i}, which is not under `about:`: a decision that parks a question or brings it back is about it")
|
|
132
|
+
for i in sorted(set(d["parks"]) & set(d["unparks"])):
|
|
133
|
+
bad("links", d["path"], f"both parks and unparks {i}")
|
|
112
134
|
done = d["decided"]
|
|
113
135
|
if done and not ({"date", "with"} <= set(done) and R.flat(d["slots"].get("Decided", ""))):
|
|
114
136
|
bad("cards", d["path"], "a settled decision holds when, with whom, and what was decided and why under Decided")
|
|
@@ -14,7 +14,7 @@ same place: what was committed under the old name is held under the new one.
|
|
|
14
14
|
- A `results.tsv` that a review has passed keeps every committed row. Once a results review that passed is committed
|
|
15
15
|
together with the rows it read, those rows stay, whatever the card and the file say later. Rows committed while
|
|
16
16
|
the last passed review was of other rows, such as a draft row added after it, were never reviewed and are not held.
|
|
17
|
-
- A settled decision keeps its `decided:`, its `about:` and its Decided text as first committed.
|
|
17
|
+
- A settled decision keeps its `decided:`, its `about:`, its `parks:`, its `unparks:` and its Decided text as first committed.
|
|
18
18
|
- A resource, once committed, is never removed. A metered resource's `granted`, `per_run` and `unit` change only together
|
|
19
19
|
with `from`, which then names another settled decision that lists the resource. Its `other_use` rows only grow.
|
|
20
20
|
- None of these files is deleted, and none changes its number.
|
|
@@ -140,8 +140,8 @@ def decisions(lab, versions=None, now=None):
|
|
|
140
140
|
return None
|
|
141
141
|
if not isinstance(fm, dict) or fm.get("decided") is None:
|
|
142
142
|
return None
|
|
143
|
-
|
|
144
|
-
return str(fm.get("decided")),
|
|
143
|
+
ids = lambda v: sorted(str(i) for i in (v if isinstance(v, list) else [v] if v is not None else []))
|
|
144
|
+
return str(fm.get("decided")), ids(fm.get("about")), ids(fm.get("parks")), ids(fm.get("unparks")), R.flat(slots.get("Decided", ""))
|
|
145
145
|
|
|
146
146
|
for where, commits in sorted(versions.items()):
|
|
147
147
|
if not DECISION.fullmatch(commits[-1][1]):
|
|
@@ -154,7 +154,7 @@ def decisions(lab, versions=None, now=None):
|
|
|
154
154
|
if was:
|
|
155
155
|
mine = path if path in now[where] else now[where][0]
|
|
156
156
|
if settled(R.read(os.path.join(root, mine))) != was:
|
|
157
|
-
bad(mine, f"was settled in {c[:8]}" + ("" if mine == path else f", as {path}") + ", and its `decided:`, its `about:` or its Decided text has changed since; a change of mind is a new decision")
|
|
157
|
+
bad(mine, f"was settled in {c[:8]}" + ("" if mine == path else f", as {path}") + ", and what it parks or brings back, its `decided:`, its `about:` or its Decided text has changed since; a change of mind is a new decision")
|
|
158
158
|
break
|
|
159
159
|
return problems
|
|
160
160
|
|
|
@@ -43,7 +43,7 @@ COLUMNS = {"results.tsv": ("name", "label", "value", "reads", "versus", "command
|
|
|
43
43
|
HASH = 2 # how a folder is hashed in the locks and runs made now; one without the marker was made with the first way
|
|
44
44
|
NUMBER = re.compile(r"[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?")
|
|
45
45
|
LISTS = {"goal": ("see",), "question": ("needs", "see"), "experiment": ("needs", "uses", "see"), "build": ("needs", "commits", "tests", "see"),
|
|
46
|
-
"reading": ("needs", "see"), "decision": ("about", "holds", "see")} # the front matter keys that hold a list
|
|
46
|
+
"reading": ("needs", "see"), "decision": ("about", "holds", "parks", "unparks", "see")} # the front matter keys that hold a list
|
|
47
47
|
TEXTS = ("title", "asks", "from", "replaces", "because", "cost", "waiting_on", "dropped", "answered") # and those that hold one value
|
|
48
48
|
|
|
49
49
|
|
|
@@ -470,9 +470,20 @@ class Lab:
|
|
|
470
470
|
group = block[2:].strip()
|
|
471
471
|
elif block.startswith("## "):
|
|
472
472
|
head, _, rest = block[3:].partition("\n")
|
|
473
|
-
code = re.search(
|
|
473
|
+
code, avoid, see = (re.search(rf"^- {key}: (.+)$", rest, flags=re.M) for key in ("code", "avoid", "see"))
|
|
474
474
|
definition = " ".join(l for l in rest.split("\n") if l.strip() and not l.startswith("- ")).strip()
|
|
475
|
-
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)})
|
|
476
487
|
return out
|
|
477
488
|
|
|
478
489
|
def _lines(self, text):
|
|
@@ -616,7 +627,7 @@ class Lab:
|
|
|
616
627
|
out = []
|
|
617
628
|
for n, path in self._numbered(f"{self.root}/decisions/D*.md", r"/D(\d+)-[^/]+\.md$", {}, "D<n>-<name>.md"):
|
|
618
629
|
fm, slots = self._card(path, "decision")
|
|
619
|
-
d = {"title": f"D{n}", "about": [], "holds": [], "decided": None, "date": "", "see": [], **fm, "id": f"D{n}", "type": "decision", "slots": slots,
|
|
630
|
+
d = {"title": f"D{n}", "about": [], "holds": [], "parks": [], "unparks": [], "decided": None, "date": "", "see": [], **fm, "id": f"D{n}", "type": "decision", "slots": slots,
|
|
620
631
|
"path": self.rel(path), "dir": self.rel(os.path.dirname(path))}
|
|
621
632
|
d["state"] = "decided" if d["decided"] else "open"
|
|
622
633
|
out.append(d)
|
|
@@ -668,8 +679,21 @@ class Lab:
|
|
|
668
679
|
return next(g for g in self.goals if g["id"] == q["goal"])
|
|
669
680
|
|
|
670
681
|
def live(self, nodes):
|
|
671
|
-
"""The goals or questions still pursued: what was dropped stays in the record and off the working pages."""
|
|
672
|
-
return [n for n in nodes if n["state"]
|
|
682
|
+
"""The goals or questions still pursued: what was dropped or parked stays in the record and off the working pages."""
|
|
683
|
+
return [n for n in nodes if n["state"] not in ("dropped", "parked")]
|
|
684
|
+
|
|
685
|
+
def pursued(self):
|
|
686
|
+
"""The steps still pursued: under a question that is neither parked nor dropped, of a goal still active. What was
|
|
687
|
+
set aside waits on a decision, not on the work, and is listed apart."""
|
|
688
|
+
keep = {q["id"] for q in self.live(self.questions) if self.nodes[q["goal"]]["state"] == "active"}
|
|
689
|
+
return [x for x in self.items if x["question"] in keep]
|
|
690
|
+
|
|
691
|
+
def set_aside(self):
|
|
692
|
+
"""What was set aside, for the page and the view that list it: parked and dropped questions, and goals that
|
|
693
|
+
were reached or dropped."""
|
|
694
|
+
return {"parked": [q for q in self.questions if q["state"] == "parked"],
|
|
695
|
+
"dropped": [q for q in self.questions if q["state"] == "dropped"],
|
|
696
|
+
"goals": [g for g in self.goals if g["state"] != "active"]}
|
|
673
697
|
|
|
674
698
|
def question_of(self, ident):
|
|
675
699
|
m = re.match(r"(G\d+\.Q\d+)", ident)
|
|
@@ -794,11 +818,22 @@ class Lab:
|
|
|
794
818
|
def replaced_by(self, ident):
|
|
795
819
|
return next((x for x in self.experiments if x.get("replaces") == ident and not x.get("dropped")), None)
|
|
796
820
|
|
|
821
|
+
def parked_by(self, ident):
|
|
822
|
+
"""The settled decision that parked this question, or None. The last settled decision, by number, that parks or
|
|
823
|
+
unparks it has the say: a question is set aside, and brought back, only by a decision."""
|
|
824
|
+
last = None
|
|
825
|
+
for d in self.decisions:
|
|
826
|
+
if d["state"] == "decided" and (ident in d["parks"] or ident in d["unparks"]):
|
|
827
|
+
last = d
|
|
828
|
+
return last if last and ident in last["parks"] else None
|
|
829
|
+
|
|
797
830
|
def _question_state(self, q):
|
|
798
831
|
if q.get("dropped") or self._goal_of(q).get("dropped"):
|
|
799
832
|
return "dropped"
|
|
800
833
|
if q.get("answer") in ("yes", "no"):
|
|
801
834
|
return q["answer"]
|
|
835
|
+
if self.parked_by(q["id"]):
|
|
836
|
+
return "parked"
|
|
802
837
|
return "open" if self.settled(q) else "under discussion"
|
|
803
838
|
|
|
804
839
|
def _reach(self):
|
|
@@ -843,6 +878,8 @@ class Lab:
|
|
|
843
878
|
return f"{g['id']} is {g['state']}"
|
|
844
879
|
if q["state"] == "under discussion":
|
|
845
880
|
return f"the decision {q.get('from') or 'it comes from'} to be settled"
|
|
881
|
+
if q["state"] == "parked":
|
|
882
|
+
return f"{q['id']} is parked by {self.parked_by(q['id'])['id']}: a decision that unparks it comes first"
|
|
846
883
|
if q["state"] != "open":
|
|
847
884
|
return f"{q['id']} is {'answered ' + q['state'] if q['state'] in ('yes', 'no') else q['state']}"
|
|
848
885
|
for need in x.get("needs") or []:
|
|
@@ -13,7 +13,7 @@ GENERIC = {"model", "field", "source", "group", "stop", "case", "score", "port",
|
|
|
13
13
|
e = html.escape
|
|
14
14
|
TONES = {"active": "info", "reached": "ok", "under discussion": "warn", "open": "info", "yes": "ok", "no": "warn", "decided": "ok",
|
|
15
15
|
"confirmed": "ok", "refuted": "bad", "unclear": "warn", "running": "info", "waiting": "warn", "in progress": "info", "built": "ok",
|
|
16
|
-
"review failed": "bad", "finished": "ok", "failed": "bad", "pass": "ok", "fail": "bad", "done": "ok"}
|
|
16
|
+
"review failed": "bad", "finished": "ok", "failed": "bad", "pass": "ok", "fail": "bad", "done": "ok", "parked": "plain"}
|
|
17
17
|
|
|
18
18
|
|
|
19
19
|
def nice(day):
|
|
@@ -190,6 +190,7 @@ CSS = """
|
|
|
190
190
|
.lv h3{margin:1.2em 0 .3em}
|
|
191
191
|
.lv .crumbs{font:500 .8rem var(--sans);color:var(--ink-3)}
|
|
192
192
|
.lv .crumbs a{color:var(--ink-3)}
|
|
193
|
+
.lv .avoid{display:block;font:.78rem var(--sans);color:var(--ink-3)}
|
|
193
194
|
.lv .lead{font-size:1.1rem;color:var(--ink-2);max-width:48rem}
|
|
194
195
|
.lv .pill{display:inline-block;padding:.08rem .55rem;border-radius:999px;font:600 .72rem/1.5 var(--sans);white-space:nowrap;background:var(--sunk);color:var(--ink-2)}
|
|
195
196
|
.lv .t-ok{background:var(--ok-soft);color:var(--ok)}
|
|
@@ -432,6 +433,7 @@ def decision_box(lab, T, d, link=True, title=True):
|
|
|
432
433
|
rows = []
|
|
433
434
|
if done:
|
|
434
435
|
rows.append((f'Decided {nice(d["decided"].get("date"))}', block(T, d["slots"].get("Decided", ""))))
|
|
436
|
+
rows += [(verb if done else f"Would {verb.lower()}", "<br>".join(named(lab, i) if i in lab.nodes else e(i) for i in d[key])) for key, verb in (("parks", "Parks"), ("unparks", "Brings back")) if d[key]]
|
|
435
437
|
rows += [(k, block(T, d["slots"][k])) for k in ("Seen", "Options", "Recommendation") if L.flat(d["slots"].get(k, ""))]
|
|
436
438
|
if not done:
|
|
437
439
|
held = lab.held_by(d)
|
|
@@ -595,7 +597,7 @@ def right_now(lab, T):
|
|
|
595
597
|
rows.append(f'<p class="what">{pill("nobody is on it", "warn")} Nothing is running, and no agent has said it is working.</p>'
|
|
596
598
|
f'<p>The next step is the agent\'s: {named(lab, x["id"])}: {T(you(x["next"]))}.</p>')
|
|
597
599
|
else:
|
|
598
|
-
waits = [x for x in lab.
|
|
600
|
+
waits = [x for x in lab.pursued() if x["state"] == "waiting" or (x["state"] == "planned" and x["next"])]
|
|
599
601
|
rows.append(f'<p class="what">{pill("idle", "plain")} Nothing is running and nothing is the agent\'s to move.</p>'
|
|
600
602
|
+ (f'<p>{named(lab, waits[0]["id"])} waits on {T(you(waits[0]["next"]))}.</p>' if waits else ""))
|
|
601
603
|
last = lab.last_record()
|
|
@@ -643,7 +645,7 @@ def home(lab, T):
|
|
|
643
645
|
out.append("<h2>To discuss with you</h2>" + ("".join(talk) or '<p class="muted">Nothing.</p>'))
|
|
644
646
|
busy = lab.doing()["about"] if lab.doing() else None
|
|
645
647
|
nxt = [x for x in lab.yours() if x["id"] != busy]
|
|
646
|
-
held = [x for x in lab.
|
|
648
|
+
held = [x for x in lab.pursued() if x["state"] == "waiting" or (x["state"] == "planned" and not x["mine"] and x["next"])]
|
|
647
649
|
if nxt or held:
|
|
648
650
|
out.append('<h2>Next</h2><table class="t"><tr><th>What</th><th>Who moves it</th><th>What happens next</th></tr>' + "".join(
|
|
649
651
|
f'<tr><td>{named(lab, x["id"])}</td><td>{"the agent" if x["mine"] else "waits"}</td><td>{("" if x["mine"] else "on ") + T(you(x["next"]))}</td></tr>' for x in nxt + held) + "</table>")
|
|
@@ -651,6 +653,7 @@ def home(lab, T):
|
|
|
651
653
|
for g in lab.live(lab.goals):
|
|
652
654
|
out.append(f'<div class="goalhead">{dot(g)}<a href="/{g["id"]}">{e(g["title"])}</a></div><p class="goalwhy">{T(g["description"])}</p>'
|
|
653
655
|
+ "".join(qcard(lab, T, q) for q in lab.live(g["questions"])))
|
|
656
|
+
out.append(set_aside_html(lab, T))
|
|
654
657
|
latest = happened(lab.lines)[-5:]
|
|
655
658
|
out.append('<h2>Latest</h2>' + log_html(lab, T, latest) + '<p style="font:.85rem var(--sans)"><a href="/log">The whole log</a></p>')
|
|
656
659
|
if lab.resources:
|
|
@@ -658,6 +661,29 @@ def home(lab, T):
|
|
|
658
661
|
return frame(lab, lab.cfg.get("title", lab.cfg["name"]), "".join(out))
|
|
659
662
|
|
|
660
663
|
|
|
664
|
+
def parked_line(lab, T, q):
|
|
665
|
+
d = lab.parked_by(q["id"])
|
|
666
|
+
return f'<p>{named(lab, q["id"])}: parked by {named(lab, d["id"])}. {T(L.first_sentence(L.flat(d["slots"].get("Decided", ""))))}</p>'
|
|
667
|
+
|
|
668
|
+
|
|
669
|
+
def set_aside_html(lab, T):
|
|
670
|
+
"""What was set aside, apart from the work: each parked question with the decision that parked it, then what was
|
|
671
|
+
dropped and the goals that were closed, folded."""
|
|
672
|
+
aside = lab.set_aside()
|
|
673
|
+
if not any(aside.values()):
|
|
674
|
+
return ""
|
|
675
|
+
out = ["<h2>Set aside</h2>"]
|
|
676
|
+
if aside["parked"]:
|
|
677
|
+
out.append('<p class="muted" style="font:.84rem var(--sans)">Parked by a decision; each comes back only by another.</p>' + "".join(parked_line(lab, T, q) for q in aside["parked"]))
|
|
678
|
+
if aside["dropped"]:
|
|
679
|
+
out.append(f'<details class="old"><summary>Dropped questions ({len(aside["dropped"])})</summary>' + "".join(
|
|
680
|
+
f'<p>{named(lab, q["id"])}: {T(str(q.get("dropped") or lab.nodes[q["goal"]].get("dropped") or ""))}</p>' for q in aside["dropped"]) + "</details>")
|
|
681
|
+
if aside["goals"]:
|
|
682
|
+
out.append(f'<details class="old"><summary>Closed goals ({len(aside["goals"])})</summary>' + "".join(
|
|
683
|
+
f'<p>{named(lab, g["id"])}: {e(label(g))}{". " + T(str(g["dropped"])) if g.get("dropped") else ""}</p>' for g in aside["goals"]) + "</details>")
|
|
684
|
+
return "".join(out)
|
|
685
|
+
|
|
686
|
+
|
|
661
687
|
def resources_table(lab):
|
|
662
688
|
per = any(isinstance(r.get("per_run"), (int, float)) for r in lab.resources.values() if isinstance(r, dict)) # the column is there only when a resource sets it
|
|
663
689
|
out = ['<table class="t"><tr><th>Resource</th><th>Used</th><th>Granted</th>' + ("<th>One run may use</th>" if per else "") + "</tr>"]
|
|
@@ -683,9 +709,14 @@ def goal_page(lab, T, g):
|
|
|
683
709
|
body.append('<div class="slots">' + "".join(slot(*x) for x in extra) + "</div>")
|
|
684
710
|
if pairs("Roles"):
|
|
685
711
|
body.append('<h2>Who plays what</h2><table class="t roles"><tr><th>Role</th><th>Played by, and what it does</th></tr>' + "".join(f"<tr><td>{T(a)}</td><td>{T(b)}</td></tr>" for a, b in pairs("Roles")) + "</table>")
|
|
686
|
-
|
|
687
|
-
|
|
712
|
+
words = lab.vocabulary(g)
|
|
713
|
+
if words: # the names are the card's; what each means is the glossary's, whatever the card says after a colon
|
|
714
|
+
rows = "".join(f'<tr><td>{e(w["entry"]["term"] if w["entry"] else w["name"])}</td><td>' + (e(w["entry"]["definition"]) + avoid_note(w["entry"]) if w["entry"] else '<span class="muted">not in the glossary</span>') + "</td></tr>" for w in words)
|
|
715
|
+
body.append('<h2>The words this lab uses</h2><table class="t roles"><tr><th>Word</th><th>What it means here, everywhere</th></tr>' + rows + "</table>")
|
|
688
716
|
body.append("<h2>Questions</h2>" + "".join(qcard(lab, T, q) for q in lab.live(g["questions"])))
|
|
717
|
+
parked = [q for q in g["questions"] if q["state"] == "parked"]
|
|
718
|
+
if parked:
|
|
719
|
+
body.append(f'<details class="old"><summary>Parked questions ({len(parked)})</summary>' + "".join(parked_line(lab, T, q) for q in parked) + "</details>")
|
|
689
720
|
gone = [q for q in g["questions"] if q["state"] == "dropped"]
|
|
690
721
|
if gone:
|
|
691
722
|
body.append(f'<details class="old"><summary>Dropped questions ({len(gone)})</summary>' + "".join(f'<p>{named(lab, q["id"])}: {T(str(q.get("dropped") or g.get("dropped") or ""))}</p>' for q in gone) + "</details>")
|
|
@@ -721,6 +752,9 @@ def question_page(lab, T, q):
|
|
|
721
752
|
live = [x for x in q["items"] if x["state"] not in ("replaced", "dropped")]
|
|
722
753
|
gone = [x for x in q["items"] if x["state"] == "dropped" or (x["state"] == "replaced" and not lab.replaced_by(x["id"]))]
|
|
723
754
|
body = [f'<h1>{e(q["title"])}</h1>']
|
|
755
|
+
if q["state"] == "parked":
|
|
756
|
+
d = lab.parked_by(q["id"])
|
|
757
|
+
body.append(f'<div class="box"><b>Parked</b> by {named(lab, d["id"])}: nothing under it moves until a decision brings it back. {T(L.flat(d["slots"].get("Decided", "")))}</div>')
|
|
724
758
|
before = [lab.nodes[i] for i in q["needs"] if i in lab.nodes]
|
|
725
759
|
if before:
|
|
726
760
|
body.append('<div class="slots">' + slot("Where we are coming from", "".join(f'<p>{named(lab, n["id"])} ({e(label(n))}).</p>{block(T, n["slots"].get("So far", ""))}' for n in before), "full") + "</div>")
|
|
@@ -954,6 +988,20 @@ def resources_page(lab, T):
|
|
|
954
988
|
return frame(lab, "Resources", "".join(body))
|
|
955
989
|
|
|
956
990
|
|
|
991
|
+
def avoid_note(g):
|
|
992
|
+
"""The words not to use for a term, in small type; nothing when there are none."""
|
|
993
|
+
return f' <span class="avoid">Avoid: {e(", ".join(g["avoid"]))}</span>' if g["avoid"] else ""
|
|
994
|
+
|
|
995
|
+
|
|
996
|
+
def see_link(lab, page):
|
|
997
|
+
"""A link to the page that explains a term, a page of the lab's own library or of a library the charter names."""
|
|
998
|
+
page = str(page)
|
|
999
|
+
if ":" not in page:
|
|
1000
|
+
return f'<a href="/docs/{e(page)}/">{e(pages(lab).get(page, page))}</a>'
|
|
1001
|
+
url = outside(lab, page)
|
|
1002
|
+
return f'<a href="{e(url)}">{e(page_title(lab, page))}</a>' if url else e(page)
|
|
1003
|
+
|
|
1004
|
+
|
|
957
1005
|
def glossary_page(lab, T):
|
|
958
1006
|
"""Every term, by group, each group closed until it is opened or the filter finds something in it."""
|
|
959
1007
|
url = code_url(lab)
|
|
@@ -973,7 +1021,8 @@ def glossary_page(lab, T):
|
|
|
973
1021
|
rows = []
|
|
974
1022
|
for g in terms:
|
|
975
1023
|
code = (f' · <a href="{url}/blob/main/src/{e(g["code"].split(":")[0].replace(".", "/"))}.py"><code>{e(g["code"])}</code></a>' if url else f' · <code>{e(g["code"])}</code>') if g["code"] else ""
|
|
976
|
-
|
|
1024
|
+
more = f' · See: {see_link(lab, g["see"])}' if g["see"] else ""
|
|
1025
|
+
rows.append(f'<dt id="{e(g["term"].lower().replace(" ", "-"))}">{e(g["term"])}</dt><dd>{e(g["definition"])}{code}{more}{avoid_note(g)}</dd>')
|
|
977
1026
|
body.append(f'<details class="ggroup"><summary>{e(name)}<span>{len(terms)} terms</span></summary><dl class="gloss">{"".join(rows)}</dl></details>')
|
|
978
1027
|
body.append("<script>(function(){var h=decodeURIComponent(location.hash.slice(1));var t=h&&document.getElementById(h);if(t){t.closest('details').open=true;t.scrollIntoView();}})();</script>")
|
|
979
1028
|
return frame(lab, "Glossary", "".join(body))
|
|
@@ -23,6 +23,9 @@ def decision_text(lab, d):
|
|
|
23
23
|
about = ", ".join(f"{i} {lab.nodes[i]['title']}" if i in lab.nodes else f"the resource {i}" for i in d["about"] if i in lab.nodes or i in lab.resources)
|
|
24
24
|
when = f"decided {d['decided'].get('date')} with {d['decided'].get('with')}" if d["decided"] else "open: to discuss with the operator"
|
|
25
25
|
out = [f"{d['id']} {d['title']} (raised {d.get('date')}, {when})" + (f"\nAbout: {about}" if about else "")]
|
|
26
|
+
for key, verb in (("parks", "Parks"), ("unparks", "Brings back")):
|
|
27
|
+
if d[key]:
|
|
28
|
+
out += [f"{verb}: " + ", ".join(f"{i} {lab.nodes[i]['title']}" if i in lab.nodes else i for i in d[key])]
|
|
26
29
|
out += [f"{slot}. {R.flat(d['slots'][slot])}" for slot in ("Seen", "Options", "Recommendation", "Decided") if R.flat(d["slots"].get(slot, ""))]
|
|
27
30
|
if d["state"] == "open":
|
|
28
31
|
held = lab.held_by(d)
|
|
@@ -69,7 +72,7 @@ def _now(lab):
|
|
|
69
72
|
going = [f"- {x['id']} {x['title']}: {r['id']}, started {r['started']}" for x in lab.experiments for r in x["runs"] + x["trials"] if r["state"] == "running" and not r["orphan"]]
|
|
70
73
|
out += ["" if not waiting else None, "Running"] + (going or ["- nothing"])
|
|
71
74
|
out += ["", "Yours next"] + ([f"- {x['id']} {x['title']} ({x['type']}): {x['next']}" for x in lab.yours()] or ["- nothing"])
|
|
72
|
-
held = [f"- {x['id']} {x['title']}: on {x['next']}" for x in lab.
|
|
75
|
+
held = [f"- {x['id']} {x['title']}: on {x['next']}" for x in lab.pursued() if x["state"] == "waiting" or (x["state"] == "planned" and not x["mine"])]
|
|
73
76
|
out += ["", "Not yours to move yet"] + (held or ["- nothing"])
|
|
74
77
|
out += ["", "Questions"]
|
|
75
78
|
for q in lab.live(lab.questions):
|
|
@@ -78,6 +81,12 @@ def _now(lab):
|
|
|
78
81
|
key = x["outcome"] if x["state"] == "done" and x.get("outcome") else x["state"]
|
|
79
82
|
counts[key] = counts.get(key, 0) + 1
|
|
80
83
|
out += [f"- {q['id']} ({q['state']}): {q['title']} [{', '.join(f'{n} {k}' for k, n in counts.items()) or 'nothing under it'}]"]
|
|
84
|
+
aside = lab.set_aside()
|
|
85
|
+
if any(aside.values()):
|
|
86
|
+
out += ["", "Set aside"] + [f"- {q['id']} (parked by {lab.parked_by(q['id'])['id']}): {q['title']}" for q in aside["parked"]]
|
|
87
|
+
rest = [f"{len(aside['dropped'])} question{'' if len(aside['dropped']) == 1 else 's'} dropped"] if aside["dropped"] else []
|
|
88
|
+
rest += [f"{len(aside['goals'])} goal{'' if len(aside['goals']) == 1 else 's'} closed ({', '.join(g['id'] + ' ' + g['state'] for g in aside['goals'])})"] if aside["goals"] else []
|
|
89
|
+
out += [f"- {', '.join(rest)}: lab show <id>"] if rest else []
|
|
81
90
|
if lab.resources:
|
|
82
91
|
out += ["", "Resources"] + [resource_line(lab, name) for name in lab.resources]
|
|
83
92
|
stuck = [f"- {r['id']}: {r['unpublished'].splitlines()[0]}" for r in lab.runs if r["unpublished"]]
|
|
@@ -125,11 +134,16 @@ def _show(lab, ident):
|
|
|
125
134
|
if n["type"] == "goal":
|
|
126
135
|
out = [f"{n['id']} ({n['state']}): {n['title']}", n["description"]] + came(n) + ["", f"Claim. {R.flat(n['slots'].get('Claim', '')) or 'not written yet'}", "", "Questions"]
|
|
127
136
|
out += [f"- {q['id']} ({q['state']}): {q['title']}. {q['description']}" for q in n["questions"]]
|
|
137
|
+
words = lab.vocabulary(n)
|
|
138
|
+
if words: # the names are the card's; each is drawn with the glossary's definition
|
|
139
|
+
out += ["", "Vocabulary (defined in GLOSSARY.md)"] + [entry_text(w["entry"], "- ") if w["entry"] else f"- {w['name']}: not in the glossary" for w in words]
|
|
128
140
|
return "\n".join(out + ["", "More: lab show <question id>"])
|
|
129
141
|
about = [l for l in lab.lines if l["about"] == ident or l["about"].startswith(ident + ".")]
|
|
130
142
|
decisions = ["", "Decisions about it"] + [f"- {d['id']} ({d['state']}): {d['title']}" for d in raised] if raised else []
|
|
131
143
|
if n["type"] == "question":
|
|
132
144
|
out = [f"{n['id']} ({n['state']}): {n['title']}", f"Asks: {n['asks']}", n["description"]] + came(n) + [""]
|
|
145
|
+
by = lab.parked_by(n["id"]) if n["state"] == "parked" else None
|
|
146
|
+
out += [f"Parked by {by['id']} {by['title']}: nothing under it moves until a decision brings it back (`unparks:`).", ""] if by else []
|
|
133
147
|
out += [f"{slot}. {lab.fill(R.flat(n['slots'].get(slot, '')))}\n" for slot, _ in R.SLOTS["question"]]
|
|
134
148
|
out += ["Under it"] + ([f"- {x['id']} {x['type']} ({state(x)}): {x['title']}" + (f". Next: {x['next']}" if x["mine"] else "") for x in n["items"]] or ["- nothing yet"])
|
|
135
149
|
out += decisions
|
|
@@ -233,7 +247,13 @@ def define(lab, term):
|
|
|
233
247
|
hits = [g for g in lab.glossary if g["term"].lower() == term.lower()] or [g for g in lab.glossary if term.lower() in g["term"].lower()]
|
|
234
248
|
if not hits:
|
|
235
249
|
raise SystemExit(f"{term!r} is not in the glossary")
|
|
236
|
-
return "\n\n".join(
|
|
250
|
+
return "\n\n".join(entry_text(g) for g in hits)
|
|
251
|
+
|
|
252
|
+
|
|
253
|
+
def entry_text(g, lead=""):
|
|
254
|
+
"""A glossary entry as the agent reads it: the definition, then the code, the words to avoid and the page that explains it."""
|
|
255
|
+
return (f"{lead}{g['term']}: {g['definition']}" + (f"\n code: {g['code']}" if g["code"] else "") + (f"\n avoid: {', '.join(g['avoid'])}" if g["avoid"] else "")
|
|
256
|
+
+ (f"\n see: {g['see']}" if g["see"] else ""))
|
|
237
257
|
|
|
238
258
|
|
|
239
259
|
def now(lab):
|
|
@@ -138,6 +138,8 @@ def new(lab, kind, parent, title, replaces=None, origin=None, about=(), because=
|
|
|
138
138
|
ident, path = f"{p['id']}.Q{n}", f"{p['dir']}/Q{n}-{slug(title)}/question.md"
|
|
139
139
|
text = CARDS["question"].format(title=quoted, origin=origin, asks=f"asks: {json.dumps(R.flat(asks), ensure_ascii=False)}\n" if R.flat(asks) else "")
|
|
140
140
|
elif kind in R.STEPS:
|
|
141
|
+
if p["state"] == "parked": # set aside by a decision: work under it starts again only once a decision brings it back
|
|
142
|
+
stop(f"{p['id']} is parked by {lab.parked_by(p['id'])['id']}: a decision that unparks it (`unparks: [{p['id']}]`) comes first")
|
|
141
143
|
n = 1 + max([int(x["id"].split(".")[-1]) for x in p["items"]] or [0])
|
|
142
144
|
ident, path = f"{p['id']}.{n}", f"{p['dir']}/{n}-{slug(title)}/{kind}.md"
|
|
143
145
|
fill = {"title": quoted, "description": "", "extra": "", "Compares": "", "Arms": "- ", "Cases": "", "Confirmed if": "- ", "Refuted if": "- ", "Outcomes": "", "Limits": ""}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
"""A question set aside by a decision: parked, off the working pages, with nothing under it moving until a later
|
|
2
|
+
decision brings it back; and a decision that parks or brings back cannot be edited afterwards."""
|
|
3
|
+
import glob
|
|
4
|
+
|
|
5
|
+
from test_flow import describe, fill, front, git, lab, open_question
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
def a_second_question(root):
|
|
9
|
+
lab(root, "new", "question", "G1", "Does the error fall on a biased coin?", "--from", "D1")
|
|
10
|
+
q = glob.glob(f"{root}/goals/G1-*/Q2-*/question.md")[0]
|
|
11
|
+
describe(q, "The law for a coin that is not fair, which the sampler can also draw.")
|
|
12
|
+
lab(root, "new", "build", "G1.Q2", "A biased sampler")
|
|
13
|
+
describe(glob.glob(f"{root}/goals/G1-*/Q2-*/1-*/build.md")[0], "The sampler with a weight on heads.")
|
|
14
|
+
return q
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def park(root, ident, title, decided, key="parks"):
|
|
18
|
+
out = lab(root, "new", "decision", title, "--about", ident)
|
|
19
|
+
card = sorted(glob.glob(f"{root}/decisions/D*.md"))[-1]
|
|
20
|
+
fill(card, Seen="The fair coin answers what the lab needs first.", Options="(a) Set it aside. (b) Keep it.", Recommendation="(a).")
|
|
21
|
+
front(card, **{key: f"[{ident}]"})
|
|
22
|
+
return card, out.split()[1].rstrip(":")
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def test_a_parked_question_leaves_the_work_and_comes_back_only_by_a_decision(tmp_path):
|
|
26
|
+
root = str(tmp_path)
|
|
27
|
+
open_question(root)
|
|
28
|
+
a_second_question(root)
|
|
29
|
+
assert "G1.Q2.1 A biased sampler" in lab(root, "now")
|
|
30
|
+
card, d2 = park(root, "G1.Q2", "Set the biased coin aside", "")
|
|
31
|
+
# an open decision parks nothing yet: the card says what it would park
|
|
32
|
+
assert "(open)" in lab(root, "show", "G1.Q2") and "Parks: G1.Q2" in lab(root, "show", d2)
|
|
33
|
+
lab(root, "decide", d2, "--with", "Ada", "The biased coin is parked: the fair coin answers what the lab needs first. It comes back if the law holds.")
|
|
34
|
+
now = lab(root, "now")
|
|
35
|
+
assert "Set aside" in now and f"G1.Q2 (parked by {d2})" in now and "A biased sampler" not in now.split("Set aside")[0]
|
|
36
|
+
assert f"Parked by {d2}" in lab(root, "show", "G1.Q2")
|
|
37
|
+
refused = lab(root, "new", "reading", "G1.Q2", "What the biased runs said", ok=False)
|
|
38
|
+
assert f"parked by {d2}" in refused and "unparks" in refused and not glob.glob(f"{root}/goals/G1-*/Q2-*/2-*")
|
|
39
|
+
assert "the record is sound" in lab(root, "check", "--no-rederive")
|
|
40
|
+
# a later decision brings it back
|
|
41
|
+
_, d3 = park(root, "G1.Q2", "Bring the biased coin back", "", key="unparks")
|
|
42
|
+
lab(root, "decide", d3, "--with", "Ada", "The law held on the fair coin, so the biased coin comes back.")
|
|
43
|
+
assert "(open)" in lab(root, "show", "G1.Q2") and "Set aside" not in lab(root, "now")
|
|
44
|
+
lab(root, "new", "reading", "G1.Q2", "What the biased runs said")
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
def test_the_site_shows_what_was_set_aside_apart_from_the_work(tmp_path):
|
|
48
|
+
import pytest
|
|
49
|
+
pytest.importorskip("folio.views")
|
|
50
|
+
from lab_kit.site import Provider
|
|
51
|
+
root = str(tmp_path)
|
|
52
|
+
open_question(root)
|
|
53
|
+
a_second_question(root)
|
|
54
|
+
_, d2 = park(root, "G1.Q2", "Set the biased coin aside", "")
|
|
55
|
+
lab(root, "decide", d2, "--with", "Ada", "The biased coin is parked: the fair coin answers what the lab needs first. It comes back if the law holds.")
|
|
56
|
+
site = Provider(root)
|
|
57
|
+
home = site.get("").main
|
|
58
|
+
assert "Set aside" in home and "parked by" in home and "The biased coin is parked" in home and "A biased sampler" not in home.split("Set aside")[0]
|
|
59
|
+
assert "Parked questions (1)" in site.get("G1").main
|
|
60
|
+
page = site.get("G1.Q2").main
|
|
61
|
+
assert "<b>Parked</b>" in page and "nothing under it moves" in page
|
|
62
|
+
assert "Parks" in site.get(d2).main
|
|
63
|
+
assert not any("biased coin?" in str(r) for r in site.rail())
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def test_parking_names_a_question_the_decision_is_about_and_stays_as_settled(tmp_path):
|
|
67
|
+
root = str(tmp_path)
|
|
68
|
+
open_question(root)
|
|
69
|
+
a_second_question(root)
|
|
70
|
+
card, d2 = park(root, "G1.Q2", "Set the biased coin aside", "")
|
|
71
|
+
front(card, parks="[G1.Q2.1, G1.Q1]", unparks="[G1.Q1]")
|
|
72
|
+
out = lab(root, "check", "--no-rederive", ok=False)
|
|
73
|
+
assert "parks names 'G1.Q2.1', which is not a question" in out and "parks names G1.Q1, which is not under `about:`" in out and "both parks and unparks G1.Q1" in out
|
|
74
|
+
front(card, parks="[G1.Q2]", unparks="[]")
|
|
75
|
+
lab(root, "decide", d2, "--with", "Ada", "The biased coin is parked: the fair coin answers what the lab needs first.")
|
|
76
|
+
git(root, "init", "-q")
|
|
77
|
+
git(root, "add", ".")
|
|
78
|
+
git(root, "commit", "-qm", "settled")
|
|
79
|
+
front(card, parks="[]") # what a settled decision parked cannot be taken back by editing it
|
|
80
|
+
assert "and what it parks or brings back, its `decided:`" in lab(root, "check", "--no-rederive", ok=False)
|
|
@@ -177,7 +177,8 @@ def test_a_readings_page_says_it_is_exploratory_and_what_was_dropped_leaves_the_
|
|
|
177
177
|
describe(card, "Reads the estimates that fell outside the band.")
|
|
178
178
|
fill(card, Looks_at="Twelve estimates.", Seen="1. Nine used the short sample.\n2. Three had the seed reset.", Suggests="Fix the seed.")
|
|
179
179
|
goal = glob.glob(f"{root}/goals/G1-*/goal.md")[0]
|
|
180
|
-
fill(goal, Roles="- The sampler: our code. It draws every estimate.", Vocabulary="-
|
|
180
|
+
fill(goal, Roles="- The sampler: our code. It draws every estimate.", Vocabulary="- tally: the card's own meaning, which is never shown", Approach="**The design.** Flip, count, compare.")
|
|
181
|
+
open(f"{root}/GLOSSARY.md", "w").write("# Terms\n\n## tally\nOne share of heads, from one sample.\n")
|
|
181
182
|
question = glob.glob(f"{root}/goals/G1-*/Q1-*/question.md")[0]
|
|
182
183
|
fill(question, Example="1. **The sampler** flips a coin 100 times.\n2. **The scorer** compares the share of heads with one half.")
|
|
183
184
|
lab(root, "new", "question", "G1", "A side question", "--from", "D1")
|
|
@@ -187,9 +188,10 @@ def test_a_readings_page_says_it_is_exploratory_and_what_was_dropped_leaves_the_
|
|
|
187
188
|
assert page.status == "done" and "This looked at data the lab already had." in page.main and "<ol><li>Nine used the short sample.</li>" in page.main and "What it suggests" in page.main
|
|
188
189
|
q = site.get("G1.Q1").main
|
|
189
190
|
assert '<span class="kind">reading</span>' in q and "<ol><li><b>The sampler</b> flips a coin 100 times.</li>" in q and "Fix the seed." in q
|
|
190
|
-
assert "The words this lab uses" in site.get("G1").main and "
|
|
191
|
+
assert "The words this lab uses" in site.get("G1").main and "One share of heads, from one sample." in site.get("G1").main and "never shown" not in site.get("G1").main and "<b>The design.</b> Flip, count, compare." in site.get("G1").main
|
|
191
192
|
assert "Who plays what" in site.get("G1").main and "It draws every estimate." in site.get("G1").main and "Dropped questions (1)" in site.get("G1").main
|
|
192
|
-
|
|
193
|
+
home = site.get("").main # off the working part of the front page; listed, folded, among what was set aside
|
|
194
|
+
assert "A side question" not in home.split("<h2>Set aside</h2>")[0] and "Dropped questions (1)" in home.split("<h2>Set aside</h2>")[1] and not any("A side question" in str(r) for r in site.rail()) and site.get("G1.Q2") is not None
|
|
193
195
|
|
|
194
196
|
|
|
195
197
|
def test_an_experiments_page_lists_its_runs_in_order_with_what_changed(tmp_path):
|
|
@@ -249,7 +251,7 @@ def test_nothing_written_in_a_lab_reaches_a_page_as_markup(tmp_path):
|
|
|
249
251
|
Q = json.dumps(P)
|
|
250
252
|
root = a_lab(tmp_path)
|
|
251
253
|
open(f"{root}/lab.toml", "a").write(f"code_url = {json.dumps('https://example.com/' + P)}\n")
|
|
252
|
-
open(f"{root}/GLOSSARY.md", "w").write(f"# {P}\n\n## sampler{P}\nWhat draws the estimates. {P}\n- code: {P}\n\n## estimate\nOne number from the sampler. {P}\n- code: sampler:{P}\n")
|
|
254
|
+
open(f"{root}/GLOSSARY.md", "w").write(f"# {P}\n\n## sampler{P}\nWhat draws the estimates. {P}\n- code: {P}\n\n## estimate\nOne number from the sampler. {P}\n- code: sampler:{P}\n- avoid: {P}, <b>x</b>\n- see: {P}\n")
|
|
253
255
|
open(f"{root}/resources.toml", "a").write(f"other_use = [{{date = \"2026-01-01\", amount = 1, what = {Q}}}]\n\n[{Q}]\nwhat = {Q}\nkey = {Q}\nunit = {Q}\ngranted = 5\nfrom = \"D1\"\nrules = [{Q}]\n")
|
|
254
256
|
goal = glob.glob(f"{root}/goals/G1-*/goal.md")[0]
|
|
255
257
|
qdir = glob.glob(f"{root}/goals/G1-*/Q1-*")[0]
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
"""A word is defined once, in GLOSSARY.md: avoid and see on an entry, and a goal that lists names only."""
|
|
2
|
+
import glob, os
|
|
3
|
+
import re
|
|
4
|
+
|
|
5
|
+
import pytest
|
|
6
|
+
|
|
7
|
+
from test_flow import fill, front, lab, open_question
|
|
8
|
+
from test_integrity import commit, under
|
|
9
|
+
|
|
10
|
+
ENTRIES = ("# Words\n\n## guard\nThe part that reads every call and refuses the ones the contract forbids.\n- code: kna.gate:Guard\n- avoid: gate, filter, `policy`\n- see: entries/the-guard\n\n"
|
|
11
|
+
"## field\nOne number on a grid.\n\n## LoRA\nA small adapter trained beside a frozen model.\n- see: notes:/content/concepts/lora/\n")
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def a_lab(tmp_path, glossary=ENTRIES, vocabulary="- guard\n- field"):
|
|
15
|
+
root = under(tmp_path, "lab")
|
|
16
|
+
qdir = open_question(root)
|
|
17
|
+
open(f"{root}/GLOSSARY.md", "w").write(glossary)
|
|
18
|
+
goal = glob.glob(f"{root}/goals/G1-*/goal.md")[0]
|
|
19
|
+
fill(goal, Vocabulary=vocabulary)
|
|
20
|
+
os.makedirs(f"{root}/docs/content/entries/the-guard")
|
|
21
|
+
open(f"{root}/docs/content/entries/the-guard/index.html", "w").write("<p>the guard</p>\n")
|
|
22
|
+
os.makedirs(tmp_path / "notes" / "content" / "concepts" / "lora")
|
|
23
|
+
open(tmp_path / "notes" / "content" / "concepts" / "lora" / "index.html", "w").write("<p>lora</p>\n")
|
|
24
|
+
open(f"{root}/docs/folio.yaml", "w").write("title: lab\nlibraries:\n notes:\n path: ../../notes\n url: https://notes.example\n")
|
|
25
|
+
commit(root)
|
|
26
|
+
return root, goal
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def test_avoid_and_see_are_read_and_shown_and_a_sound_lab_checks(tmp_path):
|
|
30
|
+
root, _ = a_lab(tmp_path)
|
|
31
|
+
out = lab(root, "define", "guard")
|
|
32
|
+
assert "guard: The part that reads every call" in out and "code: kna.gate:Guard" in out and "avoid: gate, filter, policy" in out and "see: entries/the-guard" in out
|
|
33
|
+
assert "avoid:" not in lab(root, "define", "field") and "see: notes:/content/concepts/lora/" in lab(root, "define", "LoRA")
|
|
34
|
+
assert "the record is sound" in lab(root, "check", "--strict")
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
def test_a_see_that_leads_nowhere_is_reported_like_a_cards(tmp_path):
|
|
38
|
+
root, _ = a_lab(tmp_path)
|
|
39
|
+
open(f"{root}/GLOSSARY.md", "a").write("\n## ghost\nNothing.\n- see: entries/not-there\n\n## stray\nNothing either.\n- see: elsewhere:/content/x/\n")
|
|
40
|
+
out = lab(root, "check", ok=False)
|
|
41
|
+
assert "GLOSSARY.md: ghost: see names the page entries/not-there, which is not in the library" in out
|
|
42
|
+
assert "GLOSSARY.md: stray: see names elsewhere:/content/x/, which is not a page of a library the charter names" in out
|
|
43
|
+
# the other library's page is missing while its folder is there
|
|
44
|
+
os.remove(tmp_path / "notes" / "content" / "concepts" / "lora" / "index.html")
|
|
45
|
+
os.rmdir(tmp_path / "notes" / "content" / "concepts" / "lora")
|
|
46
|
+
assert "LoRA: see names notes:/content/concepts/lora/, and the library notes holds no such page" in lab(root, "check", ok=False)
|
|
47
|
+
# the other library is not on the machine: a note, and a failure only when strict
|
|
48
|
+
os.rename(tmp_path / "notes", tmp_path / "away")
|
|
49
|
+
open(f"{root}/GLOSSARY.md", "w").write(ENTRIES)
|
|
50
|
+
out = lab(root, "check")
|
|
51
|
+
assert "the library notes is not here" in out and "the glossary name in it" in out and "problem(s)" not in out
|
|
52
|
+
assert "not everything could be checked here" in lab(root, "check", "--strict", ok=False)
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def test_the_glossary_page_shows_avoid_in_small_type_and_see_as_a_link_and_the_tooltip_is_the_definition(tmp_path):
|
|
56
|
+
pytest.importorskip("folio.views")
|
|
57
|
+
from lab_kit.site import Provider
|
|
58
|
+
root, _ = a_lab(tmp_path)
|
|
59
|
+
page = Provider(root).get("glossary").main
|
|
60
|
+
assert '<span class="avoid">Avoid: gate, filter, policy</span>' in page
|
|
61
|
+
assert 'See: <a href="/content/entries/the-guard/">' in page and 'href="https://notes.example/content/concepts/lora/"' in page
|
|
62
|
+
goal = Provider(root).get("G1").main
|
|
63
|
+
tip = re.search(r'<span class="term" data-tip="([^"]*)"', page + goal + Provider(root).get("G1.Q1").main)
|
|
64
|
+
assert tip is None or "Avoid" not in tip.group(1)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def test_the_goal_lists_names_and_shows_the_glossarys_definitions(tmp_path):
|
|
68
|
+
pytest.importorskip("folio.views")
|
|
69
|
+
from lab_kit.site import Provider
|
|
70
|
+
root, _ = a_lab(tmp_path)
|
|
71
|
+
assert "the record is sound" in lab(root, "check", "--strict")
|
|
72
|
+
main = Provider(root).get("G1").main
|
|
73
|
+
assert "The words this lab uses" in main and "The part that reads every call and refuses the ones the contract forbids." in main and "One number on a grid." in main
|
|
74
|
+
assert "Avoid: gate, filter, policy" in main
|
|
75
|
+
shown = lab(root, "show", "G1")
|
|
76
|
+
assert "- guard: The part that reads every call" in shown and "avoid: gate, filter, policy" in shown and "see: entries/the-guard" in shown and "- field: One number on a grid." in shown
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def test_a_name_that_is_not_in_the_glossary_is_reported(tmp_path):
|
|
80
|
+
pytest.importorskip("folio.views")
|
|
81
|
+
from lab_kit.site import Provider
|
|
82
|
+
root, _ = a_lab(tmp_path, vocabulary="- guard\n- sieve")
|
|
83
|
+
out = lab(root, "check", ok=False)
|
|
84
|
+
assert "Vocabulary lists 'sieve', which is not a term in GLOSSARY.md: add it there first" in out and "'guard'" not in out
|
|
85
|
+
assert "- sieve: not in the glossary" in lab(root, "show", "G1")
|
|
86
|
+
assert "not in the glossary" in Provider(root).get("G1").main
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def test_the_old_form_is_reported_and_the_glossarys_text_is_shown_never_the_cards(tmp_path):
|
|
90
|
+
pytest.importorskip("folio.views")
|
|
91
|
+
from lab_kit.site import Provider
|
|
92
|
+
root, _ = a_lab(tmp_path, vocabulary="- field: a number the card made up\n- sieve: another made-up meaning")
|
|
93
|
+
out = lab(root, "check", ok=False)
|
|
94
|
+
assert "Vocabulary lists 'field' with a meaning: list the name only, `- field`" in out
|
|
95
|
+
assert "Vocabulary lists 'sieve', which is not a term in GLOSSARY.md" in out and "'sieve' with a meaning" not in out
|
|
96
|
+
main, shown = Provider(root).get("G1").main, lab(root, "show", "G1")
|
|
97
|
+
assert "One number on a grid." in main and "made up" not in main and "made-up" not in main
|
|
98
|
+
assert "- field: One number on a grid." in shown and "made up" not in shown and "made-up" not in shown
|
|
99
|
+
|
|
100
|
+
|
|
101
|
+
def test_the_goal_a_new_lab_starts_with_has_an_empty_vocabulary_and_passes(tmp_path):
|
|
102
|
+
root = under(tmp_path, "lab")
|
|
103
|
+
open_question(root)
|
|
104
|
+
assert "## Vocabulary" in open(glob.glob(f"{root}/goals/G1-*/goal.md")[0]).read()
|
|
105
|
+
commit(root)
|
|
106
|
+
assert "Vocabulary" not in lab(root, "check")
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def test_markup_in_avoid_or_see_is_escaped(tmp_path):
|
|
110
|
+
pytest.importorskip("folio.views")
|
|
111
|
+
from lab_kit.site import Provider
|
|
112
|
+
P = 'x"><script>alert(1)</script>'
|
|
113
|
+
root, _ = a_lab(tmp_path, glossary=f"# Words\n\n## guard\nA guard.\n- avoid: {P}, <b>bold</b>\n- see: {P}\n\n## field\nA field.\n- see: other:{P}\n", vocabulary="- guard")
|
|
114
|
+
for page in (Provider(root).get("glossary").main, Provider(root).get("G1").main):
|
|
115
|
+
assert "<script>alert(1)" not in page and "<b>bold" not in page
|
|
116
|
+
assert "<script>" in Provider(root).get("glossary").main
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|