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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/AGENTS.md +8 -4
  2. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/CHANGELOG.md +26 -0
  3. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/PKG-INFO +4 -3
  4. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/README.md +3 -2
  5. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/docs/model.md +70 -6
  6. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/method/METHOD.md +2 -1
  7. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/pyproject.toml +1 -1
  8. lab_kit_cli-1.4.0/skills/lab-mission/SKILL.md +96 -0
  9. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/skills/lab-talk/SKILL.md +1 -0
  10. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/skills/lab-work/SKILL.md +4 -0
  11. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/src/lab_kit/__init__.py +1 -1
  12. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/src/lab_kit/checks.py +43 -3
  13. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/src/lab_kit/cli.py +30 -2
  14. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/src/lab_kit/history.py +6 -4
  15. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/src/lab_kit/record.py +49 -0
  16. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/src/lab_kit/views.py +55 -0
  17. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/src/lab_kit/write.py +99 -6
  18. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/tests/test_held.py +12 -0
  19. lab_kit_cli-1.4.0/tests/test_mission.py +142 -0
  20. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/.github/workflows/ci.yml +0 -0
  21. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/.github/workflows/policy.yml +0 -0
  22. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/.github/workflows/release.yml +0 -0
  23. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/.gitignore +0 -0
  24. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/CLAUDE.md +0 -0
  25. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/CONTRIBUTING.md +0 -0
  26. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/LICENSE +0 -0
  27. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/agents/reviewer.md +0 -0
  28. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/skills/lab-review/SKILL.md +0 -0
  29. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/skills/lab-set-up/SKILL.md +0 -0
  30. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/src/lab_kit/runs.py +0 -0
  31. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/src/lab_kit/site.py +0 -0
  32. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/src/lab_kit/supervise.py +0 -0
  33. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/tests/test_flow.py +0 -0
  34. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/tests/test_integrity.py +0 -0
  35. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/tests/test_needs.py +0 -0
  36. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/tests/test_order.py +0 -0
  37. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/tests/test_parked.py +0 -0
  38. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/tests/test_refusals.py +0 -0
  39. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/tests/test_site.py +0 -0
  40. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/tests/test_vocabulary.py +0 -0
  41. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/tests/test_wording.py +0 -0
  42. {lab_kit_cli-1.3.0 → lab_kit_cli-1.4.0}/tools/import_run.py +0 -0
@@ -7,7 +7,7 @@ This file is the only copy of the operating rules for this checkout. `CLAUDE.md`
7
7
  - `README.md`: what lab-kit is.
8
8
  - `docs/model.md`: the contract. When code, a skill or the method disagrees with it, it wins.
9
9
  - `method/METHOD.md`: the rules every lab keeps.
10
- - `skills/`: lab-set-up, lab-work, lab-review, lab-talk. `agents/`: the reviewer.
10
+ - `skills/`: lab-set-up, lab-work, lab-review, lab-talk, lab-mission. `agents/`: the reviewer.
11
11
  - `src/lab_kit/`: the `lab` command. `record.py` reads a lab and works out every state, `views.py` shows it to the agent, `site.py` draws it for the operator inside folio, `write.py` and `runs.py` change it, `checks.py` checks it.
12
12
 
13
13
  ## The gate
@@ -25,10 +25,15 @@ The tests build a small lab with the command itself and take it from a question
25
25
  - A command validates before it writes, and says what it wrote. No command writes a computed view into a lab.
26
26
  - Never `git add -A`. Add the files you touched.
27
27
 
28
+ ## Content and gate
29
+
30
+ **Gate:** `python -m pytest -q`.
31
+
28
32
  <!-- ops:lanes:start (generated from the owner's central rules; change them there, not here) -->
29
33
  ## How changes reach main
30
34
 
31
- `main` is the only source of truth and is always clean: every commit on it passes the gate below.
35
+ `main` is the only source of truth and is always clean: every commit on it passes the gate that
36
+ this file's own "Content and gate" section names.
32
37
  Every change goes through a pull request; `main` accepts nothing else.
33
38
 
34
39
  1. Branch from the latest `origin/main` in a separate worktree, named after the task, for example
@@ -37,8 +42,7 @@ Every change goes through a pull request; `main` accepts nothing else.
37
42
  3. When the work is done and the gate passes, squash-merge it with a clear title and description,
38
43
  then delete the branch and the worktree.
39
44
 
40
- **Gate:** `python -m pytest -q`.
41
- Run it before every push; CI also runs it on every pull request.
45
+ Run the gate before every push; CI also runs it on every pull request.
42
46
 
43
47
  **Authorship.** Every commit is authored with the repository owner's git identity. No co-author
44
48
  line, tool or agent name, "generated with" footer or session link appears in a commit message, a
@@ -1,5 +1,31 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.4.0
4
+
5
+ Missions: a working note for carrying out a settled decision across many sessions. Before, starting or restarting
6
+ the work on a decision meant pasting a long prompt that copied the decision's steps and the state of the machines,
7
+ and went stale within hours. The method (rule 5), the skills `lab-work` and `lab-talk` changed and `lab-mission` is new: run `lab init`
8
+ in a lab after upgrading, or `lab check` reports that they differ from the installed kit.
9
+
10
+ - **A mission** is `missions/M<n>-<name>.md`: a title, the decision it carries (`carries:`), what it is for, its
11
+ Rules (what holds for this mission only) and a Log that only grows. It copies nothing the record holds: not the
12
+ steps, the order, the amounts, or which machine is free.
13
+ - **`lab mission`**: `new "<title>" --carries <decision>` saves one as next; `launch [<id>]` makes one current
14
+ (with no id, the one saved last), and refuses while its decision is open; `log [<id>] "<what>"` adds a line;
15
+ `close [<id>] "<what it did>"` writes one `agent` line about the decision into `log.md` and removes the file.
16
+ Several missions may be current at once. `lab mission <id>` shows one with the steps its decision orders and
17
+ where each stands, and the other current missions. `lab now` names every mission.
18
+ - **`lab check`** checks a mission's form and that it carries a decision, and that a current one's decision is
19
+ settled. A mission is not part of the record: it is not held against history and the site does not draw it.
20
+
21
+ ## 1.3.1
22
+
23
+ - **A log line's end spaces are not part of it.** `lab log` wrote a line ending in `| ` when the so what was
24
+ empty, which a lab's own whitespace check may refuse, while `lab check` refused the line once the space was
25
+ removed, as a committed line changed. `lab log` now ends a line with no space, and `lab check` compares the
26
+ committed lines of `log.md` with the spaces at their ends left out. Other files of the record are compared as
27
+ they were.
28
+
3
29
  ## 1.3.0
4
30
 
5
31
  A new page style, and a lock that holds what a plan demands rather than its words. Before, every page of a card
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.3.0
3
+ Version: 1.4.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
@@ -40,6 +40,7 @@ Goal what the lab wants to be able to say
40
40
  Run one try at producing what the experiment demands; the first that finishes counts
41
41
  Result one number from that run, with the command that prints it again
42
42
  Decision something discussed with the operator: what was seen, the options, what was decided and why
43
+ Mission how a settled decision is being carried out: its rules, and a log a later session resumes from
43
44
  ```
44
45
 
45
46
  Every id spells the path: `G1.Q2.3`. Cards are small and written for the operator. Nothing computed is
@@ -63,7 +64,7 @@ uv tool install lab-kit-cli
63
64
  lab init
64
65
  ```
65
66
 
66
- Then ask your agent to follow `.agents/skills/lab-set-up/SKILL.md`. `lab --help` lists the fifteen
67
+ Then ask your agent to follow `.agents/skills/lab-set-up/SKILL.md`. `lab --help` lists the sixteen
67
68
  commands.
68
69
 
69
70
  The command needs Python 3.10 or later and nothing of folio. The site does: install `lab-kit-cli[site]`
@@ -74,4 +75,4 @@ where folio serves the lab, which brings `folio-kb` 0.5.0 or later, and list `la
74
75
 
75
76
  - [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.
76
77
  - [method/METHOD.md](https://github.com/pierg/lab-kit/blob/main/method/METHOD.md): the seven rules every lab keeps.
77
- - [skills/](https://github.com/pierg/lab-kit/blob/main/skills/): lab-set-up, lab-work, lab-review and lab-talk. [agents/](https://github.com/pierg/lab-kit/blob/main/agents/): the reviewer.
78
+ - [skills/](https://github.com/pierg/lab-kit/blob/main/skills/): lab-set-up, lab-work, lab-review, lab-talk and lab-mission. [agents/](https://github.com/pierg/lab-kit/blob/main/agents/): the reviewer.
@@ -22,6 +22,7 @@ Goal what the lab wants to be able to say
22
22
  Run one try at producing what the experiment demands; the first that finishes counts
23
23
  Result one number from that run, with the command that prints it again
24
24
  Decision something discussed with the operator: what was seen, the options, what was decided and why
25
+ Mission how a settled decision is being carried out: its rules, and a log a later session resumes from
25
26
  ```
26
27
 
27
28
  Every id spells the path: `G1.Q2.3`. Cards are small and written for the operator. Nothing computed is
@@ -45,7 +46,7 @@ uv tool install lab-kit-cli
45
46
  lab init
46
47
  ```
47
48
 
48
- Then ask your agent to follow `.agents/skills/lab-set-up/SKILL.md`. `lab --help` lists the fifteen
49
+ Then ask your agent to follow `.agents/skills/lab-set-up/SKILL.md`. `lab --help` lists the sixteen
49
50
  commands.
50
51
 
51
52
  The command needs Python 3.10 or later and nothing of folio. The site does: install `lab-kit-cli[site]`
@@ -56,4 +57,4 @@ where folio serves the lab, which brings `folio-kb` 0.5.0 or later, and list `la
56
57
 
57
58
  - [docs/model.md](docs/model.md): the contract. What you read, how a number becomes a result, who decides, the commands, the files.
58
59
  - [method/METHOD.md](method/METHOD.md): the seven rules every lab keeps.
59
- - [skills/](skills/): lab-set-up, lab-work, lab-review and lab-talk. [agents/](agents/): the reviewer.
60
+ - [skills/](skills/): lab-set-up, lab-work, lab-review, lab-talk and lab-mission. [agents/](agents/): the reviewer.
@@ -320,8 +320,39 @@ that resource, under `about:`.
320
320
  stopped and the command says so. `lab runs lost` records a run that started and whose folder is
321
321
  gone for good.
322
322
  - **Once:** `lab init`. Run again, it restores the method, the skills and the reviewer role.
323
-
324
- That is fifteen commands. `lab --help` lists them the same way.
323
+ - **To carry out a decision:** `lab mission` (below).
324
+
325
+ That is sixteen commands. `lab --help` lists them the same way.
326
+
327
+ **A mission.** A settled decision says what is done and why: the questions, the order, the resources. Carrying
328
+ it out can take many sessions, each starting sessions or runs of its own and watching them, and a session that
329
+ starts later has to know where the work stands. A mission is that working note. It says which settled decision it
330
+ carries out (`carries:`), what it is for, the rules of running it that hold for this mission only (how many
331
+ machines at once, what each session is given), and a log of what was started, what ended and what was reviewed.
332
+ It copies nothing the decision or the record holds: not the steps, the order or the amounts, and nothing `lab now`
333
+ works out, such as which runs are going or which machine is free.
334
+
335
+ Each mission is a file, `missions/M<n>-<slug>.md`, numbered as decisions are. `lab mission new` gives the next
336
+ number after every mission in `missions/` and every one whose close `log.md` records; a file removed by hand,
337
+ without `lab mission close`, leaves no trace, and its number may be given again. A mission is **next** from when it is saved, and **current** once
338
+ its log says it was launched. Several may be current at once, each carrying its own decision or its own part of one;
339
+ they share the lab's resources, so each one's rules say what it takes, and a session reads the other current
340
+ missions before it takes a machine.
341
+
342
+ - `lab mission new "<title>" --carries <decision>` saves a mission, as next.
343
+ - `lab mission launch [<mission>]` makes one current: the one named, or with no id the one saved last. It refuses
344
+ while the decision it carries is open, and while the mission does not say what it is for.
345
+ - `lab mission log [<mission>] "<what happened>"` adds a line to a current mission's log. Lines are only added.
346
+ - `lab mission close [<mission>] "<what it did, or why it stopped>"` ends a current mission: it writes one `agent`
347
+ line about the decision it carried into `log.md`, `Mission closed: M<n> <title>`, and removes the file. Git
348
+ keeps it.
349
+ - `lab mission` lists every mission in a line; `lab mission <mission>` shows one whole, with the steps its decision
350
+ orders and where each stands now, and the other current missions.
351
+
352
+ `log` and `close` may leave out the mission while only one is current, and refuse to guess when several are.
353
+ `lab now` names every mission under **Right now**. A mission is not part of the record: `lab check` checks its
354
+ form (section 9) and that it carries a decision, and does not hold it against history; the site does not draw
355
+ it; its log is not the lab's log. The lab-mission skill says what to do on each step.
325
356
 
326
357
  The log is one file. Every line carries its time. A line is one of five kinds: a decision was
327
358
  recorded, the agent decided, a result, something is stuck, and what the agent is starting on now.
@@ -332,8 +363,9 @@ since when), and the time of the last recorded activity. A `doing` line stands u
332
363
  about the same card, or the card being finished, ends it. When there is none, the page says that
333
364
  nobody is on anything and names the next step. Nothing is inferred from a session being open.
334
365
 
335
- Four skills: `lab-set-up`, `lab-work`, `lab-review`, and `lab-talk` (tell you where things stand, bring
336
- a decision to you, record what was decided). One role: the reviewer.
366
+ Five skills: `lab-set-up`, `lab-work`, `lab-review`, `lab-talk` (tell you where things stand, bring
367
+ a decision to you, record what was decided), and `lab-mission` (save, launch, resume and close a mission). One
368
+ role: the reviewer.
337
369
 
338
370
  Seven rules:
339
371
 
@@ -372,6 +404,7 @@ written, and only one of them writes at a time.
372
404
  ```
373
405
  lab.toml AGENTS.md GLOSSARY.md resources.toml log.md
374
406
  decisions/D1-<slug>.md what was discussed and decided
407
+ missions/M1-<slug>.md a mission: how a settled decision is being carried out, until it is closed
375
408
  goals/G1-<slug>/
376
409
  goal.md
377
410
  Q1-<slug>/
@@ -475,7 +508,7 @@ The pages are written for a reader, and the agent's detail stays in the files an
475
508
  | Predictions with confidence, decision rules, score sheet, limits | Confirmed-if and refuted-if lines, each testing one result and saying what it is for; what each outcome would mean; two or three limits; the outcome is worked out |
476
509
  | A protocol document of several thousand words | The card for the reader, and `plan/` (the configuration and the code) for the reviewer |
477
510
  | An outcome written by hand on an experiment | Worked out from its lines and its results |
478
- | Missions approved one by one, and a review memo before a change of direction | A decision: something discussed with you, with options and a recommendation, closed by what was decided and why |
511
+ | Missions approved one by one, and a review memo before a change of direction | A decision: something discussed with you, with options and a recommendation, closed by what was decided and why. A mission (1.4.0) approves nothing: it carries out a settled decision |
479
512
  | Two audits per experiment | One review; a second only before a run that uses a metered resource |
480
513
  | Budgets, allowance per question, grant history, ledger | One resources file for the lab, an optional override per experiment; each run records what it used |
481
514
  | Local rules about machines and keys in `AGENTS.md` | The rules of each resource, in the resources file |
@@ -485,7 +518,7 @@ The pages are written for a reader, and the agent's detail stays in the files an
485
518
  | `rests_on` lists and number matching | A card names the result instead of typing the number |
486
519
  | A log per goal and per question, ten kinds of line | One log, five kinds of line |
487
520
  | Everything under a question is an experiment | Three kinds of step: an experiment (bars set in advance), a build, and a reading (a look at what exists, which suggests and never confirms) |
488
- | Sixteen rules, six skills, twenty-one commands | Seven rules, four skills, fifteen commands |
521
+ | Sixteen rules, six skills, twenty-one commands | Seven rules, five skills, sixteen commands |
489
522
  | Asking the agent in chat whether it is working | The front page says what is running, what the agent is on and since when, and when the record last moved |
490
523
  | `lab.yaml`, and the record kept as folio documents: questions, claims, results, protocols, a journal | `lab.toml`, and cards in `goals/` and `decisions/`. folio draws the site from them through `lab_kit.site` and stores no page |
491
524
  | folio as a requirement of the command | The command needs no folio; only the site does |
@@ -698,6 +731,37 @@ anything else is refused when the run is sealed and reported by `lab check`. Its
698
731
  in UTC. The file holds no other heading, and a line no other `|`. The kinds are `decision`, `agent`, `result`, `stuck` and `doing`. `lab decide` writes the
699
732
  `decision` lines, each with the opening of what was decided. A `doing` line holds what the agent is
700
733
  starting on and why now. A line written before the kit kept the time has none.
734
+ A line is about a goal, a question or a step, and a `decision` line about its decision. The one other line
735
+ about a decision is the `agent` line `lab mission close` writes when a mission that carried it ends.
736
+ `lab log` ends a line with no space, even when the so what is empty. Spaces at the end of a log line
737
+ are not part of it: `lab check` compares the committed lines of `log.md` with those spaces left out,
738
+ so removing or adding them changes no committed line.
739
+
740
+ **A mission**, `missions/M<n>-<slug>.md`, is front matter, a description, then two slots:
741
+
742
+ ```
743
+ ---
744
+ title: "The first wave"
745
+ carries: D4
746
+ ---
747
+
748
+ What the mission is for, in a sentence or two (80 words).
749
+
750
+ ## Rules
751
+
752
+ - At most four machines awake at once.
753
+
754
+ ## Log
755
+
756
+ - 2026-11-15 09:12 | saved, carrying D4
757
+ - 2026-11-15 09:40 | launched
758
+ ```
759
+
760
+ The front matter holds `title:` and `carries:` (a decision) and nothing else. Rules is a list, each rule a line
761
+ `- <rule>`, possibly empty (200 words). Log is the last slot, and each line is `- <date> <time> | <what happened>` in UTC, holding no other
762
+ `|`. No other file sits in `missions/`. A mission whose log holds the line `launched` is current. `lab check`
763
+ reports a mission that breaks any of this, one whose `carries:` is not a decision, and a current mission whose
764
+ decision is still open.
701
765
 
702
766
  **Worked-out states.** A question is under discussion while the decision it came from is open, then
703
767
  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
@@ -30,7 +30,8 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
30
30
  goals and the questions. Resources are what `resources.toml` lists and how much. For those two,
31
31
  open a decision that says what was seen, the options and what you recommend, and work on what it
32
32
  does not hold. What a decision settled needs no further yes. Everything else is yours: decide,
33
- record it, go on. Never ask the operator to check your work or to run a command. *Held by
33
+ record it, go on. A mission (`missions/`) carries out what a settled decision settled across sessions, and approves
34
+ nothing more; its log only grows. Never ask the operator to check your work or to run a command. *Held by
34
35
  `lab new`, `lab lock` and `lab run`; otherwise judged.*
35
36
  6. **Record what was decided and why, in the lab's words.** A decision is written out of a conversation
36
37
  with the operator, and you show them the text as recorded. Their messages are not copied into the
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  dynamic = ["readme"]
7
7
  name = "lab-kit-cli"
8
- version = "1.3.0"
8
+ version = "1.4.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" }]
@@ -0,0 +1,96 @@
1
+ ---
2
+ name: lab-mission
3
+ description: >-
4
+ Save, launch, resume and close a mission: the working note for carrying out a settled decision
5
+ across many sessions. Use when the operator says "save it as a mission", "save it as a new
6
+ mission", "launch the mission", "launch the latest mission", "resume the mission", "resume M3",
7
+ "how is the mission going", "close the mission", or when `lab now` lists a current mission and
8
+ you are the session that runs it.
9
+ ---
10
+
11
+ # lab-mission
12
+
13
+ A decision says what the lab does and why: the questions, the order of the work, the resources. A
14
+ mission says how that is being carried out right now: which decision it carries, the rules of
15
+ running it that hold for this mission only, and a log of what has happened. It is the note a
16
+ session reads to pick the work up where the last one stopped, so the operator never has to paste
17
+ a long prompt to start or restart the work.
18
+
19
+ A mission is a file, `missions/M<n>-<name>.md`. It is **next** from when it is saved, and
20
+ **current** once it is launched. Several may be current at once. `lab mission` lists them, and
21
+ `lab mission <id>` shows one whole: what it is for, its rules, the steps its decision orders with
22
+ where each stands now, the other current missions, and its log.
23
+
24
+ ## What a mission holds, and what it never holds
25
+
26
+ It holds:
27
+
28
+ - `carries:`, the settled decision it carries out;
29
+ - one or two sentences on what it is for;
30
+ - **Rules**: only what holds for this mission and is not already a rule of the lab, such as how
31
+ many machines it may take at once and which ones, how many sessions may run side by side, or
32
+ what each session is given to read first;
33
+ - **Log**: one line per event, only added.
34
+
35
+ It never copies what the record already holds: not the steps, not their order, not the amounts of
36
+ any resource, not a result. And it never holds what is true only for a moment, such as which run
37
+ is going or which machine is free: `lab now`, `lab runs` and the machines themselves say that when
38
+ it is needed. A rule that holds for every mission belongs in the lab's `AGENTS.md`, not here.
39
+
40
+ ## Save: "save it as a mission"
41
+
42
+ After a discussion with the operator has settled a decision (the lab-talk skill records it):
43
+
44
+ 1. `lab mission new "<title>" --carries <decision>`. The title is a short name, such as "The
45
+ two waves of D10".
46
+ 2. Write the description under the front matter: what this mission is for, in the operator's
47
+ terms. Write **Rules** from what you agreed about how to run it, and nothing else.
48
+ 3. Read it back to the operator as written, then commit the file.
49
+
50
+ A mission may carry a decision that is still open, while you finish discussing it; it cannot be
51
+ launched until that decision is settled. One decision may be carried by two missions when the
52
+ operator wants its parts run separately, such as one wave each.
53
+
54
+ ## Launch: "launch the mission", "launch the latest mission"
55
+
56
+ 1. `lab mission launch` launches the mission saved last; `lab mission launch <id>` a given one.
57
+ The command refuses while the decision is open or the mission does not say what it is for.
58
+ 2. `lab mission <id>`. Read its rules, then the rules of every other current mission it lists:
59
+ they share the lab's resources, so never take a machine or a slot another current mission
60
+ holds. When two missions' rules would collide, bring that to the operator before you start.
61
+ 3. Start the work: for each step listed as yours, in the order shown, that the rules leave room
62
+ for, start a session of its own (in the way the lab's `AGENTS.md` says sessions and runs are
63
+ started) and give it the step's id and the lab-work skill. Each session follows lab-work as
64
+ usual: it logs `doing`, plans, locks, runs, gets its review, and records.
65
+ 4. Log each start: `lab mission log <id> "started G1.Q2.3 in its own session"`. Commit the
66
+ mission file each time you add lines.
67
+ 5. Watch the sessions. When one ends a step, or is stuck, log it in the mission, and start the
68
+ next step the rules leave room for.
69
+
70
+ ## Resume: "resume the mission", "resume M3", "how is the mission going"
71
+
72
+ 1. `lab mission` to find it; with several current, take the one the operator named, or ask.
73
+ 2. `lab mission <id>`, and read its log against what it lists as the steps and where each stands.
74
+ The record is the truth: a step the log says was started and the record shows as done is done;
75
+ one started and showing no new log line in the lab, no live session and no running run has
76
+ stalled.
77
+ 3. Log what you found (`lab mission log <id> "resumed: G1.Q2.3 had stalled, restarted"`), restart
78
+ what stalled, and carry on from step 3 of Launch.
79
+
80
+ When asked how it is going, answer from `lab mission <id>` and `lab now`, as lab-talk says.
81
+
82
+ ## Close: when every step is finished, or the operator stops it
83
+
84
+ 1. Check `lab mission <id>`: every step it lists is finished, or the operator said to stop.
85
+ 2. `lab mission close <id> "<what it did, or why it stopped>"`. This writes one line in the lab's
86
+ `log.md` about the decision, and removes the mission's file; git keeps it.
87
+ 3. Commit, and tell the operator in a sentence what was carried out. If another mission is next,
88
+ say so; it is launched when they say to.
89
+
90
+ ## Rules
91
+
92
+ - A mission approves nothing. It carries out what a settled decision already settled. Direction
93
+ and resources still come out of a decision with the operator.
94
+ - Never edit or remove a line of a mission's log; add a new one.
95
+ - Keep it thin. If you are about to write a list of steps, an amount or a result into a mission,
96
+ it belongs on a card or in the decision instead.
@@ -23,6 +23,7 @@ from the record, shortest first. A decision is a discussion, not a request for a
23
23
  | why are we doing this at all | `lab show <goal>` |
24
24
  | what is this (an id or a pasted path) | `lab show <id or path>` |
25
25
  | what does a word mean | `lab define <term>` |
26
+ | how is the mission going, what is running for it | `lab mission <id>` (the lab-mission skill) |
26
27
 
27
28
  - The answer first, in one or two sentences, then what it rests on: the result, by its label and value.
28
29
  - Plain words, one idea a sentence. No id without its title. A glossary term is used as the glossary defines it.
@@ -21,6 +21,10 @@ When a decision has set the order of the work, **Yours next** is already in that
21
21
  decision set it; follow it, and bring a change of order to the operator rather than skipping ahead.
22
22
  `lab show <id>` before you touch anything.
23
23
 
24
+ When `lab now` lists a current mission and you were started to run it, or the operator asks to save,
25
+ launch or resume one, follow the lab-mission skill: it starts sessions on the steps, and each of them
26
+ works as this skill says.
27
+
24
28
  Then say what you are on, before the first edit: `lab log <id> doing "<what you are starting on>"
25
29
  "<why now>"`. Do it again each time you move to another card. This line is the top of the operator's
26
30
  front page: it is how they know the lab is alive without asking you. It ends by itself when you log a
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.3.0"
2
+ __version__ = "1.4.0"
@@ -1,7 +1,7 @@
1
1
  """`lab check`: what can be held mechanically. Whether the record is honest is the review's job."""
2
2
  from __future__ import annotations
3
3
 
4
- import os, re
4
+ import glob, os, re
5
5
 
6
6
  from . import history, record as R, runs as runs_, write
7
7
 
@@ -299,8 +299,48 @@ def run(lab, rederive=True):
299
299
  kind = nodes.get(l["about"], {}).get("type")
300
300
  if l["kind"] == "doing" and not l["so"]:
301
301
  bad("log", where, "a `doing` line says why now, after what the agent is starting on")
302
- if kind is None or (kind == "decision") != (l["kind"] == "decision"):
303
- bad("log", where, f"is about {l['about']!r}: a decision line is about its decision, any other about a goal, a question, an experiment, a build or a reading")
302
+ closes = l["kind"] == "agent" and kind == "decision" and l["what"].startswith("Mission closed: ") # written by `lab mission close`
303
+ if kind is None or ((kind == "decision") != (l["kind"] == "decision") and not closes):
304
+ bad("log", where, f"is about {l['about']!r}: a decision line is about its decision, as is the line that closes a mission, any other about a goal, a question, an experiment, a build or a reading")
305
+
306
+ # missions: working notes, checked for their form and for the decision each carries; never against history
307
+ for m in lab.missions:
308
+ where = m["path"]
309
+ for b in m["bad"]:
310
+ bad("missions", where, b)
311
+ if m["bad"]:
312
+ continue
313
+ for key in sorted({str(k) for k in m["fm"]} - {"title", "carries"}):
314
+ bad("missions", where, f"`{key}:` is not something a mission holds: only `title:` and `carries:`")
315
+ if not m["title"]:
316
+ bad("missions", where, "has no title")
317
+ d = nodes.get(m["carries"])
318
+ if not d or d["type"] != "decision":
319
+ bad("missions", where, f"`carries:` names the decision it carries out; {m['carries'] or 'nothing'!r} is not one")
320
+ elif m["state"] == "current" and d["state"] != "decided":
321
+ bad("missions", where, f"is current and carries {d['id']}, which is still open: a mission carries out a settled decision")
322
+ words = len(m["description"].split())
323
+ if not words:
324
+ bad("missions", where, "has no description: a sentence or two, under the front matter, on what it is for")
325
+ elif words > R.MISSION_BUDGET["description"]:
326
+ bad("missions", where, f"its description is {words} words, budget {R.MISSION_BUDGET['description']}")
327
+ for slot in ("Rules", "Log"):
328
+ if slot not in m["slots"]:
329
+ bad("missions", where, f"missing slot {slot}")
330
+ if len(m["slots"].get("Rules", "").split()) > R.MISSION_BUDGET["Rules"]:
331
+ bad("missions", where, f"Rules is {len(m['slots']['Rules'].split())} words, budget {R.MISSION_BUDGET['Rules']}")
332
+ if any(r.strip() and not r.startswith(("- ", " ")) for r in m["slots"].get("Rules", "").split("\n")):
333
+ bad("missions", where, "Rules is a list: each rule a line `- <rule>`")
334
+ if set(m["slots"]) - {"Rules", "Log"}:
335
+ bad("missions", where, f"holds the slot {sorted(set(m['slots']) - {'Rules', 'Log'})[0]!r}; a mission has Rules and Log")
336
+ if "Log" in m["slots"] and m["last_slot"] != "Log":
337
+ bad("missions", where, "Log is the last slot: lines are added at the end of the file")
338
+ for l in m["log"]:
339
+ if "bad" in l:
340
+ bad("missions", where, f"the log line {l['bad'][:60]!r} is not `- <date> <time> | <what happened>`")
341
+ for path in sorted(glob.glob(f"{root}/missions/*")):
342
+ if not path.endswith(".md"):
343
+ bad("missions", lab.rel(path), "missions/ holds only the missions, `M<n>-<name>.md`")
304
344
 
305
345
  # resources
306
346
  for name, r in lab.resources.items():
@@ -1,7 +1,7 @@
1
1
  """lab: the one interface to a lab, for the agent and for CI. See docs/model.md, section 5."""
2
2
  from __future__ import annotations
3
3
 
4
- import os, sys
4
+ import os, re, sys
5
5
 
6
6
  from . import __version__, checks, runs, views, write
7
7
  from .record import Lab, amount, find_root
@@ -21,6 +21,12 @@ To write
21
21
  lab log <id> doing "<what you are starting on>" "<why now>"
22
22
  lab log <id> agent|result|stuck "<what happened>" ["<so what>"]
23
23
  lab answer <question> yes|no "<what the answer rests on>"
24
+ To carry out a decision
25
+ lab mission [<mission>] every mission, or one whole: its rules, the steps its decision orders, its log
26
+ lab mission new "<title>" --carries <decision> save a mission; it is next until launched
27
+ lab mission launch [<mission>] make it current; with no id, the one saved last. Several may be current
28
+ lab mission log [<mission>] "<what happened>" a line in a current mission's log
29
+ lab mission close [<mission>] "<what it did, or why it stopped>" one line in log.md, and the file removed
24
30
  For evidence
25
31
  lab lock <experiment>
26
32
  lab run <experiment> [--trial] [--wait] [--changed "<what changed since the last run, and why>"] -- <command>
@@ -54,7 +60,8 @@ def main(argv=None):
54
60
  i = rest.index("--")
55
61
  rest, command = rest[:i], rest[i + 1:]
56
62
  held = None
57
- if cmd in ("new", "log", "decide", "answer", "lock", "review"): # one writer at a time, on the lab as it then is
63
+ looks = (cmd == "mission" and len(rest) <= 1 and (not rest or re.fullmatch(r"M\d+", rest[0]) is not None)) # `lab mission [<id>]` only reads
64
+ if cmd in ("new", "log", "decide", "answer", "lock", "review") or (cmd == "mission" and not looks): # one writer at a time, on the lab as it then is
58
65
  held = runs.exclusive(find_root())
59
66
  held.__enter__()
60
67
  lab = Lab()
@@ -93,6 +100,27 @@ def main(argv=None):
93
100
  else:
94
101
  raise SystemExit(USAGE)
95
102
  print(f"made {ident}: {path}")
103
+ elif cmd == "mission":
104
+ carries = flag("--carries")
105
+ ident = lambda: rest.pop(1) if len(rest) == 3 or (rest[0] == "launch" and len(rest) == 2) else None
106
+ if looks:
107
+ print(views.mission(lab, rest[0] if rest else None))
108
+ elif rest[0] == "new" and len(rest) == 2:
109
+ made, path = write.mission_new(lab, rest[1], carries)
110
+ print(f"saved {made}: {path}. Say what it is for under the front matter, and its rules")
111
+ elif rest[0] == "launch" and len(rest) <= 2:
112
+ made, path = write.mission_launch(lab, ident())
113
+ print(f"launched {made}: {path}")
114
+ elif rest[0] in ("log", "close") and len(rest) == 2 and re.fullmatch(r"M\d+", rest[1]):
115
+ raise SystemExit(f'say what happened after the mission: lab mission {rest[0]} {rest[1]} "<what>"')
116
+ elif rest[0] == "log" and len(rest) in (2, 3):
117
+ m = ident()
118
+ print(f"added to {write.mission_log(lab, m, rest[1])}")
119
+ elif rest[0] == "close" and len(rest) in (2, 3):
120
+ m = ident()
121
+ print(f"closed: {write.mission_close(lab, m, rest[1])}")
122
+ else:
123
+ raise SystemExit(USAGE)
96
124
  elif cmd == "log":
97
125
  if not 3 <= len(rest) <= 4:
98
126
  raise SystemExit(USAGE)
@@ -10,7 +10,8 @@ A file is known by the numbers in its path and not by the words, so a folder ren
10
10
  same place: what was committed under the old name is held under the new one.
11
11
 
12
12
  - A committed `lock.json` is byte for byte its first committed version.
13
- - `log.md`, `reviews.tsv` and `runs.tsv` only grow: no committed line is removed or changed.
13
+ - `log.md`, `reviews.tsv` and `runs.tsv` only grow: no committed line is removed or changed. Spaces at the end of a
14
+ line of `log.md` are not part of it.
14
15
  - A `results.tsv` that a review has passed keeps every committed row. Once a results review that passed is committed
15
16
  together with the rows it read, those rows stay, whatever the card and the file say later. Rows committed while
16
17
  the last passed review was of other rows, such as a draft row added after it, were never reviewed and are not held.
@@ -40,11 +41,11 @@ def committed(root):
40
41
  return git(root, "rev-parse", "--is-inside-work-tree") is not None and git(root, "rev-parse", "HEAD") is not None
41
42
 
42
43
 
43
- def subsequence(old, new):
44
+ def subsequence(old, new, same=lambda a, b: a == b):
44
45
  """The first line of `old` that `new` no longer holds in order, or None."""
45
46
  it = iter(new)
46
47
  for line in old:
47
- if not any(line == x for x in it):
48
+ if not any(same(line, x) for x in it):
48
49
  return line
49
50
  return None
50
51
 
@@ -204,8 +205,9 @@ def check(lab):
204
205
  continue
205
206
  if name == "results.tsv": # rows may change until a review passes them
206
207
  commits = commits[-1:] if mine(commits[-1][1]) in reviewed else []
208
+ same = (lambda a, b: a.rstrip(" ") == b.rstrip(" ")) if name == "log.md" else (lambda a, b: a == b) # a log line's end spaces are not its
207
209
  for c, path in reversed(commits):
208
- lost = subsequence((git(root, "show", f"{c}:./{path}") or "").splitlines(), R.read(os.path.join(root, mine(path))).splitlines())
210
+ lost = subsequence((git(root, "show", f"{c}:./{path}") or "").splitlines(), R.read(os.path.join(root, mine(path))).splitlines(), same)
209
211
  if lost is not None:
210
212
  bad(mine(path), f"a line committed in {c[:8]}{named(path)} is gone or changed: {lost[:70]!r}")
211
213
  break
@@ -27,6 +27,8 @@ OPTIONAL = {("experiment", "So far"), ("decision", "Note")} # slots a card may
27
27
  DECIDED = 150 # the word budget of what a decision says was decided and why, which `lab decide` writes
28
28
  # What a reader who was not there needs under every title. A question's is its motivation, so it gets room.
29
29
  DESCRIPTION = {"goal": 70, "question": 150, "experiment": 80, "build": 60, "reading": 70}
30
+ MISSION_LINE = re.compile(r"^- (\d{4}-\d\d-\d\d) (\d\d:\d\d) \| ([^|]+)$") # a line of a mission's log
31
+ MISSION_BUDGET = {"description": 80, "Rules": 200}
30
32
  STEPS = ("experiment", "build", "reading") # what sits under a question: a locked comparison, something made, a look at what already exists
31
33
  READS = ("", "percent", "points") # how a result's value reads on a page
32
34
  BEFORE = ("Compares", "Arms", "Cases", "Confirmed if", "Refuted if", "Outcomes", "Limits") # what an experiment says before it runs: its plan, which So far, Found and Means are not part of
@@ -321,6 +323,7 @@ class Lab:
321
323
  self.builds = [x for x in self.items if x["type"] == "build"]
322
324
  self.readings = [x for x in self.items if x["type"] == "reading"]
323
325
  self.decisions = self._decisions()
326
+ self.missions = self._missions()
324
327
  for n in self.goals + self.questions + self.items + self.decisions:
325
328
  n["title"], n["description"] = flat(n.get("title") or n["id"]), flat(n.get("description") or "")
326
329
  if n["type"] == "question": # the question in full; a card without `asks:` has it as its title
@@ -635,6 +638,52 @@ class Lab:
635
638
  out.append(d)
636
639
  return out
637
640
 
641
+ def _missions(self):
642
+ """Every mission, by number: `missions/M<n>-<name>.md`. A mission is next until its log says it was launched,
643
+ and current from then on, until it is closed and its file removed. It is a working note, not part of the record:
644
+ `lab check` checks only its form."""
645
+ out = []
646
+ for n, path in self._numbered(f"{self.root}/missions/*.md", r"/M(\d+)-[^/]+\.md$", {}, "M<n>-<name>.md"):
647
+ m = {"id": f"M{n}", "n": n, "path": self.rel(path), "title": "", "carries": "", "fm": {}, "slots": {}, "description": "", "log": [], "bad": [], "last_slot": ""}
648
+ try:
649
+ fm, slots, description = parse(read(path, self.problems, m["path"]))
650
+ if not isinstance(fm, dict):
651
+ raise ValueError("its front matter is not a set of keys")
652
+ except Exception as err: # reported by `lab check`; the views show what could be read
653
+ m["bad"].append(f"cannot be read as a mission: {err}")
654
+ m["state"] = "next"
655
+ out.append(m)
656
+ continue
657
+ body = split(read(path))[1]
658
+ m.update(fm=fm, slots=slots, description=description, title=flat(fm.get("title") or ""), carries=flat(fm.get("carries") or ""))
659
+ m["last_slot"] = (re.findall(r"^## (.+?)\s*$", body, flags=re.M) or [""])[-1]
660
+ for raw in slots.get("Log", "").split("\n"):
661
+ if raw.strip():
662
+ hit = MISSION_LINE.match(raw.rstrip())
663
+ m["log"].append({"day": hit.group(1), "time": hit.group(2), "what": hit.group(3).strip()} if hit else {"bad": raw.strip()})
664
+ m["state"] = "current" if any(l.get("what") == "launched" for l in m["log"]) else "next"
665
+ out.append(m)
666
+ return out
667
+
668
+ def mission(self, ident):
669
+ return next((m for m in self.missions if m["id"] == ident), None)
670
+
671
+ def mission_numbers(self):
672
+ """Every number a mission has had: those still in `missions/`, and those whose close the lab's log records."""
673
+ closed = [int(m.group(1)) for l in self.lines if l["kind"] == "agent" for m in [re.match(r"Mission closed: M(\d+)\b", l["what"])] if m]
674
+ return [m["n"] for m in self.missions] + closed
675
+
676
+ def mission_steps(self, mission):
677
+ """The steps a mission's decision orders, in its order, each with its state: what is left to carry out."""
678
+ d = self.nodes.get(mission["carries"]) if mission else None
679
+ if not d or d["type"] != "decision" or not d["order"]:
680
+ return []
681
+ place = {}
682
+ for i, ident in enumerate(d["order"]):
683
+ place.setdefault(ident, i)
684
+ rank = lambda x: next((place[i] for i in (x["id"], x["question"], x["goal"]) if i in place), None)
685
+ return sorted((x for x in self.pursued() if rank(x) is not None), key=rank)
686
+
638
687
  def _runs(self):
639
688
  out = []
640
689
  for rj in sorted(glob.glob(f"{self.store}/*/run.json") + glob.glob(f"{self.running}/*/run.json"), key=lambda p: os.path.basename(os.path.dirname(p))):
@@ -67,6 +67,7 @@ def _now(lab):
67
67
  out += ["", "Right now, as the operator sees it"]
68
68
  out += [f"- on {d['about']} {lab.nodes[d['about']]['title']} since {d['day']} {d['time']}: {d['what']} Why now: {d['so']}"] if d else ["- no `doing` line is open: the site says nobody is on anything. When you start: lab log <id> doing \"<what>\" \"<why now>\""]
69
69
  out += [f"- last recorded activity: {last.strftime('%Y-%m-%d %H:%M')} UTC"] if last else []
70
+ out += [mission_line(lab, m).replace("- M", "- mission M", 1) for m in lab.missions]
70
71
  waiting = lab.open_decisions()
71
72
  out += ["", "To discuss with the operator"] + (["- nothing"] if not waiting else [])
72
73
  for d in waiting:
@@ -104,6 +105,60 @@ def _now(lab):
104
105
  return "\n".join([o for o in out if o is not None] + ["", "More: lab show <id or path> lab since lab runs lab define <term>"])
105
106
 
106
107
 
108
+ def mission_line(lab, m):
109
+ """One mission in a line: its id, whether it is current, its title, the decision it carries, its last log line."""
110
+ d = lab.nodes.get(m["carries"])
111
+ carries = f"carrying {d['id']} {d['title']}" if d and d["type"] == "decision" else ("cannot be read (`lab check` says why)" if m["bad"] else "carrying no decision (`lab check` says why)")
112
+ last = next((l for l in reversed(m["log"]) if "what" in l), None)
113
+ tail = f"; last: {last['day']} {last['time']} {last['what']}" if last else ""
114
+ return f"- {m['id']} ({m['state']}): {m['title'] or m['path']}, {carries}{tail}"
115
+
116
+
117
+ def mission(lab, ident=None):
118
+ """Every mission in a line each, or one whole: what it is for, its rules, the steps its decision orders, its log."""
119
+ if ident is None:
120
+ lines = [mission_line(lab, m) for m in lab.missions]
121
+ if not lines:
122
+ return 'no mission: save one with lab mission new "<title>" --carries <decision>'
123
+ return "\n".join(lines + ["", "More: lab mission <id>"])
124
+ m = lab.mission(ident)
125
+ if not m:
126
+ return f"no mission {ident}: `lab mission` lists them"
127
+ d = lab.nodes.get(m["carries"])
128
+ out = [f"{m['id']} ({m['state']}): {m['title'] or m['path']} ({m['path']})"]
129
+ out += m["bad"]
130
+ if m["description"]:
131
+ out += [m["description"]]
132
+ if not d or d["type"] != "decision":
133
+ out += ["", f"It carries {m['carries'] or 'nothing'}, which is no decision of the lab."]
134
+ else:
135
+ out += ["", f"It carries {d['id']} {d['title']} ({'decided ' + str(d['decided'].get('date')) if d['decided'] else 'still open: settle it before launching'})"]
136
+ if R.flat(d["slots"].get("Decided", "")):
137
+ out += [f"Decided. {R.flat(d['slots']['Decided'])}"]
138
+ if R.flat(m["slots"].get("Rules", "")):
139
+ out += ["", "Rules of this mission", m["slots"]["Rules"].strip()]
140
+ others = [o for o in lab.missions if o["state"] == "current" and o["id"] != m["id"]]
141
+ if others:
142
+ out += ["", "Also current (read their rules before taking a machine)"] + [mission_line(lab, o) for o in others]
143
+ if d and d["type"] == "decision":
144
+ steps = lab.mission_steps(m)
145
+ if not d["order"]:
146
+ out += ["", f"{d['id']} orders no steps: what it decided says what to carry out."]
147
+ else:
148
+ open_ = [x for x in steps if x["state"] not in ("done", "built", "dropped", "replaced")]
149
+ out += ["", f"Steps {d['id']} orders, first to last, as they stand now ({len(steps) - len(open_)} of {len(steps)} finished)"]
150
+ for x in open_:
151
+ who = "yours" if x["mine"] else "not yours to move yet"
152
+ out += [f"- {x['id']} {x['title']} ({x['type']}, {state(x)}, {who}): {x['next']}"]
153
+ out += [] if open_ else ["- every step is finished: close the mission"]
154
+ out += ["", "Log"] + ([f"- {l['day']} {l['time']} {l['what']}" if "what" in l else f"- (not a log line) {l['bad']}" for l in m["log"]] or ["- nothing yet"])
155
+ if m["state"] == "current":
156
+ out += ["", f'To add a line: lab mission log {m["id"]} "<what happened>" To end it: lab mission close {m["id"]} "<what it did>"']
157
+ else:
158
+ out += ["", f"To launch it: lab mission launch {m['id']}"]
159
+ return R.bare("\n".join(out))
160
+
161
+
107
162
  def tick(l):
108
163
  mark = {True: "holds", False: "does not hold", None: "not known yet"}[l["holds"]]
109
164
  value = f" ({l['row']['name']} = {l['row']['value']})" if l["row"] else ""
@@ -62,7 +62,8 @@ AGENTS = """# {name}
62
62
 
63
63
  Run `lab now` first, then `lab show <id>` for what you work on. The method is `.lab/METHOD.md`. The skills are in
64
64
  `.agents/skills/`: lab-work to move the work, lab-review to check someone else's, lab-talk whenever the operator
65
- asks where things stand or what something is, and whenever there is a decision to bring to them.
65
+ asks where things stand or what something is, and whenever there is a decision to bring to them, and lab-mission
66
+ to save, launch, resume or close a mission (`missions/`), which carries out a settled decision.
66
67
 
67
68
  ## Local rules
68
69
 
@@ -177,13 +178,13 @@ def new(lab, kind, parent, title, replaces=None, origin=None, about=(), because=
177
178
  return ident, path
178
179
 
179
180
 
180
- def log_line(lab, about, kind, what, so="", _by_command=False):
181
+ def log_line(lab, about, kind, what, so="", _by_command=False, _mission=False):
181
182
  """A log line, validated: (what, so) as they will be written. Nothing is written here."""
182
183
  if kind not in R.KINDS:
183
184
  stop(f"kind is one of: {', '.join(k for k in R.KINDS if k != 'decision')}")
184
185
  if kind == "decision" and not _by_command:
185
186
  stop("a decision is recorded with `lab decide`, on its card: what was decided and why")
186
- if about not in lab.nodes or (lab.nodes[about]["type"] == "decision") != (kind == "decision"):
187
+ if about not in lab.nodes or (lab.nodes[about]["type"] == "decision") != (kind == "decision" or _mission):
187
188
  stop(f"no goal, question, experiment, build or reading {about}")
188
189
  what, so = R.flat(what), R.flat(so)
189
190
  if kind == "doing" and not so:
@@ -193,11 +194,11 @@ def log_line(lab, about, kind, what, so="", _by_command=False):
193
194
  return what, so
194
195
 
195
196
 
196
- def log(lab, about, kind, what, so="", _by_command=False):
197
- what, so = log_line(lab, about, kind, what, so, _by_command)
197
+ def log(lab, about, kind, what, so="", _by_command=False, _mission=False):
198
+ what, so = log_line(lab, about, kind, what, so, _by_command, _mission)
198
199
  path = os.path.join(lab.root, "log.md")
199
200
  text = R.read(path) if os.path.exists(path) else ""
200
- line = f"- {clock()} | {about} | {kind} | {what} | {so}"
201
+ line = f"- {clock()} | {about} | {kind} | {what} | {so}".rstrip(" ")
201
202
  head = "" if re.findall(r"^## (\S+)", text, flags=re.M)[-1:] == [today()] else ("\n" if text.strip() else "") + f"## {today()}\n\n"
202
203
  with open(path, "a") as f:
203
204
  f.write(("" if not text or text.endswith("\n") else "\n") + head + line + "\n")
@@ -359,3 +360,95 @@ def rederive(lab, only=None):
359
360
  elif got != str(row["value"]).strip():
360
361
  problems.append(f"results: {row['ref']}: its command prints {got[:40]!r}, the row says {row['value']!r}")
361
362
  return problems, n
363
+
364
+
365
+ # ---------------------------------------------------------------- missions: carrying out a settled decision
366
+
367
+ MISSION = "---\ntitle: {title}\ncarries: {carries}\n---\n\n\n\n## Rules\n\n\n## Log\n\n{line}\n"
368
+
369
+
370
+ def _mission_line(what):
371
+ what = R.flat(what)
372
+ if not what or "|" in what:
373
+ stop("a mission's log line says what happened, and holds no |")
374
+ return f"- {today()} {clock()} | {what}"
375
+
376
+
377
+ def _mission_append(lab, m, line):
378
+ """Add a line at the end of a mission's log, which is its last slot."""
379
+ if m["bad"] or m["last_slot"] != "Log":
380
+ stop(f"{m['path']}: its last slot is not `## Log`, or it cannot be read: fix the file first (`lab check` says how)")
381
+ path = os.path.join(lab.root, m["path"])
382
+ text = R.read(path)
383
+ with open(path, "a") as f:
384
+ f.write(("" if text.endswith("\n") else "\n") + line + "\n")
385
+
386
+
387
+ def pick_mission(lab, ident, state):
388
+ """The mission a command acts on: the one named, or, with no name, the only one in that state."""
389
+ if ident:
390
+ m = lab.mission(ident)
391
+ if not m:
392
+ stop(f"no mission {ident}: `lab mission` lists them")
393
+ if m["state"] != state:
394
+ stop(f"{ident} is {m['state']}, not {state}")
395
+ return m
396
+ mine = [m for m in lab.missions if m["state"] == state]
397
+ if not mine:
398
+ stop(f"there is no {state} mission: `lab mission` lists them")
399
+ if state == "next": # "launch the latest mission": the one saved last
400
+ return mine[-1]
401
+ if len(mine) > 1:
402
+ stop(f"{len(mine)} missions are current ({', '.join(m['id'] for m in mine)}): name the one you mean")
403
+ return mine[0]
404
+
405
+
406
+ def mission_new(lab, title, carries):
407
+ """Save a mission: a title, the settled decision it carries out, and the first line of its log."""
408
+ title = R.flat(title)
409
+ if not title or not slug(title):
410
+ stop("a mission's title is a name, in a few words; its file is named after it")
411
+ if lab.nodes.get(carries, {}).get("type") != "decision":
412
+ stop(f"--carries <decision>: a mission carries out a decision, and {carries or 'nothing'} is not one")
413
+ n = 1 + max(lab.mission_numbers() or [0])
414
+ line = _mission_line(f"saved, carrying {carries}")
415
+ path = f"missions/M{n}-{slug(title)}.md"
416
+ os.makedirs(os.path.join(lab.root, "missions"), exist_ok=True)
417
+ open(os.path.join(lab.root, path), "w").write(MISSION.format(title=json.dumps(title, ensure_ascii=False), carries=carries, line=line))
418
+ return f"M{n}", path
419
+
420
+
421
+ def mission_launch(lab, ident=None):
422
+ """Make a mission current: the one named, or the one saved last. Other missions may be current too."""
423
+ m = pick_mission(lab, ident, "next")
424
+ if m["bad"]:
425
+ stop(f"{m['path']}: {m['bad'][0]}")
426
+ if lab.nodes.get(m["carries"], {}).get("type") != "decision":
427
+ stop(f"{m['path']}: `carries:` names no decision")
428
+ if lab.nodes[m["carries"]]["state"] != "decided":
429
+ stop(f"{m['carries']} is still open: a mission carries out a settled decision. Settle it with the operator first")
430
+ if not m["description"]:
431
+ stop(f"{m['path']}: say what the mission is for, in the paragraph under the front matter")
432
+ _mission_append(lab, m, _mission_line("launched"))
433
+ return m["id"], m["path"]
434
+
435
+
436
+ def mission_log(lab, ident, what):
437
+ m = pick_mission(lab, ident, "current")
438
+ _mission_append(lab, m, _mission_line(what))
439
+ return m["path"]
440
+
441
+
442
+ def mission_close(lab, ident, what):
443
+ """End a current mission: one line in the lab's log about the decision it carried, and its file removed."""
444
+ m = pick_mission(lab, ident, "current")
445
+ if lab.nodes.get(m["carries"], {}).get("type") != "decision":
446
+ stop(f"{m['path']}: `carries:` names no decision; fix it before closing, so the lab's log says what was carried out")
447
+ what = R.flat(what)
448
+ if not what or "|" in what:
449
+ stop("say what the mission did, or why it stopped, with no |")
450
+ title = (m["title"] or "untitled").replace("|", "/")
451
+ line = log_line(lab, m["carries"], "agent", f"Mission closed: {m['id']} {title}", what, _mission=True) # validated before anything is written
452
+ os.remove(os.path.join(lab.root, m["path"]))
453
+ log(lab, m["carries"], "agent", *line, _mission=True)
454
+ return f"log.md, and removed {m['path']} (git keeps it)"
@@ -79,6 +79,18 @@ def test_the_history_that_is_checked_is_the_labs_own_record(tmp_path):
79
79
  broken(f"{x}/{name}", drop, "a line committed in")
80
80
  broken("log.md", lambda full, kept: os.remove(full), "was committed and is gone")
81
81
  broken("log.md", drop, "a line committed in")
82
+ # the spaces at the end of a log line are not part of it: stripping or adding them is no change
83
+ log = f"{root}/log.md"
84
+ kept = open(log).read()
85
+ for spaced in ("\n".join(l + " " for l in kept.split("\n")), kept.replace(" \n", "\n")):
86
+ open(log, "w").write(spaced)
87
+ assert "the record is sound" in lab(root, "check", "--no-rederive"), spaced
88
+ open(log, "w").write(kept.replace("- ", "- ", 1)) # a space inside a line is still a change
89
+ assert "history: log.md: a line committed in" in lab(root, "check", "--no-rederive", ok=False)
90
+ open(log, "w").write(kept)
91
+ lab(root, "log", ident, "agent", "a line with no so what")
92
+ assert open(log).read().endswith("| a line with no so what |\n") # `lab log` ends a line with no space
93
+ open(log, "w").write(kept)
82
94
  broken(os.path.relpath(glob.glob(f"{root}/decisions/D1-*.md")[0], root), lambda full, kept: os.remove(full), "was committed and is gone")
83
95
  assert "the record is sound" in lab(root, "check", "--strict")
84
96
 
@@ -0,0 +1,142 @@
1
+ """Missions: the working note for carrying out a settled decision. Saved as next, launched as current (several at
2
+ once), logged, and closed with one line in the lab's log. Checked for their form, never against history."""
3
+ import glob, os
4
+
5
+ from test_flow import fill, front, lab, open_question
6
+ from test_order import order, three_steps
7
+
8
+
9
+ def mission_file(root, ident):
10
+ return glob.glob(f"{root}/missions/{ident}-*.md")[0]
11
+
12
+
13
+ def saved(root, title, carries, what="Carry out the order it settled, one session per step."):
14
+ out = lab(root, "mission", "new", title, "--carries", carries)
15
+ ident = out.split()[1].rstrip(":")
16
+ path = mission_file(root, ident)
17
+ text = open(path).read().replace("\n---\n\n\n\n", f"\n---\n\n{what}\n\n", 1)
18
+ open(path, "w").write(text)
19
+ return ident, path
20
+
21
+
22
+ def test_a_mission_is_saved_launched_logged_and_closed(tmp_path):
23
+ root = str(tmp_path)
24
+ open_question(root)
25
+ three_steps(root)
26
+ card, d2 = order(root, ["G1.Q2.2", "G1.Q1", "G1.Q2"])
27
+ assert "no mission" in lab(root, "mission")
28
+ # a mission carries a decision; it may be saved while the decision is open, and not launched until it is settled
29
+ assert "is not one" in lab(root, "mission", "new", "Nothing", "--carries", "G1.Q1", ok=False)
30
+ m1, path = saved(root, "The weight first", d2)
31
+ assert m1 == "M1" and path.endswith("missions/M1-the-weight-first.md")
32
+ assert "M1 (next): The weight first" in lab(root, "mission")
33
+ assert "still open" in lab(root, "mission", "launch", ok=False)
34
+ lab(root, "decide", d2, "--with", "Ada", "The weight on heads first, then the fair coin, then the rest of the biased coin.")
35
+ assert "launched M1" in lab(root, "mission", "launch")
36
+ assert "there is no next mission" in lab(root, "mission", "launch", ok=False)
37
+ shown = lab(root, "mission", "M1")
38
+ assert "M1 (current)" in shown and f"It carries {d2}" in shown
39
+ # the steps its decision orders, in that order, as they stand now; nothing about them is copied into the file
40
+ steps = shown.split("Steps", 1)[1]
41
+ assert steps.index("G1.Q2.2") < steps.index("G1.Q1.1") < steps.index("G1.Q2.1")
42
+ assert "G1.Q2.2" not in open(path).read()
43
+ assert "mission M1 (current): The weight first" in lab(root, "now")
44
+ lab(root, "mission", "log", "started G1.Q2.2 in its own session") # the only current mission: no id needed
45
+ assert "| started G1.Q2.2 in its own session" in open(path).read()
46
+ assert "- 2026-01-02 09:30 started G1.Q2.2" in lab(root, "mission", "M1")
47
+ assert "holds no |" in lab(root, "mission", "log", "a | b", ok=False)
48
+ assert "the record is sound" in lab(root, "check", "--no-rederive")
49
+ out = lab(root, "mission", "close", "M1", "The weight on heads is built; the rest moved to the next mission.")
50
+ assert "removed missions/M1-the-weight-first.md" in out and not os.path.exists(path)
51
+ assert f"| {d2} | agent | Mission closed: M1 The weight first | The weight on heads is built" in open(f"{root}/log.md").read()
52
+ assert "the record is sound" in lab(root, "check", "--no-rederive")
53
+ # a number is never given twice, even once its file is gone
54
+ assert saved(root, "The rest", d2)[0] == "M2"
55
+
56
+
57
+ def test_several_missions_may_be_current_and_a_command_never_guesses_between_them(tmp_path):
58
+ root = str(tmp_path)
59
+ open_question(root)
60
+ three_steps(root)
61
+ _, d2 = order(root, ["G1.Q1", "G1.Q2"])
62
+ lab(root, "decide", d2, "--with", "Ada", "The fair coin first, then the biased one.")
63
+ saved(root, "The fair coin", d2)
64
+ saved(root, "The biased coin", d2)
65
+ assert "launched M2" in lab(root, "mission", "launch") # with no id: the one saved last
66
+ assert "launched M1" in lab(root, "mission", "launch", "M1")
67
+ assert "2 missions are current (M1, M2): name the one you mean" in lab(root, "mission", "log", "a line", ok=False)
68
+ lab(root, "mission", "log", "M2", "started G1.Q2.1")
69
+ assert "started G1.Q2.1" in open(mission_file(root, "M2")).read() and "started G1.Q2.1" not in open(mission_file(root, "M1")).read()
70
+ assert "Also current" in lab(root, "mission", "M1") and "M2 (current): The biased coin" in lab(root, "mission", "M1")
71
+ assert "M1 is current, not next" in lab(root, "mission", "launch", "M1", ok=False)
72
+ assert "no mission M9" in lab(root, "mission", "close", "M9", "x", ok=False)
73
+
74
+
75
+ def test_lab_check_holds_a_missions_form(tmp_path):
76
+ root = str(tmp_path)
77
+ open_question(root)
78
+ _, path = saved(root, "A mission", "D1")
79
+ assert "the record is sound" in lab(root, "check", "--no-rederive")
80
+ front(path, carries="D9", status="active")
81
+ open(path, "a").write("not a line\n")
82
+ open(f"{root}/missions/notes.txt", "w").write("x")
83
+ out = lab(root, "check", "--no-rederive", ok=False)
84
+ assert "`status:` is not something a mission holds" in out
85
+ assert "'D9' is not one" in out
86
+ assert "is not `- <date> <time> | <what happened>`" in out
87
+ assert "missions/notes.txt: missions/ holds only the missions" in out
88
+ # a current mission carries a settled decision
89
+ front(path, carries="D2")
90
+ os.remove(f"{root}/missions/notes.txt")
91
+ lab(root, "new", "decision", "Another", "--about", "G1")
92
+ fill(sorted(glob.glob(f"{root}/decisions/D2-*.md"))[0], Seen="Something to discuss.")
93
+ text = open(path).read().replace("status: active\n", "").replace("not a line\n", "- 2026-01-02 09:40 | launched\n")
94
+ open(path, "w").write(text)
95
+ assert "is current and carries D2, which is still open" in lab(root, "check", "--no-rederive", ok=False)
96
+
97
+
98
+ def test_the_site_draws_the_line_that_closes_a_mission(tmp_path):
99
+ import pytest
100
+ pytest.importorskip("folio.views")
101
+ from lab_kit.site import Provider
102
+ root = str(tmp_path)
103
+ open_question(root)
104
+ saved(root, "A mission", "D1")
105
+ lab(root, "mission", "launch")
106
+ lab(root, "mission", "close", "The first question is open and its work has started.")
107
+ site = Provider(root)
108
+ assert "Mission closed: M1 A mission" in site.get("D1").main + site.get("log").main
109
+
110
+
111
+ def test_the_refusals_a_mission_command_holds(tmp_path):
112
+ root = str(tmp_path)
113
+ open_question(root)
114
+ lab(root, "mission", "new", "No purpose yet", "--carries", "D1")
115
+ assert "say what the mission is for" in lab(root, "mission", "launch", ok=False) # a mission says what it is for before it is launched
116
+ path = mission_file(root, "M1")
117
+ text = open(path).read().replace("\n---\n\n\n\n", "\n---\n\nTo start the first question.\n\n", 1)
118
+ open(path, "w").write(text)
119
+ lab(root, "mission", "launch")
120
+ # an id with no message is not taken as the message
121
+ assert 'say what happened after the mission: lab mission close M1 "<what>"' in lab(root, "mission", "close", "M1", ok=False)
122
+ assert "say what happened after the mission" in lab(root, "mission", "log", "M1", ok=False)
123
+ assert os.path.exists(path) and "Mission closed" not in open(f"{root}/log.md").read()
124
+
125
+
126
+ def test_lab_check_holds_a_missions_slots(tmp_path):
127
+ root = str(tmp_path)
128
+ open_question(root)
129
+ _, path = saved(root, "A mission", "D1", what=" ".join(["word"] * 81))
130
+ text = open(path).read().replace("## Rules\n\n", "## Rules\n\nnot a list item\n\n## Notes\n\nextra\n\n", 1)
131
+ open(path, "w").write(text + "\n## After\n\nx\n")
132
+ out = lab(root, "check", "--no-rederive", ok=False)
133
+ assert "its description is 81 words, budget 80" in out
134
+ assert "Rules is a list" in out
135
+ assert "holds the slot 'After'" in out or "holds the slot 'Notes'" in out
136
+ assert "Log is the last slot" in out
137
+ open(path, "w").write("---\ntitle: [unclosed\n---\n\nx\n")
138
+ out = lab(root, "check", "--no-rederive", ok=False)
139
+ assert "cannot be read as a mission" in out
140
+ assert "cannot be read" in lab(root, "mission")
141
+ open(path, "w").write("---\ntitle: Short\ncarries: D1\n---\n\nFor the first question.\n\n## Log\n\n- 2026-01-02 09:30 | saved, carrying D1\n")
142
+ assert "missing slot Rules" in lab(root, "check", "--no-rederive", ok=False)
File without changes
File without changes
File without changes
File without changes