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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/.github/workflows/policy.yml +6 -2
  2. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/AGENTS.md +4 -2
  3. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/CHANGELOG.md +22 -0
  4. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/PKG-INFO +1 -1
  5. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/docs/model.md +20 -7
  6. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/pyproject.toml +1 -1
  7. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/skills/lab-talk/SKILL.md +5 -0
  8. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/skills/lab-work/SKILL.md +6 -1
  9. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/src/lab_kit/__init__.py +1 -1
  10. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/src/lab_kit/checks.py +9 -1
  11. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/src/lab_kit/history.py +4 -4
  12. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/src/lab_kit/record.py +30 -4
  13. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/src/lab_kit/site.py +34 -3
  14. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/src/lab_kit/views.py +12 -1
  15. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/src/lab_kit/write.py +2 -0
  16. lab_kit_cli-1.1.0/tests/test_parked.py +80 -0
  17. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/tests/test_site.py +2 -1
  18. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/.github/workflows/ci.yml +0 -0
  19. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/.github/workflows/release.yml +0 -0
  20. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/.gitignore +0 -0
  21. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/CLAUDE.md +0 -0
  22. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/CONTRIBUTING.md +0 -0
  23. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/LICENSE +0 -0
  24. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/README.md +0 -0
  25. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/agents/reviewer.md +0 -0
  26. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/method/METHOD.md +0 -0
  27. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/skills/lab-review/SKILL.md +0 -0
  28. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/skills/lab-set-up/SKILL.md +0 -0
  29. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/src/lab_kit/cli.py +0 -0
  30. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/src/lab_kit/runs.py +0 -0
  31. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/src/lab_kit/supervise.py +0 -0
  32. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/tests/test_flow.py +0 -0
  33. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/tests/test_held.py +0 -0
  34. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/tests/test_integrity.py +0 -0
  35. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/tests/test_needs.py +0 -0
  36. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/tests/test_refusals.py +0 -0
  37. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/tests/test_vocabulary.py +0 -0
  38. {lab_kit_cli-1.0.3 → lab_kit_cli-1.1.0}/tools/import_run.py +0 -0
@@ -1,10 +1,14 @@
1
1
  name: policy
2
2
 
3
+ # Runs on pull requests only: a push straight to main is checked by the pre-push hook on the
4
+ # machine that pushes (setup-machine), so GitHub spends no minutes on it (decision 0033).
3
5
  on:
4
6
  pull_request:
5
7
  types: [opened, edited, synchronize, reopened]
6
- push:
7
- branches: [main]
8
+
9
+ concurrency:
10
+ group: policy-${{ github.event.pull_request.number }}
11
+ cancel-in-progress: true
8
12
 
9
13
  permissions:
10
14
  contents: read
@@ -37,9 +37,11 @@ Every change goes through a pull request; `main` accepts nothing else.
37
37
  3. When the work is done and the gate passes, squash-merge it with a clear title and description,
38
38
  then delete the branch and the worktree.
39
39
 
40
- **Gate:** `python -m pytest -q`, then `cd examples/monte-carlo-lab && lab-kit check`.
40
+ **Gate:** `python -m pytest -q`.
41
+ Run it before every push; CI also runs it on every pull request.
41
42
 
42
43
  **Authorship.** Every commit is authored with the repository owner's git identity. No co-author
43
44
  line, tool or agent name, "generated with" footer or session link appears in a commit message, a
44
- branch name or a pull request. A required check on every pull request enforces it.
45
+ branch name or a pull request. The pre-push hook enforces it on every push, and a required `policy`
46
+ check on every pull request.
45
47
  <!-- ops:lanes:end -->
@@ -1,5 +1,27 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.1.0
4
+
5
+ A question can be parked: set aside by a decision, not dropped, and brought back only by another. Before, a
6
+ question the lab chose not to pursue now stayed open, with nothing to say it was set aside on purpose, or was
7
+ dropped for good. The skills `lab-work` and `lab-talk` changed: run `lab init` in a lab after upgrading, or
8
+ `lab check` reports that they differ from the installed kit.
9
+
10
+ - A decision card may carry `parks: [<question>]` and `unparks: [<question>]`. Each question named is also
11
+ under `about:`. Once the decision is settled, the question is parked; a later settled decision that lists
12
+ it under `unparks:` brings it back. The last settled decision, by number, that names it has the say.
13
+ - A parked question leaves Now, the rail and the graph. `lab new` refuses a step under it, and `lab lock` and
14
+ `lab run` refuse its experiments, each naming the decision that parked it.
15
+ - `lab now` has a Set aside section: each parked question in one line with the decision that parked it, and a
16
+ count of the dropped questions and the closed goals. The site's front page has the same section, with the
17
+ first sentence of what was decided; a goal's page folds its parked questions; a parked question's page says
18
+ at the top which decision parked it and why; a decision shows what it parks or brings back.
19
+ - Steps under a parked or dropped question, or a goal that is not active, no longer show under "Not yours to
20
+ move yet" or as what the idle front page names next.
21
+ - `lab check` reports a `parks:` or `unparks:` that names something other than a question, a question not
22
+ under `about:`, and a question both parked and brought back by one decision. What a settled decision parks
23
+ or brings back is held against the lab's history, like its `about:`.
24
+
3
25
  ## 1.0.3
4
26
 
5
27
  A word is now defined in one place, `GLOSSARY.md`. Before, the glossary and the goal's Vocabulary
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.0.3
3
+ Version: 1.1.0
4
4
  Summary: A research lab's record, its method, and the command that keeps both.
5
5
  Project-URL: Homepage, https://github.com/pierg/lab-kit
6
6
  Project-URL: Issues, https://github.com/pierg/lab-kit/issues
@@ -10,7 +10,7 @@ A lab is a tree, and the decisions that shaped it.
10
10
  | Thing | What it says | States |
11
11
  | --- | --- | --- |
12
12
  | **Goal** | A short name, what the lab wants to be able to say, and the claim: what we would report if the questions come out as expected, and against whose work. | active, reached, dropped |
13
- | **Question** | A short name, and a yes-or-no question under a goal, written in full: why we ask it, how we would know, what we expect, what would prove us wrong, what we know so far. | under discussion, open, yes, no, dropped |
13
+ | **Question** | A short name, and a yes-or-no question under a goal, written in full: why we ask it, how we would know, what we expect, what would prove us wrong, what we know so far. | under discussion, open, parked, yes, no, dropped |
14
14
  | **Experiment** | One thing tried to answer a question. What it is for. Before the run: what is compared, each arm by name with what it is, the cases it runs on, what would confirm, what would refute. After: what was found, what it means. | planned, running, waiting, done (confirmed, refuted or unclear), review failed, replaced, dropped |
15
15
  | **Build** | One thing an experiment needs that has to be made first: what it is for, how it works in plain words, and how we know it works. | planned, in progress, built, dropped |
16
16
  | **Reading** | One look at what already exists: sealed runs, traces, the benchmark's own definitions. What it looks at; then what was seen and what that suggests. It sets no bar in advance, so it can suggest and never confirm. | planned, in progress, done, dropped |
@@ -237,12 +237,21 @@ the resources it sets need no further yes. Every goal and question names the dec
237
237
  nothing under a question is locked or run while that decision is still open. Nothing else asks for your
238
238
  approval: an experiment added later under a settled question is the agent's to plan and run.
239
239
 
240
+ **Parking a question.** A question can be set aside without being dropped: not now, perhaps later. A settled
241
+ decision parks it by listing it under `parks:`, and lists it under `about:` too. The decision's Decided text says
242
+ why, and what would bring it back. A parked question leaves Now, the rail and the graph, as a dropped one does.
243
+ Nothing under it moves: `lab new` refuses a step under it, and `lab lock` and `lab run` refuse its experiments. It
244
+ comes back only by a later settled decision that lists it under `unparks:`. The last settled decision, by number,
245
+ that parks or brings back a question has the say. An open decision parks nothing yet. Drop a question that will
246
+ never come back, with `dropped: <why>` on its card; park one that may. A goal is closed by `reached: true` or
247
+ `dropped: <why>`, and a dropped goal drops every question under it.
248
+
240
249
  You may also decide something nobody raised: add, change or drop an experiment or a build, reorder the
241
250
  work, stop a run. Say it, and the agent records it as a decision and follows it. Two things hold for
242
251
  you as for the agent: a locked plan is changed by a new experiment that replaces it, and an outcome is
243
252
  worked out from the results, not decided.
244
253
 
245
- **A settled decision stays as it was settled.** Its `decided:`, its `about:` and its Decided text never
254
+ **A settled decision stays as it was settled.** Its `decided:`, its `about:`, its `parks:`, its `unparks:` and its Decided text never
246
255
  change once committed; a change of mind is a new decision. `lab check` holds this against the lab's
247
256
  history. So a decision cannot be made, afterwards, to be about something it never discussed.
248
257
 
@@ -390,8 +399,12 @@ where one exists, and said to be only the flow where none does. The goal's page
390
399
  each role, states the design before the approximation, and lists its vocabulary: the words every card
391
400
  uses the same way, each drawn with the glossary's definition.
392
401
 
393
- **What was dropped** stays in the record: a dropped goal or question keeps its card and its page,
394
- and leaves Now, the rail and the graph.
402
+ **What was set aside** stays in the record: a dropped goal or question, and a parked question, keeps its
403
+ card and its page, and leaves Now, the rail and the graph. Now lists it apart, under Set aside: each parked
404
+ question with the decision that parked it and the first sentence of what was decided, then the dropped
405
+ questions and the closed goals, folded. A goal's page folds its parked and its dropped questions; a parked
406
+ question's page says, at the top, which decision parked it and why. `lab now` lists the parked questions in
407
+ one line each and counts the rest.
395
408
 
396
409
  **A goal's page** holds its claim and its story: one list, oldest first, of what was found, what got
397
410
  stuck, what the agent chose and what was decided with you, each decision with its text. It is the
@@ -445,7 +458,7 @@ and its sealed runs across as what they were.
445
458
  **A card** is front matter, then its description as a paragraph, then `## Slot` sections. It never
446
459
  holds an id, a state or an outcome. Every file of a lab is UTF-8 text; line ends of either kind
447
460
  read the same, and so hash the same where a review is bound to a file. The front matter sits between
448
- the first two lines that are exactly `---`. A key that holds a list (`needs`, `uses`, `see`, `about`, `holds`, `commits`,
461
+ the first two lines that are exactly `---`. A key that holds a list (`needs`, `uses`, `see`, `about`, `holds`, `parks`, `unparks`, `commits`,
449
462
  `tests`) is written as one, `[a, b]`; every other key holds one value.
450
463
 
451
464
  | Card | Front matter | Slots (word budget) |
@@ -455,7 +468,7 @@ the first two lines that are exactly `---`. A key that holds a list (`needs`, `u
455
468
  | `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:`, `dropped: <why>` | description (70), Compares: the comparison in a sentence (80), Arms (260), Cases (100), Confirmed if (150), Refuted if (110), Outcomes (200), Limits (120), Found (180), Means (150) |
456
469
  | `reading.md` | `title:`, `needs:`, `dropped: <why>` | description (70), Looks at: what, and where it is (110), Seen (320), Suggests (150) |
457
470
  | `build.md` | `title:`, `needs:`, `commits:`, `tests:`, `dropped: <why>` | description (60), How it works (200), Works when (80) |
458
- | `D<n>-<slug>.md` | `title:`, `about:` (the goals, questions, experiments or resources it concerns), `date:`, `holds:`; `decided: {date, with}` is written by `lab decide` | Seen (120), Options: a list, one option an item (200), Recommendation (80), Decided (120) |
471
+ | `D<n>-<slug>.md` | `title:`, `about:` (the goals, questions, experiments or resources it concerns), `date:`, `holds:`; `parks:` and `unparks:` (questions, each also under `about:`); `decided: {date, with}` is written by `lab decide` | Seen (120), Options: a list, one option an item (200), Recommendation (80), Decided (120) |
459
472
 
460
473
  Any card may carry `see:`, a list of pages that explain it: pages of the lab's own library, and pages
461
474
  of another library its charter names, written as folio writes them (`pier-folio:/content/readings/...`),
@@ -593,7 +606,7 @@ in UTC. The file holds no other heading, and a line no other `|`. The kinds are
593
606
  starting on and why now. A line written before the kit kept the time has none.
594
607
 
595
608
  **Worked-out states.** A question is under discussion while the decision it came from is open, then
596
- open, then yes or no; a page calls an open question with nothing under it "not started". A build is in
609
+ open, then yes or no; it is parked while the last settled decision that parks or brings it back parks it; a page calls an open question with nothing under it "not started". A build is in
597
610
  progress once the log has a line about it, and built once it names its commits. An experiment whose
598
611
  results review failed shows as review failed until it is replaced or dropped.
599
612
 
@@ -5,7 +5,7 @@ build-backend = "hatchling.build"
5
5
  [project]
6
6
  dynamic = ["readme"]
7
7
  name = "lab-kit-cli"
8
- version = "1.0.3"
8
+ version = "1.1.0"
9
9
  description = "A research lab's record, its method, and the command that keeps both."
10
10
  license = "MIT"
11
11
  authors = [{ name = "Piergiuseppe Mallozzi" }]
@@ -58,6 +58,11 @@ resource's new amount names the decision in `from`.
58
58
  `lab new decision "<what it is about>" --about <id>`, fill **Seen** with what prompted it, then
59
59
  `lab decide` as above, and do it.
60
60
 
61
+ When they set a question aside: "not now, maybe later" parks it, "never" drops it. Ask which, if it is not
62
+ clear. To park, list the question under `parks:` and `about:` on the decision before `lab decide`, and say in
63
+ the Decided text why and what would bring it back. To bring one back, a new decision lists it under
64
+ `unparks:`. To close a goal, put `reached: true` or `dropped: <why>` on its card, out of a decision.
65
+
61
66
  ## Rules
62
67
 
63
68
  - Never copy the operator's messages into the lab. The record says what was decided and why.
@@ -55,9 +55,14 @@ The operator reads every card on the site, usually days later and without you. W
55
55
  ## When to open a decision
56
56
 
57
57
  Open one when a question is answered or an experiment refutes what was expected, when a result
58
- changes what the next question should be, when you want to add, reword or drop a goal or a question,
58
+ changes what the next question should be, when you want to add, reword, park or drop a goal or a question,
59
59
  or when the resources do not cover the settled work. Not for anything else.
60
60
 
61
+ Park a question that may come back, drop one that will not. A decision parks a question by listing it
62
+ under `parks:` and under `about:`; its Decided text says why, and what would bring it back. Nothing under
63
+ a parked question moves until a later decision lists it under `unparks:`. Never start work under a
64
+ parked question, and never take it up because it looks open: it is listed under Set aside in `lab now`.
65
+
61
66
  1. `lab new decision "<what it is about>" --about <the goals, questions or experiments it concerns>`.
62
67
  2. On its card write **Seen** (what was observed, naming results), **Options** (a list of two or
63
68
  three, each item an option with what it costs and what it changes) and **Recommendation**. Put under `holds:` only the
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.0.3"
2
+ __version__ = "1.1.0"
@@ -11,7 +11,7 @@ KEYS = { # what a card's front matter may hold; a state is never among them
11
11
  "experiment": {"title", "needs", "uses", "override", "replaces", "because", "cost", "waiting_on", "dropped", "see"},
12
12
  "build": {"title", "needs", "commits", "tests", "dropped", "see"},
13
13
  "reading": {"title", "needs", "dropped", "see"},
14
- "decision": {"title", "about", "date", "holds", "decided", "see"},
14
+ "decision": {"title", "about", "date", "holds", "parks", "unparks", "decided", "see"},
15
15
  }
16
16
 
17
17
 
@@ -123,6 +123,14 @@ def run(lab, rederive=True):
123
123
  for i in d[key]:
124
124
  if nodes.get(i, {}).get("type") not in ("goal", "question") + R.STEPS and not (key == "about" and i in lab.resources):
125
125
  bad("links", d["path"], f"{key} names {i!r}, which does not exist")
126
+ for key in ("parks", "unparks"): # only a question is parked, and a decision that parks it or brings it back is about it
127
+ for i in d[key]:
128
+ if nodes.get(i, {}).get("type") != "question":
129
+ bad("links", d["path"], f"{key} names {i!r}, which is not a question: only a question is parked")
130
+ elif i not in d["about"]:
131
+ bad("links", d["path"], f"{key} names {i}, which is not under `about:`: a decision that parks a question or brings it back is about it")
132
+ for i in sorted(set(d["parks"]) & set(d["unparks"])):
133
+ bad("links", d["path"], f"both parks and unparks {i}")
126
134
  done = d["decided"]
127
135
  if done and not ({"date", "with"} <= set(done) and R.flat(d["slots"].get("Decided", ""))):
128
136
  bad("cards", d["path"], "a settled decision holds when, with whom, and what was decided and why under Decided")
@@ -14,7 +14,7 @@ same place: what was committed under the old name is held under the new one.
14
14
  - A `results.tsv` that a review has passed keeps every committed row. Once a results review that passed is committed
15
15
  together with the rows it read, those rows stay, whatever the card and the file say later. Rows committed while
16
16
  the last passed review was of other rows, such as a draft row added after it, were never reviewed and are not held.
17
- - A settled decision keeps its `decided:`, its `about:` and its Decided text as first committed.
17
+ - A settled decision keeps its `decided:`, its `about:`, its `parks:`, its `unparks:` and its Decided text as first committed.
18
18
  - A resource, once committed, is never removed. A metered resource's `granted`, `per_run` and `unit` change only together
19
19
  with `from`, which then names another settled decision that lists the resource. Its `other_use` rows only grow.
20
20
  - None of these files is deleted, and none changes its number.
@@ -140,8 +140,8 @@ def decisions(lab, versions=None, now=None):
140
140
  return None
141
141
  if not isinstance(fm, dict) or fm.get("decided") is None:
142
142
  return None
143
- about = fm.get("about")
144
- return str(fm.get("decided")), sorted(str(i) for i in (about if isinstance(about, list) else [about] if about is not None else [])), R.flat(slots.get("Decided", ""))
143
+ ids = lambda v: sorted(str(i) for i in (v if isinstance(v, list) else [v] if v is not None else []))
144
+ return str(fm.get("decided")), ids(fm.get("about")), ids(fm.get("parks")), ids(fm.get("unparks")), R.flat(slots.get("Decided", ""))
145
145
 
146
146
  for where, commits in sorted(versions.items()):
147
147
  if not DECISION.fullmatch(commits[-1][1]):
@@ -154,7 +154,7 @@ def decisions(lab, versions=None, now=None):
154
154
  if was:
155
155
  mine = path if path in now[where] else now[where][0]
156
156
  if settled(R.read(os.path.join(root, mine))) != was:
157
- bad(mine, f"was settled in {c[:8]}" + ("" if mine == path else f", as {path}") + ", and its `decided:`, its `about:` or its Decided text has changed since; a change of mind is a new decision")
157
+ bad(mine, f"was settled in {c[:8]}" + ("" if mine == path else f", as {path}") + ", and what it parks or brings back, its `decided:`, its `about:` or its Decided text has changed since; a change of mind is a new decision")
158
158
  break
159
159
  return problems
160
160
 
@@ -43,7 +43,7 @@ COLUMNS = {"results.tsv": ("name", "label", "value", "reads", "versus", "command
43
43
  HASH = 2 # how a folder is hashed in the locks and runs made now; one without the marker was made with the first way
44
44
  NUMBER = re.compile(r"[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?")
45
45
  LISTS = {"goal": ("see",), "question": ("needs", "see"), "experiment": ("needs", "uses", "see"), "build": ("needs", "commits", "tests", "see"),
46
- "reading": ("needs", "see"), "decision": ("about", "holds", "see")} # the front matter keys that hold a list
46
+ "reading": ("needs", "see"), "decision": ("about", "holds", "parks", "unparks", "see")} # the front matter keys that hold a list
47
47
  TEXTS = ("title", "asks", "from", "replaces", "because", "cost", "waiting_on", "dropped", "answered") # and those that hold one value
48
48
 
49
49
 
@@ -627,7 +627,7 @@ class Lab:
627
627
  out = []
628
628
  for n, path in self._numbered(f"{self.root}/decisions/D*.md", r"/D(\d+)-[^/]+\.md$", {}, "D<n>-<name>.md"):
629
629
  fm, slots = self._card(path, "decision")
630
- d = {"title": f"D{n}", "about": [], "holds": [], "decided": None, "date": "", "see": [], **fm, "id": f"D{n}", "type": "decision", "slots": slots,
630
+ d = {"title": f"D{n}", "about": [], "holds": [], "parks": [], "unparks": [], "decided": None, "date": "", "see": [], **fm, "id": f"D{n}", "type": "decision", "slots": slots,
631
631
  "path": self.rel(path), "dir": self.rel(os.path.dirname(path))}
632
632
  d["state"] = "decided" if d["decided"] else "open"
633
633
  out.append(d)
@@ -679,8 +679,21 @@ class Lab:
679
679
  return next(g for g in self.goals if g["id"] == q["goal"])
680
680
 
681
681
  def live(self, nodes):
682
- """The goals or questions still pursued: what was dropped stays in the record and off the working pages."""
683
- return [n for n in nodes if n["state"] != "dropped"]
682
+ """The goals or questions still pursued: what was dropped or parked stays in the record and off the working pages."""
683
+ return [n for n in nodes if n["state"] not in ("dropped", "parked")]
684
+
685
+ def pursued(self):
686
+ """The steps still pursued: under a question that is neither parked nor dropped, of a goal still active. What was
687
+ set aside waits on a decision, not on the work, and is listed apart."""
688
+ keep = {q["id"] for q in self.live(self.questions) if self.nodes[q["goal"]]["state"] == "active"}
689
+ return [x for x in self.items if x["question"] in keep]
690
+
691
+ def set_aside(self):
692
+ """What was set aside, for the page and the view that list it: parked and dropped questions, and goals that
693
+ were reached or dropped."""
694
+ return {"parked": [q for q in self.questions if q["state"] == "parked"],
695
+ "dropped": [q for q in self.questions if q["state"] == "dropped"],
696
+ "goals": [g for g in self.goals if g["state"] != "active"]}
684
697
 
685
698
  def question_of(self, ident):
686
699
  m = re.match(r"(G\d+\.Q\d+)", ident)
@@ -805,11 +818,22 @@ class Lab:
805
818
  def replaced_by(self, ident):
806
819
  return next((x for x in self.experiments if x.get("replaces") == ident and not x.get("dropped")), None)
807
820
 
821
+ def parked_by(self, ident):
822
+ """The settled decision that parked this question, or None. The last settled decision, by number, that parks or
823
+ unparks it has the say: a question is set aside, and brought back, only by a decision."""
824
+ last = None
825
+ for d in self.decisions:
826
+ if d["state"] == "decided" and (ident in d["parks"] or ident in d["unparks"]):
827
+ last = d
828
+ return last if last and ident in last["parks"] else None
829
+
808
830
  def _question_state(self, q):
809
831
  if q.get("dropped") or self._goal_of(q).get("dropped"):
810
832
  return "dropped"
811
833
  if q.get("answer") in ("yes", "no"):
812
834
  return q["answer"]
835
+ if self.parked_by(q["id"]):
836
+ return "parked"
813
837
  return "open" if self.settled(q) else "under discussion"
814
838
 
815
839
  def _reach(self):
@@ -854,6 +878,8 @@ class Lab:
854
878
  return f"{g['id']} is {g['state']}"
855
879
  if q["state"] == "under discussion":
856
880
  return f"the decision {q.get('from') or 'it comes from'} to be settled"
881
+ if q["state"] == "parked":
882
+ return f"{q['id']} is parked by {self.parked_by(q['id'])['id']}: a decision that unparks it comes first"
857
883
  if q["state"] != "open":
858
884
  return f"{q['id']} is {'answered ' + q['state'] if q['state'] in ('yes', 'no') else q['state']}"
859
885
  for need in x.get("needs") or []:
@@ -13,7 +13,7 @@ GENERIC = {"model", "field", "source", "group", "stop", "case", "score", "port",
13
13
  e = html.escape
14
14
  TONES = {"active": "info", "reached": "ok", "under discussion": "warn", "open": "info", "yes": "ok", "no": "warn", "decided": "ok",
15
15
  "confirmed": "ok", "refuted": "bad", "unclear": "warn", "running": "info", "waiting": "warn", "in progress": "info", "built": "ok",
16
- "review failed": "bad", "finished": "ok", "failed": "bad", "pass": "ok", "fail": "bad", "done": "ok"}
16
+ "review failed": "bad", "finished": "ok", "failed": "bad", "pass": "ok", "fail": "bad", "done": "ok", "parked": "plain"}
17
17
 
18
18
 
19
19
  def nice(day):
@@ -433,6 +433,7 @@ def decision_box(lab, T, d, link=True, title=True):
433
433
  rows = []
434
434
  if done:
435
435
  rows.append((f'Decided {nice(d["decided"].get("date"))}', block(T, d["slots"].get("Decided", ""))))
436
+ rows += [(verb if done else f"Would {verb.lower()}", "<br>".join(named(lab, i) if i in lab.nodes else e(i) for i in d[key])) for key, verb in (("parks", "Parks"), ("unparks", "Brings back")) if d[key]]
436
437
  rows += [(k, block(T, d["slots"][k])) for k in ("Seen", "Options", "Recommendation") if L.flat(d["slots"].get(k, ""))]
437
438
  if not done:
438
439
  held = lab.held_by(d)
@@ -596,7 +597,7 @@ def right_now(lab, T):
596
597
  rows.append(f'<p class="what">{pill("nobody is on it", "warn")} Nothing is running, and no agent has said it is working.</p>'
597
598
  f'<p>The next step is the agent\'s: {named(lab, x["id"])}: {T(you(x["next"]))}.</p>')
598
599
  else:
599
- waits = [x for x in lab.items if x["state"] == "waiting" or (x["state"] == "planned" and x["next"])]
600
+ waits = [x for x in lab.pursued() if x["state"] == "waiting" or (x["state"] == "planned" and x["next"])]
600
601
  rows.append(f'<p class="what">{pill("idle", "plain")} Nothing is running and nothing is the agent\'s to move.</p>'
601
602
  + (f'<p>{named(lab, waits[0]["id"])} waits on {T(you(waits[0]["next"]))}.</p>' if waits else ""))
602
603
  last = lab.last_record()
@@ -644,7 +645,7 @@ def home(lab, T):
644
645
  out.append("<h2>To discuss with you</h2>" + ("".join(talk) or '<p class="muted">Nothing.</p>'))
645
646
  busy = lab.doing()["about"] if lab.doing() else None
646
647
  nxt = [x for x in lab.yours() if x["id"] != busy]
647
- held = [x for x in lab.items if x["state"] == "waiting" or (x["state"] == "planned" and not x["mine"] and x["next"])]
648
+ held = [x for x in lab.pursued() if x["state"] == "waiting" or (x["state"] == "planned" and not x["mine"] and x["next"])]
648
649
  if nxt or held:
649
650
  out.append('<h2>Next</h2><table class="t"><tr><th>What</th><th>Who moves it</th><th>What happens next</th></tr>' + "".join(
650
651
  f'<tr><td>{named(lab, x["id"])}</td><td>{"the agent" if x["mine"] else "waits"}</td><td>{("" if x["mine"] else "on ") + T(you(x["next"]))}</td></tr>' for x in nxt + held) + "</table>")
@@ -652,6 +653,7 @@ def home(lab, T):
652
653
  for g in lab.live(lab.goals):
653
654
  out.append(f'<div class="goalhead">{dot(g)}<a href="/{g["id"]}">{e(g["title"])}</a></div><p class="goalwhy">{T(g["description"])}</p>'
654
655
  + "".join(qcard(lab, T, q) for q in lab.live(g["questions"])))
656
+ out.append(set_aside_html(lab, T))
655
657
  latest = happened(lab.lines)[-5:]
656
658
  out.append('<h2>Latest</h2>' + log_html(lab, T, latest) + '<p style="font:.85rem var(--sans)"><a href="/log">The whole log</a></p>')
657
659
  if lab.resources:
@@ -659,6 +661,29 @@ def home(lab, T):
659
661
  return frame(lab, lab.cfg.get("title", lab.cfg["name"]), "".join(out))
660
662
 
661
663
 
664
+ def parked_line(lab, T, q):
665
+ d = lab.parked_by(q["id"])
666
+ return f'<p>{named(lab, q["id"])}: parked by {named(lab, d["id"])}. {T(L.first_sentence(L.flat(d["slots"].get("Decided", ""))))}</p>'
667
+
668
+
669
+ def set_aside_html(lab, T):
670
+ """What was set aside, apart from the work: each parked question with the decision that parked it, then what was
671
+ dropped and the goals that were closed, folded."""
672
+ aside = lab.set_aside()
673
+ if not any(aside.values()):
674
+ return ""
675
+ out = ["<h2>Set aside</h2>"]
676
+ if aside["parked"]:
677
+ out.append('<p class="muted" style="font:.84rem var(--sans)">Parked by a decision; each comes back only by another.</p>' + "".join(parked_line(lab, T, q) for q in aside["parked"]))
678
+ if aside["dropped"]:
679
+ out.append(f'<details class="old"><summary>Dropped questions ({len(aside["dropped"])})</summary>' + "".join(
680
+ f'<p>{named(lab, q["id"])}: {T(str(q.get("dropped") or lab.nodes[q["goal"]].get("dropped") or ""))}</p>' for q in aside["dropped"]) + "</details>")
681
+ if aside["goals"]:
682
+ out.append(f'<details class="old"><summary>Closed goals ({len(aside["goals"])})</summary>' + "".join(
683
+ f'<p>{named(lab, g["id"])}: {e(label(g))}{". " + T(str(g["dropped"])) if g.get("dropped") else ""}</p>' for g in aside["goals"]) + "</details>")
684
+ return "".join(out)
685
+
686
+
662
687
  def resources_table(lab):
663
688
  per = any(isinstance(r.get("per_run"), (int, float)) for r in lab.resources.values() if isinstance(r, dict)) # the column is there only when a resource sets it
664
689
  out = ['<table class="t"><tr><th>Resource</th><th>Used</th><th>Granted</th>' + ("<th>One run may use</th>" if per else "") + "</tr>"]
@@ -689,6 +714,9 @@ def goal_page(lab, T, g):
689
714
  rows = "".join(f'<tr><td>{e(w["entry"]["term"] if w["entry"] else w["name"])}</td><td>' + (e(w["entry"]["definition"]) + avoid_note(w["entry"]) if w["entry"] else '<span class="muted">not in the glossary</span>') + "</td></tr>" for w in words)
690
715
  body.append('<h2>The words this lab uses</h2><table class="t roles"><tr><th>Word</th><th>What it means here, everywhere</th></tr>' + rows + "</table>")
691
716
  body.append("<h2>Questions</h2>" + "".join(qcard(lab, T, q) for q in lab.live(g["questions"])))
717
+ parked = [q for q in g["questions"] if q["state"] == "parked"]
718
+ if parked:
719
+ body.append(f'<details class="old"><summary>Parked questions ({len(parked)})</summary>' + "".join(parked_line(lab, T, q) for q in parked) + "</details>")
692
720
  gone = [q for q in g["questions"] if q["state"] == "dropped"]
693
721
  if gone:
694
722
  body.append(f'<details class="old"><summary>Dropped questions ({len(gone)})</summary>' + "".join(f'<p>{named(lab, q["id"])}: {T(str(q.get("dropped") or g.get("dropped") or ""))}</p>' for q in gone) + "</details>")
@@ -724,6 +752,9 @@ def question_page(lab, T, q):
724
752
  live = [x for x in q["items"] if x["state"] not in ("replaced", "dropped")]
725
753
  gone = [x for x in q["items"] if x["state"] == "dropped" or (x["state"] == "replaced" and not lab.replaced_by(x["id"]))]
726
754
  body = [f'<h1>{e(q["title"])}</h1>']
755
+ if q["state"] == "parked":
756
+ d = lab.parked_by(q["id"])
757
+ body.append(f'<div class="box"><b>Parked</b> by {named(lab, d["id"])}: nothing under it moves until a decision brings it back. {T(L.flat(d["slots"].get("Decided", "")))}</div>')
727
758
  before = [lab.nodes[i] for i in q["needs"] if i in lab.nodes]
728
759
  if before:
729
760
  body.append('<div class="slots">' + slot("Where we are coming from", "".join(f'<p>{named(lab, n["id"])} ({e(label(n))}).</p>{block(T, n["slots"].get("So far", ""))}' for n in before), "full") + "</div>")
@@ -23,6 +23,9 @@ def decision_text(lab, d):
23
23
  about = ", ".join(f"{i} {lab.nodes[i]['title']}" if i in lab.nodes else f"the resource {i}" for i in d["about"] if i in lab.nodes or i in lab.resources)
24
24
  when = f"decided {d['decided'].get('date')} with {d['decided'].get('with')}" if d["decided"] else "open: to discuss with the operator"
25
25
  out = [f"{d['id']} {d['title']} (raised {d.get('date')}, {when})" + (f"\nAbout: {about}" if about else "")]
26
+ for key, verb in (("parks", "Parks"), ("unparks", "Brings back")):
27
+ if d[key]:
28
+ out += [f"{verb}: " + ", ".join(f"{i} {lab.nodes[i]['title']}" if i in lab.nodes else i for i in d[key])]
26
29
  out += [f"{slot}. {R.flat(d['slots'][slot])}" for slot in ("Seen", "Options", "Recommendation", "Decided") if R.flat(d["slots"].get(slot, ""))]
27
30
  if d["state"] == "open":
28
31
  held = lab.held_by(d)
@@ -69,7 +72,7 @@ def _now(lab):
69
72
  going = [f"- {x['id']} {x['title']}: {r['id']}, started {r['started']}" for x in lab.experiments for r in x["runs"] + x["trials"] if r["state"] == "running" and not r["orphan"]]
70
73
  out += ["" if not waiting else None, "Running"] + (going or ["- nothing"])
71
74
  out += ["", "Yours next"] + ([f"- {x['id']} {x['title']} ({x['type']}): {x['next']}" for x in lab.yours()] or ["- nothing"])
72
- held = [f"- {x['id']} {x['title']}: on {x['next']}" for x in lab.items if x["state"] == "waiting" or (x["state"] == "planned" and not x["mine"])]
75
+ held = [f"- {x['id']} {x['title']}: on {x['next']}" for x in lab.pursued() if x["state"] == "waiting" or (x["state"] == "planned" and not x["mine"])]
73
76
  out += ["", "Not yours to move yet"] + (held or ["- nothing"])
74
77
  out += ["", "Questions"]
75
78
  for q in lab.live(lab.questions):
@@ -78,6 +81,12 @@ def _now(lab):
78
81
  key = x["outcome"] if x["state"] == "done" and x.get("outcome") else x["state"]
79
82
  counts[key] = counts.get(key, 0) + 1
80
83
  out += [f"- {q['id']} ({q['state']}): {q['title']} [{', '.join(f'{n} {k}' for k, n in counts.items()) or 'nothing under it'}]"]
84
+ aside = lab.set_aside()
85
+ if any(aside.values()):
86
+ out += ["", "Set aside"] + [f"- {q['id']} (parked by {lab.parked_by(q['id'])['id']}): {q['title']}" for q in aside["parked"]]
87
+ rest = [f"{len(aside['dropped'])} question{'' if len(aside['dropped']) == 1 else 's'} dropped"] if aside["dropped"] else []
88
+ rest += [f"{len(aside['goals'])} goal{'' if len(aside['goals']) == 1 else 's'} closed ({', '.join(g['id'] + ' ' + g['state'] for g in aside['goals'])})"] if aside["goals"] else []
89
+ out += [f"- {', '.join(rest)}: lab show <id>"] if rest else []
81
90
  if lab.resources:
82
91
  out += ["", "Resources"] + [resource_line(lab, name) for name in lab.resources]
83
92
  stuck = [f"- {r['id']}: {r['unpublished'].splitlines()[0]}" for r in lab.runs if r["unpublished"]]
@@ -133,6 +142,8 @@ def _show(lab, ident):
133
142
  decisions = ["", "Decisions about it"] + [f"- {d['id']} ({d['state']}): {d['title']}" for d in raised] if raised else []
134
143
  if n["type"] == "question":
135
144
  out = [f"{n['id']} ({n['state']}): {n['title']}", f"Asks: {n['asks']}", n["description"]] + came(n) + [""]
145
+ by = lab.parked_by(n["id"]) if n["state"] == "parked" else None
146
+ out += [f"Parked by {by['id']} {by['title']}: nothing under it moves until a decision brings it back (`unparks:`).", ""] if by else []
136
147
  out += [f"{slot}. {lab.fill(R.flat(n['slots'].get(slot, '')))}\n" for slot, _ in R.SLOTS["question"]]
137
148
  out += ["Under it"] + ([f"- {x['id']} {x['type']} ({state(x)}): {x['title']}" + (f". Next: {x['next']}" if x["mine"] else "") for x in n["items"]] or ["- nothing yet"])
138
149
  out += decisions
@@ -138,6 +138,8 @@ def new(lab, kind, parent, title, replaces=None, origin=None, about=(), because=
138
138
  ident, path = f"{p['id']}.Q{n}", f"{p['dir']}/Q{n}-{slug(title)}/question.md"
139
139
  text = CARDS["question"].format(title=quoted, origin=origin, asks=f"asks: {json.dumps(R.flat(asks), ensure_ascii=False)}\n" if R.flat(asks) else "")
140
140
  elif kind in R.STEPS:
141
+ if p["state"] == "parked": # set aside by a decision: work under it starts again only once a decision brings it back
142
+ stop(f"{p['id']} is parked by {lab.parked_by(p['id'])['id']}: a decision that unparks it (`unparks: [{p['id']}]`) comes first")
141
143
  n = 1 + max([int(x["id"].split(".")[-1]) for x in p["items"]] or [0])
142
144
  ident, path = f"{p['id']}.{n}", f"{p['dir']}/{n}-{slug(title)}/{kind}.md"
143
145
  fill = {"title": quoted, "description": "", "extra": "", "Compares": "", "Arms": "- ", "Cases": "", "Confirmed if": "- ", "Refuted if": "- ", "Outcomes": "", "Limits": ""}
@@ -0,0 +1,80 @@
1
+ """A question set aside by a decision: parked, off the working pages, with nothing under it moving until a later
2
+ decision brings it back; and a decision that parks or brings back cannot be edited afterwards."""
3
+ import glob
4
+
5
+ from test_flow import describe, fill, front, git, lab, open_question
6
+
7
+
8
+ def a_second_question(root):
9
+ lab(root, "new", "question", "G1", "Does the error fall on a biased coin?", "--from", "D1")
10
+ q = glob.glob(f"{root}/goals/G1-*/Q2-*/question.md")[0]
11
+ describe(q, "The law for a coin that is not fair, which the sampler can also draw.")
12
+ lab(root, "new", "build", "G1.Q2", "A biased sampler")
13
+ describe(glob.glob(f"{root}/goals/G1-*/Q2-*/1-*/build.md")[0], "The sampler with a weight on heads.")
14
+ return q
15
+
16
+
17
+ def park(root, ident, title, decided, key="parks"):
18
+ out = lab(root, "new", "decision", title, "--about", ident)
19
+ card = sorted(glob.glob(f"{root}/decisions/D*.md"))[-1]
20
+ fill(card, Seen="The fair coin answers what the lab needs first.", Options="(a) Set it aside. (b) Keep it.", Recommendation="(a).")
21
+ front(card, **{key: f"[{ident}]"})
22
+ return card, out.split()[1].rstrip(":")
23
+
24
+
25
+ def test_a_parked_question_leaves_the_work_and_comes_back_only_by_a_decision(tmp_path):
26
+ root = str(tmp_path)
27
+ open_question(root)
28
+ a_second_question(root)
29
+ assert "G1.Q2.1 A biased sampler" in lab(root, "now")
30
+ card, d2 = park(root, "G1.Q2", "Set the biased coin aside", "")
31
+ # an open decision parks nothing yet: the card says what it would park
32
+ assert "(open)" in lab(root, "show", "G1.Q2") and "Parks: G1.Q2" in lab(root, "show", d2)
33
+ lab(root, "decide", d2, "--with", "Ada", "The biased coin is parked: the fair coin answers what the lab needs first. It comes back if the law holds.")
34
+ now = lab(root, "now")
35
+ assert "Set aside" in now and f"G1.Q2 (parked by {d2})" in now and "A biased sampler" not in now.split("Set aside")[0]
36
+ assert f"Parked by {d2}" in lab(root, "show", "G1.Q2")
37
+ refused = lab(root, "new", "reading", "G1.Q2", "What the biased runs said", ok=False)
38
+ assert f"parked by {d2}" in refused and "unparks" in refused and not glob.glob(f"{root}/goals/G1-*/Q2-*/2-*")
39
+ assert "the record is sound" in lab(root, "check", "--no-rederive")
40
+ # a later decision brings it back
41
+ _, d3 = park(root, "G1.Q2", "Bring the biased coin back", "", key="unparks")
42
+ lab(root, "decide", d3, "--with", "Ada", "The law held on the fair coin, so the biased coin comes back.")
43
+ assert "(open)" in lab(root, "show", "G1.Q2") and "Set aside" not in lab(root, "now")
44
+ lab(root, "new", "reading", "G1.Q2", "What the biased runs said")
45
+
46
+
47
+ def test_the_site_shows_what_was_set_aside_apart_from_the_work(tmp_path):
48
+ import pytest
49
+ pytest.importorskip("folio.views")
50
+ from lab_kit.site import Provider
51
+ root = str(tmp_path)
52
+ open_question(root)
53
+ a_second_question(root)
54
+ _, d2 = park(root, "G1.Q2", "Set the biased coin aside", "")
55
+ lab(root, "decide", d2, "--with", "Ada", "The biased coin is parked: the fair coin answers what the lab needs first. It comes back if the law holds.")
56
+ site = Provider(root)
57
+ home = site.get("").main
58
+ assert "Set aside" in home and "parked by" in home and "The biased coin is parked" in home and "A biased sampler" not in home.split("Set aside")[0]
59
+ assert "Parked questions (1)" in site.get("G1").main
60
+ page = site.get("G1.Q2").main
61
+ assert "<b>Parked</b>" in page and "nothing under it moves" in page
62
+ assert "Parks" in site.get(d2).main
63
+ assert not any("biased coin?" in str(r) for r in site.rail())
64
+
65
+
66
+ def test_parking_names_a_question_the_decision_is_about_and_stays_as_settled(tmp_path):
67
+ root = str(tmp_path)
68
+ open_question(root)
69
+ a_second_question(root)
70
+ card, d2 = park(root, "G1.Q2", "Set the biased coin aside", "")
71
+ front(card, parks="[G1.Q2.1, G1.Q1]", unparks="[G1.Q1]")
72
+ out = lab(root, "check", "--no-rederive", ok=False)
73
+ assert "parks names 'G1.Q2.1', which is not a question" in out and "parks names G1.Q1, which is not under `about:`" in out and "both parks and unparks G1.Q1" in out
74
+ front(card, parks="[G1.Q2]", unparks="[]")
75
+ lab(root, "decide", d2, "--with", "Ada", "The biased coin is parked: the fair coin answers what the lab needs first.")
76
+ git(root, "init", "-q")
77
+ git(root, "add", ".")
78
+ git(root, "commit", "-qm", "settled")
79
+ front(card, parks="[]") # what a settled decision parked cannot be taken back by editing it
80
+ assert "and what it parks or brings back, its `decided:`" in lab(root, "check", "--no-rederive", ok=False)
@@ -190,7 +190,8 @@ def test_a_readings_page_says_it_is_exploratory_and_what_was_dropped_leaves_the_
190
190
  assert '<span class="kind">reading</span>' in q and "<ol><li><b>The sampler</b> flips a coin 100 times.</li>" in q and "Fix the seed." in q
191
191
  assert "The words this lab uses" in site.get("G1").main and "One share of heads, from one sample." in site.get("G1").main and "never shown" not in site.get("G1").main and "<b>The design.</b> Flip, count, compare." in site.get("G1").main
192
192
  assert "Who plays what" in site.get("G1").main and "It draws every estimate." in site.get("G1").main and "Dropped questions (1)" in site.get("G1").main
193
- assert "A side question" not in site.get("").main and not any("A side question" in str(r) for r in site.rail()) and site.get("G1.Q2") is not None
193
+ home = site.get("").main # off the working part of the front page; listed, folded, among what was set aside
194
+ assert "A side question" not in home.split("<h2>Set aside</h2>")[0] and "Dropped questions (1)" in home.split("<h2>Set aside</h2>")[1] and not any("A side question" in str(r) for r in site.rail()) and site.get("G1.Q2") is not None
194
195
 
195
196
 
196
197
  def test_an_experiments_page_lists_its_runs_in_order_with_what_changed(tmp_path):
File without changes
File without changes
File without changes
File without changes
File without changes