lab-kit-cli 1.14.0__tar.gz → 1.16.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.14.0 → lab_kit_cli-1.16.0}/AGENTS.md +2 -1
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/CHANGELOG.md +40 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/PKG-INFO +2 -2
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/README.md +1 -1
- lab_kit_cli-1.16.0/agents/page-reviewer.md +42 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/docs/model.md +89 -6
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/method/METHOD.md +5 -2
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/pyproject.toml +1 -1
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/skills/lab-mission/SKILL.md +3 -1
- lab_kit_cli-1.16.0/skills/lab-pages/SKILL.md +136 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/skills/lab-review/SKILL.md +5 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/skills/lab-work/SKILL.md +7 -1
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/__init__.py +1 -1
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/checks.py +8 -1
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/cli.py +41 -5
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/history.py +8 -0
- lab_kit_cli-1.16.0/src/lab_kit/pages.py +518 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/record.py +12 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/views.py +2 -1
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/write.py +24 -6
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_held.py +61 -0
- lab_kit_cli-1.16.0/tests/test_pages.py +245 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/.github/workflows/ci.yml +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/.github/workflows/policy.yml +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/.github/workflows/release.yml +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/.gitignore +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/CLAUDE.md +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/CONTRIBUTING.md +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/LICENSE +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/agents/reviewer.md +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/skills/lab-set-up/SKILL.md +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/skills/lab-talk/SKILL.md +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/runs.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/site.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/storylines.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/src/lab_kit/supervise.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_drafts.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_flow.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_integrity.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_mission.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_needs.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_order.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_parked.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_refusals.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_site.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_states.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_storylines.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_vocabulary.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tests/test_wording.py +0 -0
- {lab_kit_cli-1.14.0 → lab_kit_cli-1.16.0}/tools/import_run.py +0 -0
|
@@ -22,7 +22,8 @@ The tests build a small lab with the command itself and take it from a question
|
|
|
22
22
|
|
|
23
23
|
- The model wins. Change `docs/model.md` first, then the code, the method and the skills, in the same change.
|
|
24
24
|
- A rule a command holds is in `docs/model.md`, in the code and in a test together, with a case that it refuses.
|
|
25
|
-
- A command validates before it writes, and says what it wrote. No command writes a computed view into a lab.
|
|
25
|
+
- A command validates before it writes, and says what it wrote. No command writes a computed view into a lab. The one exception is `lab pages terms`,
|
|
26
|
+
which copies each glossary definition into the links to it, as hover text that `lab check` otherwise refuses.
|
|
26
27
|
- Never `git add -A`. Add the files you touched.
|
|
27
28
|
|
|
28
29
|
## Content and gate
|
|
@@ -1,5 +1,45 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.16.0
|
|
4
|
+
|
|
5
|
+
- **The library's pages are held to the record, when the library keeps `pages.toml`.** The question cards are the
|
|
6
|
+
facts, and no page repeats one. `pages.toml` gives every page a kind: storyline (the argument, revised when a
|
|
7
|
+
question it cites is answered), stable (how the method works, only corrected), reference (the trail, the
|
|
8
|
+
appendices, the maps) or retiring. `lab check` then holds that every page has a kind; a number quoted in a
|
|
9
|
+
`data-result="<experiment>:<result>"` element is the card's, from reviewed results; a storyline page tagged
|
|
10
|
+
`<meta name="numbers" content="tagged">` shows no other number; no page but a retiring one uses a phrase
|
|
11
|
+
`pages.toml` drops or claims to be first without "to our knowledge"; every storyline and stable page matches a
|
|
12
|
+
page reviewer's recorded pass (`page-reviews.tsv`, by a fingerprint of the page, so a page is read again only
|
|
13
|
+
when its text changes); every question answered since `since` records that its answer reached its pages
|
|
14
|
+
(`answers-in-pages.tsv`); each active storyline page links every storyline page; and a link to a glossary term
|
|
15
|
+
names a term the glossary has and carries its definition as hover text.
|
|
16
|
+
- `lab pages` lists the pages and whether each was passed as it stands; `lab pages check` runs only the page check;
|
|
17
|
+
`lab pages cites <id>` lists the storyline pages to revise when a question is answered; `lab pages passed` and
|
|
18
|
+
`lab pages answered` write the two records; `lab pages terms` writes the hover text from the glossary. `lab now`
|
|
19
|
+
lists the answers whose pages lag and the pages waiting for a reviewer, and `lab answer` says what comes next.
|
|
20
|
+
- A new skill, `lab-pages`, and a new role, `page-reviewer`, with fix rounds that converge: the same reviewer reads
|
|
21
|
+
only what changed, and passes from the third reading once nothing blocks. Method rule 8, lab-work and
|
|
22
|
+
lab-mission say when they apply.
|
|
23
|
+
- A lab without `pages.toml` is unchanged. Upgrading: run `lab init`, which installs the new skill and role. It
|
|
24
|
+
replaces any skill or role of the same name the lab wrote itself (`.agents/skills/lab-pages`,
|
|
25
|
+
`.agents/agents/page-reviewer.md`): move what is local in them to the lab's AGENTS.md first. A new lab's
|
|
26
|
+
`.gitattributes` unions the two page records, which sessions add rows to side by side. To opt in, write `pages.toml` with `since` and a kind for every page, then have a page reviewer pass each storyline and
|
|
27
|
+
stable page.
|
|
28
|
+
|
|
29
|
+
## 1.15.0
|
|
30
|
+
|
|
31
|
+
- **A later results review can supersede an earlier one, by name.** A reviewed row that had to be read another
|
|
32
|
+
way, to the same result (a command that read the run by a fixed path, rewritten to read `$RUN` so the gate
|
|
33
|
+
passes), was held as it was: `lab check` said "a row that a review had passed in ... is gone or changed", a
|
|
34
|
+
second passing review did not lift it, and putting the old row back brought back the failure it was changed
|
|
35
|
+
to fix. `lab review <experiment> results pass "<why>" --supersedes <of>` now names the earlier passing results
|
|
36
|
+
review by its `of`; it ends the note with "Supersedes the results review of <of>.", and the rows that review
|
|
37
|
+
read are held no more once it is committed together with the rows it read, which are held in their place. A review that does not name the earlier one
|
|
38
|
+
still supersedes nothing, and a note may not end with that sentence by hand. `lab review` refuses it on a plan or a failing review, for an `of` no earlier passing
|
|
39
|
+
results review has, and when the earlier review read the rows as they are now; `lab check` refuses a note that
|
|
40
|
+
names no earlier passing results review of other rows.
|
|
41
|
+
- The skill `lab-review` changed: run `lab init` in a lab after upgrading.
|
|
42
|
+
|
|
3
43
|
## 1.14.0
|
|
4
44
|
|
|
5
45
|
- **A home map has Current storylines.** When `lab.toml` names active storylines, one of the library's home
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: lab-kit-cli
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.16.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
|
|
@@ -76,4 +76,4 @@ where folio serves the lab, which brings `folio-kb` 0.5.0 or later, and list `la
|
|
|
76
76
|
|
|
77
77
|
- [docs/model.md](https://github.com/pierg/lab-kit/blob/main/docs/model.md): the contract. What you read, how a number becomes a result, who decides, the commands, the files.
|
|
78
78
|
- [method/METHOD.md](https://github.com/pierg/lab-kit/blob/main/method/METHOD.md): the eight rules every lab keeps.
|
|
79
|
-
- [skills/](https://github.com/pierg/lab-kit/blob/main/skills/): lab-set-up, lab-work, lab-review, lab-talk and lab-
|
|
79
|
+
- [skills/](https://github.com/pierg/lab-kit/blob/main/skills/): lab-set-up, lab-work, lab-review, lab-talk, lab-mission and lab-pages. [agents/](https://github.com/pierg/lab-kit/blob/main/agents/): the reviewer and the page reviewer.
|
|
@@ -57,4 +57,4 @@ where folio serves the lab, which brings `folio-kb` 0.5.0 or later, and list `la
|
|
|
57
57
|
|
|
58
58
|
- [docs/model.md](docs/model.md): the contract. What you read, how a number becomes a result, who decides, the commands, the files.
|
|
59
59
|
- [method/METHOD.md](method/METHOD.md): the eight rules every lab keeps.
|
|
60
|
-
- [skills/](skills/): lab-set-up, lab-work, lab-review, lab-talk and lab-
|
|
60
|
+
- [skills/](skills/): lab-set-up, lab-work, lab-review, lab-talk, lab-mission and lab-pages. [agents/](agents/): the reviewer and the page reviewer.
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: page-reviewer
|
|
3
|
+
description: >-
|
|
4
|
+
Reads one library page with fresh context and checks every number and claim against the question cards, the
|
|
5
|
+
units and the words the lab uses, and how the page reads. Use for every page the lab-pages skill writes or
|
|
6
|
+
revises. Give it only the page's path and the ids it cites. Never use it in the session that wrote the page.
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
You review one page of the library, under its `content/` folder. You did not write it. You need to run commands
|
|
10
|
+
(`lab show`, `lab pages check`, `lab pages passed`): if you cannot, say so at once and stop, without a verdict, so
|
|
11
|
+
the writer starts a reviewer that can. A reading without them is not a reading, and is not counted. Follow the lab-pages skill
|
|
12
|
+
(`.agents/skills/lab-pages/SKILL.md`, How a page reads) and the lab's own writing rules, which its AGENTS.md names.
|
|
13
|
+
|
|
14
|
+
1. Read the page top to bottom as a reader who does not know the lab. Note every name used before it is defined
|
|
15
|
+
(a term linked to the glossary at its first use counts as defined), every term the page defines in its own
|
|
16
|
+
words when `GLOSSARY.md` already has it (it should link instead), every glossary term whose first use is not
|
|
17
|
+
linked, every number without its unit or without "k of n", and every figure that comes before the words that
|
|
18
|
+
introduce it.
|
|
19
|
+
2. For every number and claim, open the card it rests on (`lab show <id>`) and check it: the value, what n counts,
|
|
20
|
+
the limit the card states, and whether the step's results review passed. A claim no card supports is a fault.
|
|
21
|
+
3. Check the words: the glossary's terms as it defines them, no phrase `pages.toml` drops, "first" only as "to our
|
|
22
|
+
knowledge" with the closest published work named, and nothing from a step still running given as a result.
|
|
23
|
+
4. Run `lab pages check`. Until you record a pass, it reports the page under review as "no page reviewer has
|
|
24
|
+
passed it"; that one line is expected. Any other line about the page is a fault.
|
|
25
|
+
|
|
26
|
+
Return pass, or fail with a numbered list of fixes, each naming the sentence and what the card says, and marked
|
|
27
|
+
**blocks** or **nit**. Everything steps 1 to 4 find blocks, and so does any `lab pages check` line about the page other
|
|
28
|
+
than the expected one; a nit is wording only.
|
|
29
|
+
|
|
30
|
+
Each time you read a page, keep a copy of it in your scratch folder, outside the repository and the store. When the
|
|
31
|
+
writer comes back after a fail, find what changed yourself, by diffing the page against that copy; do not rely on
|
|
32
|
+
the writer's list. For each changed spot, run steps 2 to 4 again, and re-check the page-wide order of step 1 (each
|
|
33
|
+
term defined or linked at its first use, each figure after its words). If anything changed that you did not ask
|
|
34
|
+
for, read the whole page again. Rounds are counted per page: nits may still be listed as fixes in the first and
|
|
35
|
+
second readings; from the third reading of the page on (the first reading plus two fix rounds), pass once nothing
|
|
36
|
+
blocks, and list the remaining nits briefly in your reply. If you are a fresh reviewer taking over a page, read the
|
|
37
|
+
whole page, with the earlier lists of fixes and the number of readings so far in hand; the count carries over.
|
|
38
|
+
|
|
39
|
+
On a pass, and only then, record it: `lab pages passed <page> "<one line: what you checked>"` (the page is its path
|
|
40
|
+
under `content/`, such as `entries/the-error-halves`). That line in `page-reviews.tsv` is the one thing you write
|
|
41
|
+
in the lab or the library; the only other file you write is your copy of the page in your scratch folder. The lab's
|
|
42
|
+
AGENTS.md may name places you never open; keep to them.
|
|
@@ -199,6 +199,20 @@ Each arrow is a command that refuses when the step before it is missing. You see
|
|
|
199
199
|
problem `lab check` reports at every step: a different result is a new experiment. A review is
|
|
200
200
|
bound to the rows it read by its `of`, so only those are held: a draft row committed after a
|
|
201
201
|
review, which that review never read, may still be corrected before the next review reads it.
|
|
202
|
+
**A review that supersedes another.** A reviewed row that must be read another way, to the same
|
|
203
|
+
result (a command that read the run by a fixed path and now reads `$RUN`), is not a new
|
|
204
|
+
experiment. A later results review that passes the new rows says so by name: `lab review
|
|
205
|
+
<experiment> results pass "<why the rows changed, and what was re-read>" --supersedes <of>`, where
|
|
206
|
+
`<of>` is the earlier passing results review's `of` (eight to sixteen of its first hex digits).
|
|
207
|
+
The command ends the note with "Supersedes the results review of <of>.". Once that review is
|
|
208
|
+
committed together with the rows it read, the rows the earlier review read are held no more, and
|
|
209
|
+
the new rows are held in their place; until then it supersedes nothing. A note cannot end with that
|
|
210
|
+
sentence except through `--supersedes`.
|
|
211
|
+
A later review that passes changed rows without naming the earlier one supersedes nothing, so the
|
|
212
|
+
old rows are still held. `lab review` refuses `--supersedes` on a plan review or a failing one, an
|
|
213
|
+
`of` that no earlier passing results review has, and a review that read the rows as they are now;
|
|
214
|
+
`lab check` refuses a note that names a review that is not an earlier passing results review of
|
|
215
|
+
other rows.
|
|
202
216
|
**The history that is read.** The check reads the history of the record under the lab's root as
|
|
203
217
|
that root is now. Moving the lab's root inside its repository, or to another repository, starts
|
|
204
218
|
again what is held: what was committed under the old root is not compared. And it needs the
|
|
@@ -409,6 +423,25 @@ parked or dropped is in either, and a goal, a question or a step sits in one row
|
|
|
409
423
|
before a result about something it lists under included or open is noted. `lab now` lists each storyline's
|
|
410
424
|
open experiments, and the live steps no storyline lists, by themselves or by their question or goal.
|
|
411
425
|
|
|
426
|
+
**Pages: the cards are the facts, and every page is passed as it stands.** Above the record, the library's pages
|
|
427
|
+
argue and explain; they never repeat a question card. A lab may opt in to hold its pages to the record by giving
|
|
428
|
+
its library a `pages.toml` (section 9), which gives every page a **kind**. A **storyline** page carries the
|
|
429
|
+
argument and is revised when a question it cites is answered. A **stable** page explains how the method works, or
|
|
430
|
+
the words and objects every page leans on, and is changed only to correct it. A **reference** page holds the full
|
|
431
|
+
trail, the appendices, the guide and the maps. A **retiring** page waits to be merged into another and retired.
|
|
432
|
+
The session that answers a question revises, in the same sitting, the storyline pages that cite it, and a **page
|
|
433
|
+
reviewer** who did not write them reads each against the cards and records a pass with a fingerprint of the page
|
|
434
|
+
as it read it. A page is read again only when its text changes. Then `lab check` holds that every page under the
|
|
435
|
+
sections the lab lists has a kind; a number a page quotes inside a `data-result` element is the value its card gives
|
|
436
|
+
that result, from results that were reviewed and not replaced or dropped; a storyline page says its numbers are
|
|
437
|
+
tagged and shows no other; no page but a retiring one uses a phrase the lab has dropped, or claims to be first
|
|
438
|
+
without "to our knowledge"; every
|
|
439
|
+
storyline and stable page matches a recorded pass; every question answered since the day the lab names has a row
|
|
440
|
+
saying its answer reached its pages; each active storyline page links every storyline page; and a link to a
|
|
441
|
+
glossary term names a term the glossary has, with its definition, as it now stands, as hover text. `lab now` lists
|
|
442
|
+
the answers that have not reached their pages and the pages waiting for a reviewer. A lab without `pages.toml` has
|
|
443
|
+
none of this.
|
|
444
|
+
|
|
412
445
|
## 5. What the agent uses
|
|
413
446
|
|
|
414
447
|
- **To look:** `lab now`, `lab show <id or path>`, `lab brief <question>`, `lab since`, `lab define <term>`. Each shows one level,
|
|
@@ -429,10 +462,17 @@ open experiments, and the live steps no storyline lists, by themselves or by the
|
|
|
429
462
|
`--evidence <folder>` writes an amendment instead (below, under `runs.tsv`). Where the system gives no way to tell that a process is the run's, nothing is
|
|
430
463
|
stopped and the command says so. `lab runs lost` records a run that started and whose folder is
|
|
431
464
|
gone for good.
|
|
432
|
-
- **Once:** `lab init`. Run again, it restores the method, the skills and the reviewer
|
|
465
|
+
- **Once:** `lab init`. Run again, it restores the method, the skills and the reviewer roles.
|
|
433
466
|
- **To carry out a decision:** `lab mission` (below).
|
|
467
|
+
- **For the library's pages,** when it keeps `pages.toml`: `lab pages` lists every page with its kind and
|
|
468
|
+
whether a page reviewer passed it as it now stands; `lab pages check` runs only what `lab check` holds about the
|
|
469
|
+
pages; `lab pages cites <id>` lists the storyline pages that cite a question or a step; `lab pages passed <page>
|
|
470
|
+
"<note>"` is the page reviewer's pass; `lab pages answered <question> "<note>"` records that an answer reached its
|
|
471
|
+
pages, and is refused while a storyline or stable page waits for a pass; `lab pages terms` writes each glossary
|
|
472
|
+
link's hover text from `GLOSSARY.md`. It is the one command that writes into a page, and it writes only what
|
|
473
|
+
`lab check` would otherwise refuse: the definition, as the glossary gives it, in the link's `title`.
|
|
434
474
|
|
|
435
|
-
That is
|
|
475
|
+
That is seventeen commands. `lab --help` lists them the same way.
|
|
436
476
|
|
|
437
477
|
**A mission.** A settled decision says what is done and why: the questions, the order, the resources. Carrying
|
|
438
478
|
it out can take many sessions, each starting sessions or runs of its own and watching them, and a session that
|
|
@@ -478,9 +518,10 @@ since when), and the time of the last recorded activity. A `doing` line stands u
|
|
|
478
518
|
about the same card, or the card being finished, ends it. When there is none, the page says that
|
|
479
519
|
nobody is on anything and names the next step. Nothing is inferred from a session being open.
|
|
480
520
|
|
|
481
|
-
|
|
482
|
-
a decision to you, record what was decided),
|
|
483
|
-
|
|
521
|
+
Six skills: `lab-set-up`, `lab-work`, `lab-review`, `lab-talk` (tell you where things stand, bring
|
|
522
|
+
a decision to you, record what was decided), `lab-mission` (save, launch, resume and close a mission), and
|
|
523
|
+
`lab-pages` (revise and review the library's pages when it keeps `pages.toml`). Two roles: the reviewer, and the
|
|
524
|
+
page reviewer.
|
|
484
525
|
|
|
485
526
|
Eight rules:
|
|
486
527
|
|
|
@@ -822,7 +863,8 @@ with each quote inside written twice, as a spreadsheet writes it, is read withou
|
|
|
822
863
|
quote is a character like any other.
|
|
823
864
|
|
|
824
865
|
**`reviews.tsv`** is written by `lab review`: `date`, `stage` (plan, results), `verdict` (pass, fail),
|
|
825
|
-
`by`, `of` (a hash of what was read), `note`.
|
|
866
|
+
`by`, `of` (a hash of what was read), `note`. A results review written with `--supersedes` ends its
|
|
867
|
+
note with "Supersedes the results review of <of>." (section 3, Reviewed rows stay).
|
|
826
868
|
|
|
827
869
|
**`resources.toml`** has one table per resource: `what`, `key` (where it is kept), `rules` (a list of
|
|
828
870
|
sentences), `retired` (why, once it is no longer used), and for a metered resource `unit`, `granted`,
|
|
@@ -973,6 +1015,47 @@ is the one place those pages have on a map; the overview and a retired storyline
|
|
|
973
1015
|
headings. The library has one such section, and no map that is not a home map has one. A lab without
|
|
974
1016
|
`[storylines]` has none of this.
|
|
975
1017
|
|
|
1018
|
+
**Pages.** A library that keeps `pages.toml` (beside `folio.yaml`) gives every page a kind, and says how the
|
|
1019
|
+
page check reads its pages:
|
|
1020
|
+
|
|
1021
|
+
```
|
|
1022
|
+
since = "2026-11-21" # every question answered from this day on records that it reached its pages
|
|
1023
|
+
dropped = ["law of everything", "breakthrough"] # phrases no page but a retiring one uses, as case-blind regular expressions
|
|
1024
|
+
names = ["Model", "Trial"] # words after which a number is a name, not a result ("Model 4", "Trial 2")
|
|
1025
|
+
sections = ["entries", "concepts", "guides"] # the folders under content/ whose pages each need a kind (these by default)
|
|
1026
|
+
first = ["for the first time", "first[- ]ever", "never before"] # claims to be first, which say "to our knowledge"
|
|
1027
|
+
|
|
1028
|
+
[pages]
|
|
1029
|
+
"index" = "reference"
|
|
1030
|
+
"entries/the-error-halves" = "storyline"
|
|
1031
|
+
"concepts/error-ratio" = "stable"
|
|
1032
|
+
```
|
|
1033
|
+
|
|
1034
|
+
A page is a path under `content/`: a folder, whose HTML files are all the page, or a file `<page>.html` (the home
|
|
1035
|
+
page, a map), never with `..`. `since` is required, a date; `dropped` is empty and `sections` is as shown unless set;
|
|
1036
|
+
`first` lists the claims to be first that a sentence makes only with "to our knowledge", and by default holds "for
|
|
1037
|
+
the first time", "first-ever", "never before", "had not been done" and "never been done", "shown", "proved" or
|
|
1038
|
+
"measured"; `[]` turns it off. Every folder under a listed section has a kind, and every page `[pages]` lists is
|
|
1039
|
+
there. A number quotes a result in an element `data-result="<experiment>:<result>"`, whose first number is compared
|
|
1040
|
+
with the result's value, rounded half up to as many decimals as the page shows, or with the number the card itself
|
|
1041
|
+
shows (`reads`: a share as a percentage, a difference in points); names joined by `+` are summed and by `*`
|
|
1042
|
+
multiplied, and a single result that reads as a percent or in points is compared as one, never added to others. The
|
|
1043
|
+
result is usable: its experiment's results were reviewed, and it was not replaced or dropped. An element whose end
|
|
1044
|
+
tag is left out ends where HTML ends it, with its parent; one still open where the page ends is refused. Each HTML
|
|
1045
|
+
file of a storyline page carries `<meta name="numbers" content="tagged">` and shows a number only in such an element, in an element
|
|
1046
|
+
marked `data-plain`, in `<code>`, a `<figure>` or an `<svg>`, in a link to a card (`/lab/<id>/`), or as the total
|
|
1047
|
+
in "k of n", a year, or right after one of `names` or of Result, Step, Figure, Table, Section, Part and Version, in
|
|
1048
|
+
any case. A link to a glossary term is `<a class="term" href="/lab/glossary/#<anchor>" title="<definition>">`, the
|
|
1049
|
+
anchor being the entry's heading, or a name under its `- also:`, in lower case with spaces as hyphens.
|
|
1050
|
+
|
|
1051
|
+
Two records sit beside `pages.toml`, each a TSV whose rows are only added, through the commands:
|
|
1052
|
+
`page-reviews.tsv` (`page`, `fingerprint`, `date`, `note`), one row per pass, and `answers-in-pages.tsv`
|
|
1053
|
+
(`question`, `answered`, `date`, `note`), one row per answer that reached its pages, keyed by the question and the
|
|
1054
|
+
date on its `answered:` line. A page's fingerprint is the first 16 hex digits of the SHA-256 of its HTML files, in
|
|
1055
|
+
path order, each as its path under `content/`, a zero byte, its bytes with every glossary link's `title` left out,
|
|
1056
|
+
and a zero byte. A storyline or stable page whose fingerprint no row of `page-reviews.tsv` holds waits for a page
|
|
1057
|
+
reviewer; a reference page never read is listed by `lab pages`, and not held.
|
|
1058
|
+
|
|
976
1059
|
**Worked-out states.** A goal is open until `reached: true` makes it done or `dropped:` drops it. A
|
|
977
1060
|
question is waiting while the decision it came from is open, then open, then done with its answer; it
|
|
978
1061
|
is parked while the last settled decision that parks or brings it back parks it. A step is waiting while
|
|
@@ -57,5 +57,8 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
|
|
|
57
57
|
thesis, the experiments included, those excluded or superseded, and those still open. What you propose,
|
|
58
58
|
order, park or drop follows the storylines' open rows and their reviewers' criticisms; when a result lands,
|
|
59
59
|
revise the overview and every storyline it touches, and move what a newer run supersedes to excluded. Adding,
|
|
60
|
-
merging or retiring a storyline is direction.
|
|
61
|
-
|
|
60
|
+
merging or retiring a storyline is direction. When the library keeps `pages.toml`, every page has a kind
|
|
61
|
+
(storyline, stable, reference or retiring), quotes a number only beside the result it comes from, and lands
|
|
62
|
+
only once a page reviewer who did not write it has passed it as it stands; the session that answers a question
|
|
63
|
+
revises the pages that cite it before the answer lands. *The storylines are held by `lab check` when `lab.toml`
|
|
64
|
+
names them, and the pages when the library keeps `pages.toml`; otherwise judged.*
|
|
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
|
|
|
5
5
|
[project]
|
|
6
6
|
dynamic = ["readme"]
|
|
7
7
|
name = "lab-kit-cli"
|
|
8
|
-
version = "1.
|
|
8
|
+
version = "1.16.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" }]
|
|
@@ -70,7 +70,9 @@ operator wants its parts run separately, such as one wave each.
|
|
|
70
70
|
4. Log each start: `lab mission log <id> "started G1.Q2.3 in its own session"`. Commit the
|
|
71
71
|
mission file each time you add lines.
|
|
72
72
|
5. Watch the sessions. When one ends a step, or is stuck, log it in the mission, and start the
|
|
73
|
-
next step the rules leave room for.
|
|
73
|
+
next step the rules leave room for. When the library keeps `pages.toml`, the session whose result
|
|
74
|
+
passes review, or that answers a question, revises the pages that cite it with the lab-pages skill
|
|
75
|
+
before it pushes: give each session that rule with its step.
|
|
74
76
|
|
|
75
77
|
## Resume: "resume the mission", "resume M3", "how is the mission going"
|
|
76
78
|
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: lab-pages
|
|
3
|
+
description: >-
|
|
4
|
+
Keep the library's pages in step with the record, when the library keeps `pages.toml`: the session that answers
|
|
5
|
+
a question revises, in the same sitting, the storyline pages that cite it, corrects a stable page only when it is
|
|
6
|
+
wrong, and lands nothing a page reviewer has not passed. Use whenever a question is answered (`lab answer`), when
|
|
7
|
+
a mission's result passes review, and when the operator says "update the pages", "revise the storyline",
|
|
8
|
+
"rewrite the top page", "fix this page" or names a page of the library.
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
# lab-pages
|
|
12
|
+
|
|
13
|
+
This skill applies only when the library keeps `pages.toml` (`lab pages` says so). Without it, lab-work's rules
|
|
14
|
+
for the overview and the storylines are all there is.
|
|
15
|
+
|
|
16
|
+
The library sits above the record. The question cards (`lab show <id>`, served at `/lab/<id>/`) are the facts, and
|
|
17
|
+
no page repeats one. Every page has a kind in `pages.toml`:
|
|
18
|
+
|
|
19
|
+
| Kind | What it holds | When it changes |
|
|
20
|
+
|---|---|---|
|
|
21
|
+
| `storyline` | the argument: the top page, the result pages, what is new, what is not shown yet | when a question it cites is answered, or on request |
|
|
22
|
+
| `stable` | how the method works, and the words and objects every page leans on | only to correct an error, or when the method itself changes |
|
|
23
|
+
| `reference` | the overview (the full trail), the storyline's scope page, the appendices, the guide, the maps | as lab-work's rules for the overview and the storylines say |
|
|
24
|
+
| `retiring` | a page waiting to be merged into another and retired | never; finish the merge instead |
|
|
25
|
+
|
|
26
|
+
`lab check` holds the rest (docs/model.md, section 9, Pages): every page has a kind; every number a page quotes in a
|
|
27
|
+
`data-result` element is its card's, from reviewed results; no page but a retiring one uses a phrase `pages.toml`
|
|
28
|
+
drops or claims to be first without "to our knowledge"; every storyline and stable page has passed a page reviewer
|
|
29
|
+
as it now stands; every answer since `since` has reached its pages; each active storyline page links every storyline
|
|
30
|
+
page; and every link to a glossary term names a term the glossary has, with its definition as hover text.
|
|
31
|
+
|
|
32
|
+
## When a question is answered
|
|
33
|
+
|
|
34
|
+
1. Pull. Read `lab show <question>` and each of its steps' Found, Means and result names.
|
|
35
|
+
2. List the pages to revise: `lab pages cites <question>`, plus the same for every question its answer
|
|
36
|
+
supersedes. Add the overview and the active storyline pages that `lab.toml` names (lab-work, The storylines and
|
|
37
|
+
the overview). Revise nothing else.
|
|
38
|
+
3. If no storyline page cites the question, decide whether the answer belongs in the argument: a new item on the
|
|
39
|
+
top page, a limit under an existing item, or a line under what is not shown yet. If it would change the thesis
|
|
40
|
+
or drop an item, bring it to the operator with lab-talk instead of writing it.
|
|
41
|
+
4. Revise each listed page (How a page reads, below). Change only what the answer changes. A number that changed
|
|
42
|
+
is changed everywhere it is quoted; `lab pages check` finds the quotes that disagree.
|
|
43
|
+
5. If the answer shows a stable page wrong, correct that sentence and nothing else, and say so where the library
|
|
44
|
+
keeps its log ("correction").
|
|
45
|
+
6. Review (below). Once every page has passed, record that the answer reached the pages:
|
|
46
|
+
`lab pages answered <question> "<the pages revised, or why none needed it>"`. It is refused while any storyline
|
|
47
|
+
or stable page waits for a pass. Until this row exists, `lab check` fails on the answered question: that failure
|
|
48
|
+
is expected before this step.
|
|
49
|
+
7. Run the lab's gate.
|
|
50
|
+
8. Land the answer, the pages, `page-reviews.tsv` and `answers-in-pages.tsv` together, as the lab's AGENTS.md says
|
|
51
|
+
content lands. If the push is refused because another session changed the same page, rebase, merge the two
|
|
52
|
+
edits, and have the merged paragraph read again.
|
|
53
|
+
|
|
54
|
+
A new storyline page is also linked from the active scope page (`lab.toml`'s `[storylines] active`), with the cards
|
|
55
|
+
it cites under included and the runs it leaves out under excluded; `lab check` fails on a storyline page the scope
|
|
56
|
+
page does not link.
|
|
57
|
+
|
|
58
|
+
The record is keyed by the question and the date on its `answered:` line. A question re-answered on the same day
|
|
59
|
+
is not due again: the session that re-answers it revises the pages all the same.
|
|
60
|
+
|
|
61
|
+
## On request
|
|
62
|
+
|
|
63
|
+
The operator names a page, or asks to revise the storyline. Follow step 4, then the review, then steps 7 and 8 for
|
|
64
|
+
the pages named, with no answer to record. A new page: write it in the page shape, give it a kind in `pages.toml`
|
|
65
|
+
and one place on a map, then review. Moving, renaming, merging or retiring a page is proposed to the operator as a
|
|
66
|
+
table (page, from, to, why) and done with the library's own commands only after their yes.
|
|
67
|
+
|
|
68
|
+
## Review
|
|
69
|
+
|
|
70
|
+
Every page you wrote or revised is read by a page reviewer who did not write it: start the `page-reviewer` agent
|
|
71
|
+
with only the page's path and the ids it cites. It checks each number and claim against the cards, the units, the
|
|
72
|
+
glossary's words and the lab's writing rules, and returns pass or a list of fixes. A page lands only on a pass.
|
|
73
|
+
Never review a page you wrote.
|
|
74
|
+
|
|
75
|
+
Fix rounds converge; they do not start over:
|
|
76
|
+
|
|
77
|
+
- The reviewer marks each fix **blocks** or **nit**. Everything its checklist finds blocks: a number or claim the
|
|
78
|
+
cards do not support, a running step given as a result, a count without "k of n" or a bare percentage, an
|
|
79
|
+
unhedged "first", a dropped phrase, a figure before its words, a term used undefined or defined when the glossary
|
|
80
|
+
has it, a broken sentence, and any `lab pages check` line about the page other than the expected one. A nit is wording
|
|
81
|
+
only.
|
|
82
|
+
- After a fail, make the fixes and send the page back to **the same reviewer** (continue that agent; do not start a
|
|
83
|
+
new one). It finds what changed itself, by diffing the page against the copy it kept of the version it read (in
|
|
84
|
+
its scratch folder, outside the repository and the store), not from your list. It re-checks each changed spot
|
|
85
|
+
against the cards, runs `lab pages check` again, and re-checks the page-wide order (each term linked at its first use,
|
|
86
|
+
each figure after its words). A change it did not ask for means it reads the whole page again.
|
|
87
|
+
- Rounds are counted per page. Nits may still be listed as fixes in the first and second readings; from the third
|
|
88
|
+
reading of the page on (the first reading plus two fix rounds), the reviewer passes once nothing blocks, and
|
|
89
|
+
lists the remaining nits briefly in its reply.
|
|
90
|
+
- If the original reviewer cannot be continued, a fresh reviewer reads the whole page, with the earlier lists of
|
|
91
|
+
fixes and the number of readings so far in hand; the count carries over. A pass is recorded only by a reviewer
|
|
92
|
+
that has every earlier fix in hand.
|
|
93
|
+
|
|
94
|
+
The reviewer records its pass in `page-reviews.tsv` (`lab pages passed`), with a fingerprint of the page as it read
|
|
95
|
+
it; the writer never records one. `lab check` fails on a storyline or stable page that no recorded pass matches, so a
|
|
96
|
+
page is read again only when its text changes, and never when it has not. `lab pages` lists every page and whether
|
|
97
|
+
its last change was passed. Commit `page-reviews.tsv` with the page.
|
|
98
|
+
|
|
99
|
+
## How a page reads
|
|
100
|
+
|
|
101
|
+
Follow the lab's own writing rules (its AGENTS.md says where they are) and lab-work's page style. On top of them:
|
|
102
|
+
|
|
103
|
+
- **The top page**, in this order: the problem; the one contribution; a map of the results on one screen, each with
|
|
104
|
+
its count; one short block per item with its claim, one figure, its count, its limit and one link to its page;
|
|
105
|
+
what is not shown yet.
|
|
106
|
+
- **Every other page**, in this order: a title that states the claim; the question in one sentence; the answer in
|
|
107
|
+
one bold sentence; one example worked by hand; one figure after the words that name its parts; the count and its
|
|
108
|
+
honest limit; a record box at the foot with the ids, linked. Ids appear nowhere else on the page, except in an
|
|
109
|
+
active storyline page's scope table, which lab-work fills with id links.
|
|
110
|
+
- **Numbers.** Write "k of n" with what n is, never a bare percentage. A storyline page carries
|
|
111
|
+
`<meta name="numbers" content="tagged">`, and every number on it from a card sits in an element naming its result:
|
|
112
|
+
`<span data-result="G1.Q1.1:ratio">50%</span>`, or `<span data-result="G1.Q2.1:held+held-late">12</span> of 12`. Names joined by `+` are summed and by `*`
|
|
113
|
+
multiplied, so a share times its total gives a count; a single result read as a percent or in points is compared
|
|
114
|
+
as one. The first number the element shows is compared with the card's value rounded to as many decimals as the page
|
|
115
|
+
shows, or with the number the card itself shows.
|
|
116
|
+
A number that is not a result (a definition, a count of what is studied) sits in an element marked `data-plain`;
|
|
117
|
+
the total in "k of n", a year, and a number right after a word `pages.toml` lists under `names` need neither.
|
|
118
|
+
- **Definitions live in the glossary.** The lab defines each word once, in `GLOSSARY.md`, served at
|
|
119
|
+
`/lab/glossary/`. A page never defines a term the glossary has: it links the term's first use on the page to its
|
|
120
|
+
entry, `<a class="term" href="/lab/glossary/#error-ratio">error ratio</a>`, then runs `lab pages terms`, which
|
|
121
|
+
writes the entry's definition into the link as hover text. The anchor is the entry's heading in lower case with
|
|
122
|
+
spaces as hyphens; a word of the page that is not a heading is listed under the entry's `- also:`. A word the
|
|
123
|
+
glossary lacks is added to `GLOSSARY.md` first, in the lab's words, then linked. A page explains only what is
|
|
124
|
+
particular to it. The hover text is left out of a page's fingerprint, so a changed definition asks for no new
|
|
125
|
+
review.
|
|
126
|
+
- **Words.** The glossary's terms as it defines them; none of the phrases `pages.toml` drops; "first" only as "to our
|
|
127
|
+
knowledge", naming the closest published work.
|
|
128
|
+
- **Running work.** A step still running has no result on any page; it may appear under what is not shown yet.
|
|
129
|
+
|
|
130
|
+
## Never
|
|
131
|
+
|
|
132
|
+
- A page that repeats a question card.
|
|
133
|
+
- A number on a storyline page without its `data-result`.
|
|
134
|
+
- A stable page reframed to fit a new result.
|
|
135
|
+
- A card, a decision or a locked plan changed to fit a page.
|
|
136
|
+
- A pass recorded by the session that wrote the page.
|
|
@@ -42,6 +42,11 @@ A failed plan is fixed by its author and read again.
|
|
|
42
42
|
can read, saying what you conclude ("The numbers are what the rows say, and the bars were fixed
|
|
43
43
|
before the run."). What you re-ran and what you could not verify comes after it: the page shows
|
|
44
44
|
the first sentence and folds the rest.
|
|
45
|
+
5. When rows that an earlier results review passed have changed since (`lab check` says "a row that a
|
|
46
|
+
review had passed in ... is gone or changed"), read what changed (`git diff` of `results.tsv` from
|
|
47
|
+
the commit it names) as well as the rows. Pass it only when each changed row still reports the same
|
|
48
|
+
result, read another way, and add `--supersedes <of>`, naming that earlier review's `of` from
|
|
49
|
+
`reviews.tsv`: the note says why the rows changed. A different result is a new experiment: fail it.
|
|
45
50
|
|
|
46
51
|
A failed results review is final for that experiment. Say in the note what a replacement must do
|
|
47
52
|
differently. Its numbers can then be cited nowhere: if a storyline page lists it under included, `lab check`
|
|
@@ -127,6 +127,11 @@ row, move it to included, or to excluded if it is void or no longer serves the a
|
|
|
127
127
|
that fails makes the experiment void: take it off every included row. `lab check` refuses what a row may
|
|
128
128
|
not list, and notes a storyline committed before a result about something it lists.
|
|
129
129
|
|
|
130
|
+
When the library keeps `pages.toml`, every page has a kind, and the lab-pages skill says how a page is revised and
|
|
131
|
+
reviewed: the session that answers a question revises the storyline pages that cite it (`lab pages cites
|
|
132
|
+
<question>`) in the same sitting, a page reviewer who did not write them passes each, and `lab pages answered`
|
|
133
|
+
records it before the answer lands. `lab check` holds it, and `lab now` lists what waits.
|
|
134
|
+
|
|
130
135
|
A home map has the section Current storylines (`<h2 id="current-storylines">`): one row per active storyline
|
|
131
136
|
page, and nothing else. `lab check` holds that its rows and `active` name the same pages.
|
|
132
137
|
|
|
@@ -287,7 +292,8 @@ repository, tests first. When it works, put `commits:` and `tests:` on the card
|
|
|
287
292
|
`lab now` lists such a question under **Yours next**, and a goal whose questions are all settled. Decide whether they answer it. For a test, `lab answer <question> yes|no|mixed "<what the answer rests
|
|
288
293
|
on>"`: yes and no say whether what the question expected held; mixed says part held and part did not,
|
|
289
294
|
and the sentence says which. For an estimate, `lab answer <question> found "<the finding, with its range
|
|
290
|
-
or its shape, and what it rests on>"`. Then bring **So far** up to date.
|
|
295
|
+
or its shape, and what it rests on>"`. Then bring **So far** up to date. When the library keeps `pages.toml`,
|
|
296
|
+
revise the pages the answer touches in the same sitting, with the lab-pages skill, before you push the answer. An answer rests on a done experiment that is not
|
|
291
297
|
void. If they do not answer it, add the next experiment. An answer usually changes
|
|
292
298
|
what should come next: open a decision.
|
|
293
299
|
|
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
"""lab-kit: a research lab's record, its method, and the command that keeps both."""
|
|
2
|
-
__version__ = "1.
|
|
2
|
+
__version__ = "1.16.0"
|
|
@@ -3,7 +3,7 @@ from __future__ import annotations
|
|
|
3
3
|
|
|
4
4
|
import glob, os, re
|
|
5
5
|
|
|
6
|
-
from . import history, storylines, record as R, runs as runs_, write
|
|
6
|
+
from . import history, pages, storylines, record as R, runs as runs_, write
|
|
7
7
|
|
|
8
8
|
KEYS = { # what a card's front matter may hold; a state is never among them
|
|
9
9
|
"goal": {"title", "from", "reached", "dropped", "see"},
|
|
@@ -305,6 +305,10 @@ def run(lab, rederive=True):
|
|
|
305
305
|
if r["stage"] not in ("plan", "results") or r["verdict"] not in ("pass", "fail") or not R.day(r["date"]) or not r["of"]:
|
|
306
306
|
bad("reviews", p, f"a row of reviews.tsv is not one `lab review` wrote: {R.flat(' '.join(r.values()))[:60]!r}")
|
|
307
307
|
break
|
|
308
|
+
for i, r in enumerate(x["reviews"]):
|
|
309
|
+
m = R.SUPERSEDING.search((r.get("note") or "").rstrip()) if r.get("stage") == "results" and r.get("verdict") == "pass" else None
|
|
310
|
+
if m and not any(e.get("stage") == "results" and e.get("verdict") == "pass" and e.get("of") == m.group(1) and e.get("of") != r.get("of") for e in x["reviews"][:i]):
|
|
311
|
+
bad("reviews", p, f"a results review supersedes {m.group(1)}, which is no earlier results review of other rows that passed")
|
|
308
312
|
if x["results"]:
|
|
309
313
|
if not x["lock"] or not x["finished"]:
|
|
310
314
|
bad("results", p, "has results with no locked plan and finished run behind them")
|
|
@@ -430,6 +434,9 @@ def run(lab, rederive=True):
|
|
|
430
434
|
# storylines: each active storyline's scope lists only what it may
|
|
431
435
|
storylines.check(lab, bad, notes)
|
|
432
436
|
|
|
437
|
+
# pages: when the library keeps pages.toml, every page has a kind, quotes its numbers as the cards give them and was passed as it stands
|
|
438
|
+
pages.check(lab, bad, notes)
|
|
439
|
+
|
|
433
440
|
# clean: the plans and the store stay out of default searches
|
|
434
441
|
ignore = R.read(f"{root}/.ignore") if os.path.exists(f"{root}/.ignore") else ""
|
|
435
442
|
if "plan/" not in ignore or "runs/" not in ignore:
|
|
@@ -3,7 +3,7 @@ from __future__ import annotations
|
|
|
3
3
|
|
|
4
4
|
import os, re, sys
|
|
5
5
|
|
|
6
|
-
from . import __version__, checks, runs, views, write
|
|
6
|
+
from . import __version__, checks, pages, runs, views, write
|
|
7
7
|
from .record import Lab, amount, find_root
|
|
8
8
|
|
|
9
9
|
USAGE = """To look
|
|
@@ -27,6 +27,13 @@ To carry out a decision
|
|
|
27
27
|
lab mission launch [<mission>] make it current; with no id, the one saved last. Several may be current
|
|
28
28
|
lab mission log [<mission>] "<what happened>" a line in a current mission's log
|
|
29
29
|
lab mission close [<mission>] [--stopped] "<what it did, or why it stopped>" done (or stopped), one line in log.md; the file is kept
|
|
30
|
+
For the library's pages (when it keeps pages.toml)
|
|
31
|
+
lab pages every page with its kind and whether a page reviewer passed it as it stands
|
|
32
|
+
lab pages check only what `lab check` holds about the pages, quickly
|
|
33
|
+
lab pages cites <question or step> the storyline pages that cite it: those to revise when it is answered
|
|
34
|
+
lab pages passed <page> "<what was checked>" the page reviewer's pass of a page as it now stands
|
|
35
|
+
lab pages answered <question> "<the pages revised>" the answer has reached its pages, each passed
|
|
36
|
+
lab pages terms write each glossary link's hover text from GLOSSARY.md
|
|
30
37
|
For evidence
|
|
31
38
|
lab lock <experiment>
|
|
32
39
|
lab run <experiment> [--trial] [--wait] [--changed "<what changed since the last run, and why>"] -- <command>
|
|
@@ -34,7 +41,9 @@ For evidence
|
|
|
34
41
|
lab runs close <run> "<why>" [--used <resource>=<amount>]... a run whose process died; --used for one that wrote no used.json
|
|
35
42
|
lab runs close <run> "<why>" --used <resource>=<amount>... --evidence <folder> an ended run that did not record what it used of a resource it ran on
|
|
36
43
|
lab runs lost <run> "<why>" [--used <resource>=<amount>]... a run that started and whose folder is gone for good
|
|
37
|
-
lab review <experiment> plan|results pass|fail "<note>" [--by <who>]
|
|
44
|
+
lab review <experiment> plan|results pass|fail "<note>" [--by <who>] [--supersedes <of>]
|
|
45
|
+
--supersedes: a results review that passes rows changed after the review
|
|
46
|
+
whose `of` it names had passed them; the note says why they changed
|
|
38
47
|
lab check [--no-rederive] [--strict] runs every command in results.tsv: only on a lab you trust. --strict fails when
|
|
39
48
|
history or the store could not be checked, as in CI
|
|
40
49
|
Once
|
|
@@ -63,7 +72,8 @@ def main(argv=None):
|
|
|
63
72
|
held = None
|
|
64
73
|
bare = [r for r in rest if r != "--all"]
|
|
65
74
|
looks = cmd == "mission" and len(bare) <= 1 and (not bare or re.fullmatch(r"M\d+", bare[0]) is not None) # `lab mission [<id>]` only reads
|
|
66
|
-
|
|
75
|
+
writes = cmd == "pages" and rest[:1] in (["passed"], ["answered"], ["terms"])
|
|
76
|
+
if cmd in ("new", "log", "decide", "answer", "lock", "review") or (cmd == "mission" and not looks) or writes: # one writer at a time, on the lab as it then is
|
|
67
77
|
held = runs.exclusive(find_root())
|
|
68
78
|
held.__enter__()
|
|
69
79
|
lab = Lab()
|
|
@@ -141,6 +151,31 @@ def main(argv=None):
|
|
|
141
151
|
if len(rest) != 3:
|
|
142
152
|
raise SystemExit(USAGE)
|
|
143
153
|
print(f"answered: {write.answer(lab, rest[0], rest[1], rest[2])}")
|
|
154
|
+
if pages.on(lab):
|
|
155
|
+
print(f"now revise the pages it touches (`lab pages cites {rest[0]}`) with the lab-pages skill; once a page reviewer has passed them, "
|
|
156
|
+
f"`lab pages answered {rest[0]} \"<the pages revised>\"`. `lab check` reports it until then")
|
|
157
|
+
elif cmd == "pages":
|
|
158
|
+
if not rest:
|
|
159
|
+
print(pages.listing(lab))
|
|
160
|
+
elif rest[0] == "check" and len(rest) == 1:
|
|
161
|
+
pages._require(lab)
|
|
162
|
+
found = []
|
|
163
|
+
pages.check(lab, lambda check, where, what: found.append(f"{check}: {where}: {what}"), [])
|
|
164
|
+
print("\n".join(sorted(set(found))) or "the pages are in step with the record")
|
|
165
|
+
if found:
|
|
166
|
+
return 1
|
|
167
|
+
elif rest[0] == "cites" and len(rest) == 2:
|
|
168
|
+
pages._require(lab)
|
|
169
|
+
print("\n".join(pages.cites(lab, rest[1])) or f"no storyline page cites {rest[1]}")
|
|
170
|
+
elif rest[0] == "passed" and len(rest) == 3:
|
|
171
|
+
print(f"recorded in {pages.record_pass(lab, rest[1], rest[2])}; commit it with the page")
|
|
172
|
+
elif rest[0] == "answered" and len(rest) == 3:
|
|
173
|
+
print(f"recorded in {pages.record_answer(lab, rest[1], rest[2])}; commit it with the answer and the pages")
|
|
174
|
+
elif rest[0] == "terms" and len(rest) == 1:
|
|
175
|
+
changed = pages.sync_terms(lab)
|
|
176
|
+
print("hover text written in " + ", ".join(changed) if changed else "every glossary link's hover text is its definition")
|
|
177
|
+
else:
|
|
178
|
+
raise SystemExit(USAGE)
|
|
144
179
|
elif cmd == "lock" and len(rest) == 1:
|
|
145
180
|
print(f"locked: {write.lock(lab, rest[0])}")
|
|
146
181
|
elif cmd == "run":
|
|
@@ -191,10 +226,11 @@ def main(argv=None):
|
|
|
191
226
|
else:
|
|
192
227
|
raise SystemExit(USAGE)
|
|
193
228
|
elif cmd == "review":
|
|
194
|
-
|
|
229
|
+
named = "--supersedes" in rest
|
|
230
|
+
by, supersedes = flag("--by"), flag("--supersedes")
|
|
195
231
|
if len(rest) != 4:
|
|
196
232
|
raise SystemExit(USAGE)
|
|
197
|
-
print(f"recorded in {write.review(lab, rest[0], rest[1], rest[2], rest[3], by or None)}")
|
|
233
|
+
print(f"recorded in {write.review(lab, rest[0], rest[1], rest[2], rest[3], by or None, supersedes if named else None)}")
|
|
198
234
|
elif cmd == "check":
|
|
199
235
|
if set(rest) - {"--no-rederive", "--strict"}:
|
|
200
236
|
raise SystemExit(USAGE)
|
|
@@ -382,6 +382,7 @@ def check(lab):
|
|
|
382
382
|
rows, read = where.rsplit("/", 1)[0] + "/results.tsv", set()
|
|
383
383
|
if rows not in now:
|
|
384
384
|
continue # never committed, so nothing is held; or committed and gone, which is said above
|
|
385
|
+
held_at = [] # (commit, the rows it holds, the last review that passed them there), newest first
|
|
385
386
|
for c, path in reversed(commits + versions.get(rows, [])): # every commit that touched the reviews or the rows
|
|
386
387
|
folder = os.path.dirname(path)
|
|
387
388
|
if c in read:
|
|
@@ -395,6 +396,13 @@ def check(lab):
|
|
|
395
396
|
seals = [l[5] for l in listed if len(l) >= 6 and l[1] == "run" and l[2] == "ended" and l[4] == "0"] # the finished run, as that commit lists it
|
|
396
397
|
if passed[-1].get("of") not in {R.text_hash(R.text_hash(was) + str(seal))[:16] for seal in seals}:
|
|
397
398
|
continue # the last review that passed there read other rows than these
|
|
399
|
+
held_at.append((c, was, passed[-1]))
|
|
400
|
+
# A passing results review that names an earlier one by its `of` (`lab review ... --supersedes`) supersedes it
|
|
401
|
+
# only once it is committed together with the rows it read: then those rows are held instead of the earlier ones.
|
|
402
|
+
gone = R.superseded([r for _, _, r in held_at])
|
|
403
|
+
for c, was, review in held_at:
|
|
404
|
+
if review.get("of") in gone:
|
|
405
|
+
continue # a later review, committed with the rows it read, superseded it and said why
|
|
398
406
|
lost = subsequence(was.splitlines(), R.read(os.path.join(root, now[rows][0])).splitlines())
|
|
399
407
|
if lost is not None:
|
|
400
408
|
bad(now[rows][0], f"a row that a review had passed in {c[:8]} is gone or changed: {lost[:70]!r}. Reviewed rows stay; a different result is a new experiment")
|