Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ jobs:
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python }}
# The site's tests need folio's views hook, in folio-kb 0.5.0 and later: the `site` extra brings it.
# The site's tests need folio's views hook, in folio-kb 0.7.0 and later: the `site` extra brings it.
- name: Install lab-kit, and folio for the site's tests
run: |
python -m pip install --upgrade pip
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ jobs:
with:
python-version: "3.12"
# Never publish untested: the same gate CI runs, and here the site's tests must run too, so
# folio-kb 0.5.0 or later has to be on PyPI before lab-kit is released.
# folio-kb 0.7.0 or later has to be on PyPI before lab-kit is released.
- run: python -m pip install -e ".[dev,site]"
- run: python -m pytest -q -rs
env:
Expand Down
29 changes: 29 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,34 @@
# Changelog

## 1.6.0

One set of states for every card, and the checks that keep a card from saying what the record does not. The site's
Now page is a dashboard and its rail is the tree of goals, questions and steps; the Graph page is gone. It needs
folio 0.7.0, whose rail draws the tree. The skill `lab-work` and the method changed: run `lab init` in a lab after
upgrading.

- **Seven states, the same for every kind of card:** open, waiting, running, parked, done, replaced, dropped. What
was `planned`, `active` or `in progress` is open or running; `built` and `reached` are done; `under discussion`
is waiting. A done card may carry a label: a question's answer (yes, no or mixed) and an experiment's outcome
(confirmed, refuted, unclear, or void when its results review failed). `lab show` and `lab now` print
`done, confirmed`. A decision is open or done.
- **A failed results review makes an experiment done and void,** not a step to replace. No page uses its numbers,
and what it made may still be used.
- **`lab answer <question> yes|no|mixed`.** An answer rests on a done experiment that is not void.
- **A need is met by a done step, and by a replaced or dropped experiment whose run finished:** a later step may
use what such an experiment made (a frozen program), and says so with `needs:`.
- **`drops:` on a decision** drops the questions and steps it names once it is settled, like `parks:`. It is frozen
with the rest of what a settled decision says.
- **`waiting_on:` is for what is outside the lab.** `lab check` refuses one that names a goal, question, step or
decision: that wait never clears by itself. Builds and readings may carry it too.
- **So far says what was learned.** `lab check` refuses a question's So far with words that say where a step
stands ("is running", "is next", "no result yet"), and reports a So far last committed before a `result` line
about a step under the question, or one it names. `lab log <step> result` says so.
- **The site.** Now shows what is live with a pulsing sign (runs, the current mission, what the agent is on), what
needs the operator, what is next for the agent in the agreed order, a tile per question with one sign per step,
the resources and the latest events. The rail nests goal, question and step, opens on the current page, marks each
with a sign for its state, folds what was replaced, dropped or set aside, and ends with a key.

## 1.5.0

A closed mission is kept. In 1.4.0 `lab mission close` removed the mission's file, and with it the only account of
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ record to the operator as a live site: `lab_kit.site` draws the pages, and nothi

```
Goal what the lab wants to be able to say
Question a yes-or-no question: what we expect, what would prove us wrong, what we know so far
Question a question answered yes, no or mixed: what we expect, what would prove us wrong, what we know so far
Build something an experiment needs that has to be made first
Reading a look at what already exists: it suggests, and never confirms
Experiment what is compared, what would confirm, what would refute; then what was found
Expand Down
126 changes: 89 additions & 37 deletions docs/model.md

Large diffs are not rendered by default.

10 changes: 7 additions & 3 deletions method/METHOD.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,9 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
`lab check`; the review itself is judged.*
3. **A miss is recorded like a hit, and nothing recorded is edited. What a locked plan demands is never
changed; its words may be made clearer.** A failed run is kept. A refuted line is an outcome like
any other. A changed plan, a failed review or a partial score is a new experiment that replaces the
old one and says why in a sentence. What an experiment demands (each bar's role, result, comparison and
any other. A changed plan or a partial score is a new experiment that replaces the old one and
says why in a sentence. An experiment whose results review failed is done and void: no page uses its
numbers, and what it made may still be used through `needs:`. What an experiment demands (each bar's role, result, comparison and
number, each arm's name, the resources it uses) is locked once; a clearer word keeps its meaning,
and a reviewer who did not write it reads it. It is run until one run finishes, and a run after a fix says what changed. Once a
run has finished, nothing more runs under it. Every run is listed in the experiment's `runs.tsv`,
Expand All @@ -24,7 +25,10 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
4. **Write for a reader who was not there.** Every page stands on its own: it says what each thing it
mentions is, names each arm of an experiment and what it is, names another page by its exact
title, and uses a term only as the glossary defines it, the one place a word is defined. A number is said once: it lives in its result row, and a card names it. A state is
worked out, never written. *The numbers and the budgets are held by `lab check`; whether a page
worked out, never written, and So far says what was learned, never where a step stands. Every
card has one of the same states: open, waiting, running, parked, done, replaced or dropped. A
number's label says what it counts and of how many, in one set of cases named once: "of the 20
checks the solver leaves open", not "of 20". *The numbers and the budgets are held by `lab check`; whether a page
can be read cold is judged, and the reviewer reads for it.*
5. **Decide everything that is not direction or resources, and never wait idle.** Direction is the
goals and the questions. Resources are what `resources.toml` lists and how much. For those two,
Expand Down
6 changes: 3 additions & 3 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ build-backend = "hatchling.build"
[project]
dynamic = ["readme"]
name = "lab-kit-cli"
version = "1.5.0"
version = "1.6.0"
description = "A research lab's record, its method, and the command that keeps both."
license = "MIT"
authors = [{ name = "Piergiuseppe Mallozzi" }]
Expand All @@ -14,9 +14,9 @@ dependencies = ["pyyaml", "tomli; python_version < '3.11'"]

[project.optional-dependencies]
dev = ["pytest"]
# folio serves the operator's site and lab_kit.site draws its pages, through the views hook of folio-kb 0.5.0.
# folio serves the operator's site and lab_kit.site draws its pages, through the views hook of folio-kb 0.7.0.
# The `lab` command itself needs no folio.
site = ["folio-kb>=0.5.0"]
site = ["folio-kb>=0.7.0"]

[project.urls]
Homepage = "https://github.com/pierg/lab-kit"
Expand Down
24 changes: 18 additions & 6 deletions skills/lab-work/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ the plan in fixed boxes, then the steps and the record. Write the card for that
no result: a number observed never goes in a picture. Use the site's colours (`var(--ink)`,
`var(--ink-2)`, `var(--accent)`, `var(--surface)`, `var(--rule)`, `var(--sans)`) and never a fixed
colour, so it reads in light and dark. Keep its text at least 12 pixels at its own width.
- **What we know so far holds everything observed.** The card's `## So far`: where it stands, what
- **What we know so far holds everything observed.** The card's `## So far`: what was learned, what
was learned after the plan was written, later decisions and what they change, reference runs. On
an experiment it sits outside the plan, so you keep it current after the lock. When a decision
changes how a node is read, give the decision a `## Note` of one or two sentences: a node whose So
Expand Down Expand Up @@ -178,6 +178,10 @@ until that decision is settled; after that it needs no further yes.
9. Once the review has passed, write **Found** and **Means** on the card. Name each result instead
of typing its number: `{attack-success}`. It is shown the way its row says it reads. Bring the
experiment's **So far** up to date, and rewrite the question's **So far** the same way, with full names: `{G1.Q1.2:attack-success}`.
So far says what was learned, never where a step stands ("is running", "is next", "no result yet"):
the pages draw each step's state. `lab check` reports a question's So far that was last committed
before a result under it, or one it names. Give each result a label that says what it counts and
of how many, in a set of cases the lab names once ("of the 20 checks the solver leaves open").
10. `lab log <experiment> result "<what was found, in a sentence, without numbers>" "<so what>"`.

The outcome is worked out from the lines: you never write it.
Expand Down Expand Up @@ -232,18 +236,26 @@ repository, tests first. When it works, put `commits:` and `tests:` on the card

## When all experiments of a question are done

Decide whether they answer it. `lab answer <question> yes|no "<what the answer rests on>"`, and bring
**So far** up to date. If they do not answer it, add the next experiment. An answer usually changes
Decide whether they answer it. `lab answer <question> yes|no|mixed "<what the answer rests on>"`, and
bring **So far** up to date. Yes and no say whether what the question expected held; mixed says part
held and part did not, and the sentence says which. An answer rests on a done experiment that is not
void. If they do not answer it, add the next experiment. An answer usually changes
what should come next: open a decision.

## When something is in the way

- **It is yours to decide.** Decide, `lab log <id> agent "<what you decided>" "<why>"`, go on.
- **It is the operator's** (direction or resources). Open a decision, then work on what it does not
hold.
- **It waits on something outside the lab.** Put `waiting_on: <what>` on the card, log a `stuck`
line, and remove both when it clears.
- **It will not be done.** Put `dropped: <why>` on the card and log it.
- **It waits on something outside the lab** (an account, a person, a machine being repaired). Put
`waiting_on: <what>` on the card, log a `stuck` line, and remove both when it clears. A wait on the
lab's own work is a `needs:`, or a decision's `holds:`: `lab check` refuses a `waiting_on:` that
names a goal, question, step or decision.
- **It will not be done.** Put `dropped: <why>` on the card and log it. When a decision drops it,
the decision lists it under `drops:`, and the card needs nothing more.
- **A later step uses what a replaced or void step made** (a frozen program, a data set). Put the
step under `needs:`: a need is met by a done step, and by a replaced or dropped experiment whose
run finished.
- **A run's process died.** `lab runs close <run> "<why>"`. It stops whatever the run left going and
reads the run's `used.json`. If the run used a metered resource and wrote none, say what it used:
`--used <resource>=<amount>`.
Expand Down
2 changes: 1 addition & 1 deletion src/lab_kit/__init__.py
Original file line number Diff line number Diff line change
@@ -1,2 +1,2 @@
"""lab-kit: a research lab's record, its method, and the command that keeps both."""
__version__ = "1.5.0"
__version__ = "1.6.0"
Loading
Loading