lab-kit-cli 1.0.2__tar.gz → 1.0.3__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 (37) hide show
  1. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/CHANGELOG.md +20 -0
  2. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/PKG-INFO +1 -1
  3. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/docs/model.md +34 -3
  4. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/pyproject.toml +1 -1
  5. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/skills/lab-set-up/SKILL.md +4 -1
  6. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/skills/lab-work/SKILL.md +7 -3
  7. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/__init__.py +1 -1
  8. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/checks.py +27 -13
  9. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/record.py +13 -2
  10. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/site.py +21 -3
  11. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/views.py +10 -1
  12. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_site.py +4 -3
  13. lab_kit_cli-1.0.3/tests/test_vocabulary.py +116 -0
  14. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/.github/workflows/ci.yml +0 -0
  15. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/.github/workflows/policy.yml +0 -0
  16. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/.github/workflows/release.yml +0 -0
  17. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/.gitignore +0 -0
  18. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/AGENTS.md +0 -0
  19. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/CLAUDE.md +0 -0
  20. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/CONTRIBUTING.md +0 -0
  21. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/LICENSE +0 -0
  22. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/README.md +0 -0
  23. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/agents/reviewer.md +0 -0
  24. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/method/METHOD.md +0 -0
  25. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/skills/lab-review/SKILL.md +0 -0
  26. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/skills/lab-talk/SKILL.md +0 -0
  27. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/cli.py +0 -0
  28. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/history.py +0 -0
  29. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/runs.py +0 -0
  30. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/supervise.py +0 -0
  31. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/src/lab_kit/write.py +0 -0
  32. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_flow.py +0 -0
  33. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_held.py +0 -0
  34. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_integrity.py +0 -0
  35. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_needs.py +0 -0
  36. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tests/test_refusals.py +0 -0
  37. {lab_kit_cli-1.0.2 → lab_kit_cli-1.0.3}/tools/import_run.py +0 -0
@@ -1,5 +1,25 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.0.3
4
+
5
+ A word is now defined in one place, `GLOSSARY.md`. Before, the glossary and the goal's Vocabulary
6
+ both said what a word means, and the two could drift. The skills `lab-work` and `lab-set-up` changed:
7
+ run `lab init` in a lab after upgrading, or `lab check` reports that they differ from the installed
8
+ kit. Change the goal's Vocabulary to names, too: see below.
9
+
10
+ - A glossary entry may carry two more lines beside `- code:`. `- avoid: gate, filter, policy` lists
11
+ the words not to use for the thing; `- see: entries/kna-gate` (or a page of a library the charter
12
+ names, such as `pier-folio:/content/concepts/lora/`) names a page that explains the concept.
13
+ `lab define` prints both, and the glossary page shows the avoid words in small type and the page as a
14
+ link. The hover on a term stays the definition alone. `lab check` checks a `see` as it checks a
15
+ card's `see:`. It does not flag avoid words used in cards: a word to avoid for one thing is often right
16
+ for another.
17
+ - The goal's Vocabulary is a list of names only (`- field`). The goal's page and `lab show` draw
18
+ each with its glossary definition. `lab check` reports a name that is not a glossary term. A goal
19
+ written the old way (`- word: meaning`) still shows the glossary's definition, never the card's, and
20
+ `lab check` reports it: list the name only, and add the term to the glossary if it is missing there.
21
+ An existing lab must change its goal's Vocabulary to names.
22
+
3
23
  ## 1.0.2
4
24
 
5
25
  One defect found while rehearsing a real lab, four follow-ups from 1.0.1, and three larger word
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: lab-kit-cli
3
- Version: 1.0.2
3
+ Version: 1.0.3
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
@@ -325,7 +325,7 @@ Seven rules:
325
325
  Never record a decision that was not discussed with them.
326
326
  7. Say what you are on. When you start on a card, log what you are doing and why now.
327
327
 
328
- `lab check` holds what can be held mechanically: ids and links, a title and a description on every
328
+ `lab check` holds what can be held mechanically: ids and links, the goal's vocabulary being terms of the glossary, a title and a description on every
329
329
  card, short cards that write only their own front matter, a test on every line, a reason on every
330
330
  replacement, unchanged locks, sealed runs, results that still re-derive and were reviewed, use inside
331
331
  the resources' amounts, a decision behind every goal, question and metered amount, an experiment
@@ -387,7 +387,8 @@ resource. Nothing on it is static text except one line per goal.
387
387
  **An example on every question.** A question's page carries one case, step by step, as a numbered
388
388
  list that says who does what: the user, the agent, the tools, the gate, the scorer. A real episode
389
389
  where one exists, and said to be only the flow where none does. The goal's page says once who plays
390
- each role, states the design before the approximation, and pins the vocabulary.
390
+ each role, states the design before the approximation, and lists its vocabulary: the words every card
391
+ uses the same way, each drawn with the glossary's definition.
391
392
 
392
393
  **What was dropped** stays in the record: a dropped goal or question keeps its card and its page,
393
394
  and leaves Now, the rail and the graph.
@@ -449,7 +450,7 @@ the first two lines that are exactly `---`. A key that holds a list (`needs`, `u
449
450
 
450
451
  | Card | Front matter | Slots (word budget) |
451
452
  | --- | --- | --- |
452
- | `goal.md` | `title:`, `from:` (its decision); `reached: true`; `dropped: <why>` | description (70), Claim (90), Example: the idea in one case, from the reader's own domain (260), Approach: the design, how this lab approximates it, and where it knowingly differs (340), Roles: a list, `- <role>: <who plays it and what it does>` (170), Vocabulary: a list, `- <word>: <what it means>`, the few words every card uses the same way (260) |
453
+ | `goal.md` | `title:`, `from:` (its decision); `reached: true`; `dropped: <why>` | description (70), Claim (90), Example: the idea in one case, from the reader's own domain (260), Approach: the design, how this lab approximates it, and where it knowingly differs (340), Roles: a list, `- <role>: <who plays it and what it does>` (170), Vocabulary: a list of names only, `- <term>`, the few words every card uses the same way; each is a term of `GLOSSARY.md`, which defines it (260) |
453
454
  | `question.md` | `title:` (a short name), `asks:` (the question in full), `from:`, `needs:`; `dropped: <why>`; `answer:` and `answered:` are written by `lab answer` | description: why we ask (130), How we would know (150), Example: one case step by step, a numbered list (380), We expect (70), Wrong if (70), So far (180) |
454
455
  | `experiment.md` | `title:`, `needs:`, `uses:` (resources), `override: {resource: cap}`, `cost:`, `replaces:` with `because:` (one sentence), `waiting_on:`, `dropped: <why>` | description (70), Compares: the comparison in a sentence (80), Arms (260), Cases (100), Confirmed if (150), Refuted if (110), Outcomes (200), Limits (120), Found (180), Means (150) |
455
456
  | `reading.md` | `title:`, `needs:`, `dropped: <why>` | description (70), Looks at: what, and where it is (110), Seen (320), Suggests (150) |
@@ -468,6 +469,36 @@ as in CI, which checks out the lab alone, the page cannot be looked for: that is
468
469
  failure only with `--strict`. When the folder is there and the page is not, or the charter names no
469
470
  such library, it is a problem.
470
471
 
472
+ **The glossary** is `GLOSSARY.md`, the only place a word is defined. A group is a `# Group` heading
473
+ and a term a `## Term` heading under it, followed by its definition as a paragraph and these optional
474
+ lines, each `- key: value`:
475
+
476
+ ```
477
+ ## Guard
478
+ The part that reads every call and refuses the ones the contract forbids.
479
+ - code: kna.gate:Guard
480
+ - avoid: gate, filter, policy
481
+ - see: entries/kna-gate
482
+ ```
483
+
484
+ `code:` is where the term is in the code. `avoid:` lists, separated by commas, the words not to use
485
+ for this thing. `see:` names a page that explains the concept: a page of the lab's own library
486
+ (`entries/kna-gate`) or of a library the charter names (`pier-folio:/content/concepts/lora/`), the
487
+ same targets a card's `see:` takes. `lab define <term>` prints all of it. The glossary page shows the
488
+ definition, the code, the page as a link and the avoid words in small type; the hover on a term in
489
+ prose is the definition alone.
490
+
491
+ A word is defined once, in the glossary. A card that needs a word adds it there first, then uses it;
492
+ no card defines a word of its own. A concept that is not this lab's own (a method, a paper's idea) gets
493
+ a one-line entry and a `see:` link to the page that explains it, not a new explanation. The goal's
494
+ Vocabulary lists terms by name, and the goal's page and `lab show` draw each with the glossary's
495
+ definition and avoid words. `lab check` holds this: a name in Vocabulary that is not a term of the
496
+ glossary is a problem, and so is an item written with a meaning (`- word: what it means`): the part
497
+ before the colon is taken as the name, the glossary's text is what is shown, and the card must list the
498
+ name only. It checks an entry's `see:` as it checks a card's, including the note, and no failure, when
499
+ the other library is not on the machine. It does not look for avoid words in cards: a word to avoid for
500
+ one thing is often the right word for another, so `avoid:` is for the writer and the reviewer to read.
501
+
471
502
  **An arm** is a list item under Arms: its name, a colon, and what it is, so that a reader who has
472
503
  never seen it knows what was run.
473
504
 
@@ -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.2"
8
+ version = "1.0.3"
9
9
  description = "A research lab's record, its method, and the command that keeps both."
10
10
  license = "MIT"
11
11
  authors = [{ name = "Piergiuseppe Mallozzi" }]
@@ -37,7 +37,10 @@ You set the lab up in one discussion with the operator, so that everything it se
37
37
  9. Fill `lab.toml` (`code` for the code repository, `store` if the runs live elsewhere) and the
38
38
  local rules in `AGENTS.md`.
39
39
  10. Start `GLOSSARY.md`: each term the cards use that an outsider would not know, one sentence, with
40
- its name in the code when it has one.
40
+ its name in the code when it has one (`- code: module:Name`), the words not to use for it
41
+ (`- avoid: a, b`) and a page that explains it (`- see: <page>`) when there is one. The glossary is the
42
+ only place a word is defined: the goal's Vocabulary lists names, and a card that needs a word adds it
43
+ here first.
41
44
  11. The site: the lab's `docs/` folder is a folio library whose charter lists `lab_kit.site` under
42
45
  `views:`. Set it up with folio's own skill if it is not there.
43
46
 
@@ -36,8 +36,12 @@ The operator reads every card on the site, usually days later and without you. W
36
36
  - A paper, a method or a tool the reader may not know gets a few words saying what it is, and a
37
37
  link where it is first named: `[PISmith](pier-folio:/content/readings/...)` for a page of a
38
38
  library the charter names, or a web address. Put the same page under `see:`.
39
- - Use the goal's vocabulary. The goal's card pins the few words the lab uses for its own things;
40
- use those words, the same way, on every card, and add a word there before you use a new one.
39
+ - A word is defined once, in `GLOSSARY.md`, and nowhere else. Use the goal's vocabulary: the goal's
40
+ card lists, by name only (`- field`), the few words the lab uses for its own things; use those words,
41
+ the same way, on every card, and read a term's `avoid:` words as the ones not to use for it. When a
42
+ card needs a new word, add it to the glossary first, then list it on the goal if every card uses it.
43
+ A generic concept that is not this lab's own gets a one-line glossary entry and a `- see:` link to the
44
+ page that explains it, not a new explanation.
41
45
  - Say the design before the approximation: what the idea wants, then how this lab builds it and
42
46
  where it knowingly differs. A shortcut of the implementation is never the definition.
43
47
  - Say what is measured and what is your reading of it, in so many words.
@@ -208,7 +212,7 @@ what should come next: open a decision.
208
212
  - Never write that the operator decided something outside a decision recorded with `lab decide` (the
209
213
  lab-talk skill).
210
214
  - Open `plan/` and `runs/` only for the experiment you are working on.
211
- - A term an outsider would not know goes in `GLOSSARY.md`, once, and is used the same way everywhere.
215
+ - A term an outsider would not know goes in `GLOSSARY.md`, once, and is used the same way everywhere. A card never defines a word itself, and the goal's Vocabulary holds names, not meanings.
212
216
 
213
217
  ## Before you stop
214
218
 
@@ -1,2 +1,2 @@
1
1
  """lab-kit: a research lab's record, its method, and the command that keeps both."""
2
- __version__ = "1.0.2"
2
+ __version__ = "1.0.3"
@@ -27,6 +27,22 @@ def run(lab, rederive=True):
27
27
  unchecked = True
28
28
 
29
29
  absent = {} # the libraries the charter names whose folder is not on this machine
30
+
31
+ def see(where, page, who=""):
32
+ """A page a card's `see:` or a glossary entry's `- see:` names is there."""
33
+ if ":" in str(page): # a page of another library the charter names, such as background reading
34
+ from . import site
35
+ name, _, path = str(page).partition(":")
36
+ lib = site.libraries(lab).get(name)
37
+ if not lib:
38
+ bad("links", where, f"{who}see names {page}, which is not a page of a library the charter names")
39
+ elif not os.path.isdir(lib["path"]): # the other library is not on this machine, as in CI: nothing to look in
40
+ absent.setdefault(name, lib["path"])
41
+ elif not os.path.exists(os.path.join(lib["path"], path.lstrip("/"))):
42
+ bad("links", where, f"{who}see names {page}, and the library {name} holds no such page")
43
+ elif not os.path.exists(os.path.join(library, str(page).split("#")[0], "index.html")):
44
+ bad("links", where, f"{who}see names the page {page}, which is not in the library")
45
+
30
46
  # cards: each has its slots, stays short, and writes only what is its to write
31
47
  for n in lab.goals + lab.questions + lab.items + lab.decisions:
32
48
  try:
@@ -51,20 +67,18 @@ def run(lab, rederive=True):
51
67
  if n["type"] in ("goal", "question") and nodes.get(str(n.get("from")), {}).get("type") != "decision":
52
68
  bad("links", n["path"], f"`from:` names the decision it came out of; {n.get('from')!r} is not one")
53
69
  for page in n.get("see") or []:
54
- if ":" in str(page): # a page of another library the charter names, such as background reading
55
- from . import site
56
- name, _, path = str(page).partition(":")
57
- lib = site.libraries(lab).get(name)
58
- if not lib:
59
- bad("links", n["path"], f"see names {page}, which is not a page of a library the charter names")
60
- elif not os.path.isdir(lib["path"]): # the other library is not on this machine, as in CI: nothing to look in
61
- absent.setdefault(name, lib["path"])
62
- elif not os.path.exists(os.path.join(lib["path"], path.lstrip("/"))):
63
- bad("links", n["path"], f"see names {page}, and the library {name} holds no such page")
64
- elif not os.path.exists(os.path.join(library, str(page).split("#")[0], "index.html")):
65
- bad("links", n["path"], f"see names the page {page}, which is not in the library")
70
+ see(n["path"], page)
71
+ if n["type"] == "goal": # the words a goal lists are names; GLOSSARY.md is the only place a word is defined
72
+ for w in lab.vocabulary(n):
73
+ if not w["entry"]:
74
+ bad("cards", n["path"], f"Vocabulary lists {w['name']!r}, which is not a term in GLOSSARY.md: add it there first, and list the name only")
75
+ elif w["old"]:
76
+ bad("cards", n["path"], f"Vocabulary lists {w['name']!r} with a meaning: list the name only, `- {w['name']}`; GLOSSARY.md defines it")
77
+ for g in lab.glossary:
78
+ if g["see"]:
79
+ see("GLOSSARY.md", g["see"], f"{g['term']}: ")
66
80
  for name, path in sorted(absent.items()):
67
- notes.append(f"the library {name} is not here ({path}): the pages cards name in it under `see:` could not be checked here")
81
+ notes.append(f"the library {name} is not here ({path}): the pages cards and the glossary name in it under `see:` could not be checked here")
68
82
  unchecked = True
69
83
  for d in {os.path.dirname(x["path"]) for x in lab.items}:
70
84
  if sum(os.path.exists(os.path.join(root, d, f"{kind}.md")) for kind in R.STEPS) > 1:
@@ -470,9 +470,20 @@ class Lab:
470
470
  group = block[2:].strip()
471
471
  elif block.startswith("## "):
472
472
  head, _, rest = block[3:].partition("\n")
473
- code = re.search(r"^- code: (.+)$", rest, flags=re.M)
473
+ code, avoid, see = (re.search(rf"^- {key}: (.+)$", rest, flags=re.M) for key in ("code", "avoid", "see"))
474
474
  definition = " ".join(l for l in rest.split("\n") if l.strip() and not l.startswith("- ")).strip()
475
- out.append({"term": head.strip(), "group": group, "definition": definition, "code": code.group(1).strip("` ") if code else ""})
475
+ out.append({"term": head.strip(), "group": group, "definition": definition, "code": code.group(1).strip("` ") if code else "",
476
+ "avoid": [w for w in (w.strip("` ") for w in re.split(r"[,;]", avoid.group(1))) if w] if avoid else [], "see": see.group(1).strip("` ") if see else ""})
477
+ return out
478
+
479
+ def vocabulary(self, goal):
480
+ """The names a goal's Vocabulary lists, each with its glossary entry (None when the glossary lacks it) and whether
481
+ it was written the old way, with a meaning after a colon. The meaning is never read: only the glossary defines."""
482
+ by = {g["term"].lower(): g for g in self.glossary}
483
+ out = []
484
+ for item in items(goal["slots"].get("Vocabulary", "")):
485
+ name, colon, _ = item.partition(":")
486
+ out.append({"name": name.strip(), "entry": by.get(name.strip().lower()), "old": bool(colon)})
476
487
  return out
477
488
 
478
489
  def _lines(self, text):
@@ -190,6 +190,7 @@ CSS = """
190
190
  .lv h3{margin:1.2em 0 .3em}
191
191
  .lv .crumbs{font:500 .8rem var(--sans);color:var(--ink-3)}
192
192
  .lv .crumbs a{color:var(--ink-3)}
193
+ .lv .avoid{display:block;font:.78rem var(--sans);color:var(--ink-3)}
193
194
  .lv .lead{font-size:1.1rem;color:var(--ink-2);max-width:48rem}
194
195
  .lv .pill{display:inline-block;padding:.08rem .55rem;border-radius:999px;font:600 .72rem/1.5 var(--sans);white-space:nowrap;background:var(--sunk);color:var(--ink-2)}
195
196
  .lv .t-ok{background:var(--ok-soft);color:var(--ok)}
@@ -683,8 +684,10 @@ def goal_page(lab, T, g):
683
684
  body.append('<div class="slots">' + "".join(slot(*x) for x in extra) + "</div>")
684
685
  if pairs("Roles"):
685
686
  body.append('<h2>Who plays what</h2><table class="t roles"><tr><th>Role</th><th>Played by, and what it does</th></tr>' + "".join(f"<tr><td>{T(a)}</td><td>{T(b)}</td></tr>" for a, b in pairs("Roles")) + "</table>")
686
- if pairs("Vocabulary"):
687
- 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>' + "".join(f"<tr><td>{T(a)}</td><td>{T(b)}</td></tr>" for a, b in pairs("Vocabulary")) + "</table>")
687
+ words = lab.vocabulary(g)
688
+ if words: # the names are the card's; what each means is the glossary's, whatever the card says after a colon
689
+ 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
+ body.append('<h2>The words this lab uses</h2><table class="t roles"><tr><th>Word</th><th>What it means here, everywhere</th></tr>' + rows + "</table>")
688
691
  body.append("<h2>Questions</h2>" + "".join(qcard(lab, T, q) for q in lab.live(g["questions"])))
689
692
  gone = [q for q in g["questions"] if q["state"] == "dropped"]
690
693
  if gone:
@@ -954,6 +957,20 @@ def resources_page(lab, T):
954
957
  return frame(lab, "Resources", "".join(body))
955
958
 
956
959
 
960
+ def avoid_note(g):
961
+ """The words not to use for a term, in small type; nothing when there are none."""
962
+ return f' <span class="avoid">Avoid: {e(", ".join(g["avoid"]))}</span>' if g["avoid"] else ""
963
+
964
+
965
+ def see_link(lab, page):
966
+ """A link to the page that explains a term, a page of the lab's own library or of a library the charter names."""
967
+ page = str(page)
968
+ if ":" not in page:
969
+ return f'<a href="/docs/{e(page)}/">{e(pages(lab).get(page, page))}</a>'
970
+ url = outside(lab, page)
971
+ return f'<a href="{e(url)}">{e(page_title(lab, page))}</a>' if url else e(page)
972
+
973
+
957
974
  def glossary_page(lab, T):
958
975
  """Every term, by group, each group closed until it is opened or the filter finds something in it."""
959
976
  url = code_url(lab)
@@ -973,7 +990,8 @@ def glossary_page(lab, T):
973
990
  rows = []
974
991
  for g in terms:
975
992
  code = (f' · <a href="{url}/blob/main/src/{e(g["code"].split(":")[0].replace(".", "/"))}.py"><code>{e(g["code"])}</code></a>' if url else f' · <code>{e(g["code"])}</code>') if g["code"] else ""
976
- rows.append(f'<dt id="{e(g["term"].lower().replace(" ", "-"))}">{e(g["term"])}</dt><dd>{e(g["definition"])}{code}</dd>')
993
+ more = f' · See: {see_link(lab, g["see"])}' if g["see"] else ""
994
+ rows.append(f'<dt id="{e(g["term"].lower().replace(" ", "-"))}">{e(g["term"])}</dt><dd>{e(g["definition"])}{code}{more}{avoid_note(g)}</dd>')
977
995
  body.append(f'<details class="ggroup"><summary>{e(name)}<span>{len(terms)} terms</span></summary><dl class="gloss">{"".join(rows)}</dl></details>')
978
996
  body.append("<script>(function(){var h=decodeURIComponent(location.hash.slice(1));var t=h&&document.getElementById(h);if(t){t.closest('details').open=true;t.scrollIntoView();}})();</script>")
979
997
  return frame(lab, "Glossary", "".join(body))
@@ -125,6 +125,9 @@ def _show(lab, ident):
125
125
  if n["type"] == "goal":
126
126
  out = [f"{n['id']} ({n['state']}): {n['title']}", n["description"]] + came(n) + ["", f"Claim. {R.flat(n['slots'].get('Claim', '')) or 'not written yet'}", "", "Questions"]
127
127
  out += [f"- {q['id']} ({q['state']}): {q['title']}. {q['description']}" for q in n["questions"]]
128
+ words = lab.vocabulary(n)
129
+ if words: # the names are the card's; each is drawn with the glossary's definition
130
+ out += ["", "Vocabulary (defined in GLOSSARY.md)"] + [entry_text(w["entry"], "- ") if w["entry"] else f"- {w['name']}: not in the glossary" for w in words]
128
131
  return "\n".join(out + ["", "More: lab show <question id>"])
129
132
  about = [l for l in lab.lines if l["about"] == ident or l["about"].startswith(ident + ".")]
130
133
  decisions = ["", "Decisions about it"] + [f"- {d['id']} ({d['state']}): {d['title']}" for d in raised] if raised else []
@@ -233,7 +236,13 @@ def define(lab, term):
233
236
  hits = [g for g in lab.glossary if g["term"].lower() == term.lower()] or [g for g in lab.glossary if term.lower() in g["term"].lower()]
234
237
  if not hits:
235
238
  raise SystemExit(f"{term!r} is not in the glossary")
236
- return "\n\n".join(f"{g['term']}: {g['definition']}" + (f"\n code: {g['code']}" if g["code"] else "") for g in hits)
239
+ return "\n\n".join(entry_text(g) for g in hits)
240
+
241
+
242
+ def entry_text(g, lead=""):
243
+ """A glossary entry as the agent reads it: the definition, then the code, the words to avoid and the page that explains it."""
244
+ return (f"{lead}{g['term']}: {g['definition']}" + (f"\n code: {g['code']}" if g["code"] else "") + (f"\n avoid: {', '.join(g['avoid'])}" if g["avoid"] else "")
245
+ + (f"\n see: {g['see']}" if g["see"] else ""))
237
246
 
238
247
 
239
248
  def now(lab):
@@ -177,7 +177,8 @@ def test_a_readings_page_says_it_is_exploratory_and_what_was_dropped_leaves_the_
177
177
  describe(card, "Reads the estimates that fell outside the band.")
178
178
  fill(card, Looks_at="Twelve estimates.", Seen="1. Nine used the short sample.\n2. Three had the seed reset.", Suggests="Fix the seed.")
179
179
  goal = glob.glob(f"{root}/goals/G1-*/goal.md")[0]
180
- fill(goal, Roles="- The sampler: our code. It draws every estimate.", Vocabulary="- estimate: one share of heads, from one sample.", Approach="**The design.** Flip, count, compare.")
180
+ fill(goal, Roles="- The sampler: our code. It draws every estimate.", Vocabulary="- tally: the card's own meaning, which is never shown", Approach="**The design.** Flip, count, compare.")
181
+ open(f"{root}/GLOSSARY.md", "w").write("# Terms\n\n## tally\nOne share of heads, from one sample.\n")
181
182
  question = glob.glob(f"{root}/goals/G1-*/Q1-*/question.md")[0]
182
183
  fill(question, Example="1. **The sampler** flips a coin 100 times.\n2. **The scorer** compares the share of heads with one half.")
183
184
  lab(root, "new", "question", "G1", "A side question", "--from", "D1")
@@ -187,7 +188,7 @@ def test_a_readings_page_says_it_is_exploratory_and_what_was_dropped_leaves_the_
187
188
  assert page.status == "done" and "This looked at data the lab already had." in page.main and "<ol><li>Nine used the short sample.</li>" in page.main and "What it suggests" in page.main
188
189
  q = site.get("G1.Q1").main
189
190
  assert '<span class="kind">reading</span>' in q and "<ol><li><b>The sampler</b> flips a coin 100 times.</li>" in q and "Fix the seed." in q
190
- assert "The words this lab uses" in site.get("G1").main and "one share of heads" in site.get("G1").main and "<b>The design.</b> Flip, count, compare." in site.get("G1").main
191
+ assert "The words this lab uses" in site.get("G1").main and "One share of heads, from one sample." in site.get("G1").main and "never shown" not in site.get("G1").main and "<b>The design.</b> Flip, count, compare." in site.get("G1").main
191
192
  assert "Who plays what" in site.get("G1").main and "It draws every estimate." in site.get("G1").main and "Dropped questions (1)" in site.get("G1").main
192
193
  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
194
 
@@ -249,7 +250,7 @@ def test_nothing_written_in_a_lab_reaches_a_page_as_markup(tmp_path):
249
250
  Q = json.dumps(P)
250
251
  root = a_lab(tmp_path)
251
252
  open(f"{root}/lab.toml", "a").write(f"code_url = {json.dumps('https://example.com/' + P)}\n")
252
- open(f"{root}/GLOSSARY.md", "w").write(f"# {P}\n\n## sampler{P}\nWhat draws the estimates. {P}\n- code: {P}\n\n## estimate\nOne number from the sampler. {P}\n- code: sampler:{P}\n")
253
+ open(f"{root}/GLOSSARY.md", "w").write(f"# {P}\n\n## sampler{P}\nWhat draws the estimates. {P}\n- code: {P}\n\n## estimate\nOne number from the sampler. {P}\n- code: sampler:{P}\n- avoid: {P}, <b>x</b>\n- see: {P}\n")
253
254
  open(f"{root}/resources.toml", "a").write(f"other_use = [{{date = \"2026-01-01\", amount = 1, what = {Q}}}]\n\n[{Q}]\nwhat = {Q}\nkey = {Q}\nunit = {Q}\ngranted = 5\nfrom = \"D1\"\nrules = [{Q}]\n")
254
255
  goal = glob.glob(f"{root}/goals/G1-*/goal.md")[0]
255
256
  qdir = glob.glob(f"{root}/goals/G1-*/Q1-*")[0]
@@ -0,0 +1,116 @@
1
+ """A word is defined once, in GLOSSARY.md: avoid and see on an entry, and a goal that lists names only."""
2
+ import glob, os
3
+ import re
4
+
5
+ import pytest
6
+
7
+ from test_flow import fill, front, lab, open_question
8
+ from test_integrity import commit, under
9
+
10
+ ENTRIES = ("# Words\n\n## guard\nThe part that reads every call and refuses the ones the contract forbids.\n- code: kna.gate:Guard\n- avoid: gate, filter, `policy`\n- see: entries/the-guard\n\n"
11
+ "## field\nOne number on a grid.\n\n## LoRA\nA small adapter trained beside a frozen model.\n- see: notes:/content/concepts/lora/\n")
12
+
13
+
14
+ def a_lab(tmp_path, glossary=ENTRIES, vocabulary="- guard\n- field"):
15
+ root = under(tmp_path, "lab")
16
+ qdir = open_question(root)
17
+ open(f"{root}/GLOSSARY.md", "w").write(glossary)
18
+ goal = glob.glob(f"{root}/goals/G1-*/goal.md")[0]
19
+ fill(goal, Vocabulary=vocabulary)
20
+ os.makedirs(f"{root}/docs/content/entries/the-guard")
21
+ open(f"{root}/docs/content/entries/the-guard/index.html", "w").write("<p>the guard</p>\n")
22
+ os.makedirs(tmp_path / "notes" / "content" / "concepts" / "lora")
23
+ open(tmp_path / "notes" / "content" / "concepts" / "lora" / "index.html", "w").write("<p>lora</p>\n")
24
+ open(f"{root}/docs/folio.yaml", "w").write("title: lab\nlibraries:\n notes:\n path: ../../notes\n url: https://notes.example\n")
25
+ commit(root)
26
+ return root, goal
27
+
28
+
29
+ def test_avoid_and_see_are_read_and_shown_and_a_sound_lab_checks(tmp_path):
30
+ root, _ = a_lab(tmp_path)
31
+ out = lab(root, "define", "guard")
32
+ assert "guard: The part that reads every call" in out and "code: kna.gate:Guard" in out and "avoid: gate, filter, policy" in out and "see: entries/the-guard" in out
33
+ assert "avoid:" not in lab(root, "define", "field") and "see: notes:/content/concepts/lora/" in lab(root, "define", "LoRA")
34
+ assert "the record is sound" in lab(root, "check", "--strict")
35
+
36
+
37
+ def test_a_see_that_leads_nowhere_is_reported_like_a_cards(tmp_path):
38
+ root, _ = a_lab(tmp_path)
39
+ open(f"{root}/GLOSSARY.md", "a").write("\n## ghost\nNothing.\n- see: entries/not-there\n\n## stray\nNothing either.\n- see: elsewhere:/content/x/\n")
40
+ out = lab(root, "check", ok=False)
41
+ assert "GLOSSARY.md: ghost: see names the page entries/not-there, which is not in the library" in out
42
+ assert "GLOSSARY.md: stray: see names elsewhere:/content/x/, which is not a page of a library the charter names" in out
43
+ # the other library's page is missing while its folder is there
44
+ os.remove(tmp_path / "notes" / "content" / "concepts" / "lora" / "index.html")
45
+ os.rmdir(tmp_path / "notes" / "content" / "concepts" / "lora")
46
+ assert "LoRA: see names notes:/content/concepts/lora/, and the library notes holds no such page" in lab(root, "check", ok=False)
47
+ # the other library is not on the machine: a note, and a failure only when strict
48
+ os.rename(tmp_path / "notes", tmp_path / "away")
49
+ open(f"{root}/GLOSSARY.md", "w").write(ENTRIES)
50
+ out = lab(root, "check")
51
+ assert "the library notes is not here" in out and "the glossary name in it" in out and "problem(s)" not in out
52
+ assert "not everything could be checked here" in lab(root, "check", "--strict", ok=False)
53
+
54
+
55
+ def test_the_glossary_page_shows_avoid_in_small_type_and_see_as_a_link_and_the_tooltip_is_the_definition(tmp_path):
56
+ pytest.importorskip("folio.views")
57
+ from lab_kit.site import Provider
58
+ root, _ = a_lab(tmp_path)
59
+ page = Provider(root).get("glossary").main
60
+ assert '<span class="avoid">Avoid: gate, filter, policy</span>' in page
61
+ assert 'See: <a href="/content/entries/the-guard/">' in page and 'href="https://notes.example/content/concepts/lora/"' in page
62
+ goal = Provider(root).get("G1").main
63
+ tip = re.search(r'<span class="term" data-tip="([^"]*)"', page + goal + Provider(root).get("G1.Q1").main)
64
+ assert tip is None or "Avoid" not in tip.group(1)
65
+
66
+
67
+ def test_the_goal_lists_names_and_shows_the_glossarys_definitions(tmp_path):
68
+ pytest.importorskip("folio.views")
69
+ from lab_kit.site import Provider
70
+ root, _ = a_lab(tmp_path)
71
+ assert "the record is sound" in lab(root, "check", "--strict")
72
+ main = Provider(root).get("G1").main
73
+ assert "The words this lab uses" in main and "The part that reads every call and refuses the ones the contract forbids." in main and "One number on a grid." in main
74
+ assert "Avoid: gate, filter, policy" in main
75
+ shown = lab(root, "show", "G1")
76
+ assert "- guard: The part that reads every call" in shown and "avoid: gate, filter, policy" in shown and "see: entries/the-guard" in shown and "- field: One number on a grid." in shown
77
+
78
+
79
+ def test_a_name_that_is_not_in_the_glossary_is_reported(tmp_path):
80
+ pytest.importorskip("folio.views")
81
+ from lab_kit.site import Provider
82
+ root, _ = a_lab(tmp_path, vocabulary="- guard\n- sieve")
83
+ out = lab(root, "check", ok=False)
84
+ assert "Vocabulary lists 'sieve', which is not a term in GLOSSARY.md: add it there first" in out and "'guard'" not in out
85
+ assert "- sieve: not in the glossary" in lab(root, "show", "G1")
86
+ assert "not in the glossary" in Provider(root).get("G1").main
87
+
88
+
89
+ def test_the_old_form_is_reported_and_the_glossarys_text_is_shown_never_the_cards(tmp_path):
90
+ pytest.importorskip("folio.views")
91
+ from lab_kit.site import Provider
92
+ root, _ = a_lab(tmp_path, vocabulary="- field: a number the card made up\n- sieve: another made-up meaning")
93
+ out = lab(root, "check", ok=False)
94
+ assert "Vocabulary lists 'field' with a meaning: list the name only, `- field`" in out
95
+ assert "Vocabulary lists 'sieve', which is not a term in GLOSSARY.md" in out and "'sieve' with a meaning" not in out
96
+ main, shown = Provider(root).get("G1").main, lab(root, "show", "G1")
97
+ assert "One number on a grid." in main and "made up" not in main and "made-up" not in main
98
+ assert "- field: One number on a grid." in shown and "made up" not in shown and "made-up" not in shown
99
+
100
+
101
+ def test_the_goal_a_new_lab_starts_with_has_an_empty_vocabulary_and_passes(tmp_path):
102
+ root = under(tmp_path, "lab")
103
+ open_question(root)
104
+ assert "## Vocabulary" in open(glob.glob(f"{root}/goals/G1-*/goal.md")[0]).read()
105
+ commit(root)
106
+ assert "Vocabulary" not in lab(root, "check")
107
+
108
+
109
+ def test_markup_in_avoid_or_see_is_escaped(tmp_path):
110
+ pytest.importorskip("folio.views")
111
+ from lab_kit.site import Provider
112
+ P = 'x"><script>alert(1)</script>'
113
+ root, _ = a_lab(tmp_path, glossary=f"# Words\n\n## guard\nA guard.\n- avoid: {P}, <b>bold</b>\n- see: {P}\n\n## field\nA field.\n- see: other:{P}\n", vocabulary="- guard")
114
+ for page in (Provider(root).get("glossary").main, Provider(root).get("G1").main):
115
+ assert "<script>alert(1)" not in page and "<b>bold" not in page
116
+ assert "&lt;script&gt;" in Provider(root).get("glossary").main
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes