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

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 23 additions & 14 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,30 @@
# Changelog

## 1.13.0

- **A scope page is a storyline.** A storyline is one argument the lab is building from its findings, for one
audience: what a paper, a talk or a report is later written from, never the finished artifact. The table in
`lab.toml` is `[storylines]`, `lab now` has a Storylines section and a "Serving no active storyline" list, and
the method, the model and the skills say storyline throughout. 1.12.0's table of the same shape, `[papers]`,
is no longer read: no lab had turned it on. Run `lab init` in a lab after upgrading.

## 1.12.0

- **Papers drive the work; the record names no paper** (method rule 8, model section 4). A lab that writes
papers keeps one overview page of the whole trail and one page per active paper, written as that paper's
argument and opening with a scope table: audience, thesis, experiments included, excluded or superseded, and
open. The papers' open rows and their reviewers' criticisms say what is proposed, ordered, parked or dropped,
and a result revises the overview and every paper it touches. So far gives the current finding, never the
story of the bugs on the way. Adding, merging or retiring a paper is direction.
- **`[papers]` in `lab.toml`** names the overview and the active paper pages, as library paths. It is optional:
a lab without it is unchanged. With it, each paper page marks its scope cells `data-scope="included"`,
`"excluded"` and `"open"`, and `lab check` refuses an id that is not in the lab, a step under included that is
not done or is void, a step under open that is finished, a question or goal under open that is done, a parked
or dropped question or goal in either, and a goal, question or step listed in two rows of one page. It notes a
paper page committed before a result about something it lists under included or open.
- **`lab now` lists the papers**: each active paper with the open work its scope names, then the live steps
that no paper lists, by themselves or by their question or goal.
- **Storylines drive the work; the record names no storyline** (method rule 8, model section 4). A lab keeps one
overview page of the whole trail and one page per active storyline, written as that argument and opening with
a scope table: audience, thesis, experiments included, excluded or superseded, and open. The storylines' open
rows and their reviewers' criticisms say what is proposed, ordered, parked or dropped, and a result revises the
overview and every storyline it touches. So far gives the current finding, never the story of the bugs on the
way. Adding, merging or retiring a storyline is direction.
- **A table in `lab.toml`** (`[papers]` in this release, `[storylines]` from 1.13.0) names the overview and the
active storyline pages, as library paths. It is optional: a lab without it is unchanged. With it, each
storyline page marks its scope cells `data-scope="included"`, `"excluded"` and `"open"`, and `lab check`
refuses an id that is not in the lab, a step under included that is not done or is void, a step under open
that is finished, a question or goal under open that is done, a parked or dropped question or goal in either,
and a goal, question or step listed in two rows of one page. It notes a storyline page committed before a
result about something it lists under included or open.
- **`lab now` lists the storylines**: each active one with the open work its scope names, then the live steps
that none lists, by themselves or by their question or goal.
- The skills `lab-set-up`, `lab-work`, `lab-talk` and `lab-review` and the method changed: run `lab init` in a lab
after upgrading.

Expand Down
72 changes: 37 additions & 35 deletions docs/model.md
Original file line number Diff line number Diff line change
Expand Up @@ -255,7 +255,7 @@ in points. When a named result belongs to a replaced experiment, the page says s
You decide two things: **direction** and **resources**. You decide them in a discussion with the agent,
not by approving requests.

- **Direction.** The goals, the questions, and the papers they serve.
- **Direction.** The goals, the questions, and the storylines they serve.
- **Resources.** Everything outside the lab that it may touch: what it may use, how much, and what it
may do there.

Expand Down Expand Up @@ -376,35 +376,37 @@ is a resource and a cap, nothing else. A lower cap is the agent's to write. A hi
rule, a new resource or a larger grant comes out of a decision: one that lists that experiment, or
that resource, under `about:`.

**Papers drive the work; the record names no paper.** A lab that writes papers keeps two layers apart. The
record (`goals/`, `decisions/`, `runs/`) is the trail: every question, run, failed attempt and replaced
experiment, so that every number has an origin. No card names a paper, because papers change, split, merge
and are dropped while the record stays as it is and is read by each of them. Above the record, the lab's
library holds one **overview** page that keeps the whole trail in one place, whatever paper it serves: the
words on one running example, the workflow, every related-work row, every established finding, every
criticism and what answers it. Beside it, each **active paper** has its own page, written as that paper's
technical argument and nothing else: it never talks about the lab or how it works. A paper page opens, under
its thesis, with a **scope table** of five rows: the target audience and venues, the core thesis, the
experiments included (the clean runs each claim rests on), the experiments excluded or superseded (a run
that hit a harness bug, a subset a full run replaced, work that belongs to another paper), and the open
experiments the paper still needs. Then come its words on one running example, its pipeline, its
comparison with the published work of its community, its established results citing only included work,
the criticisms a reviewer in that community will raise with what answers each, and what remains to run.

The control runs from the papers to the lab, not the other way. Which questions and experiments are
proposed, ordered, parked or dropped follows the open rows and the criticisms on the active paper pages: a
decision says which paper row it serves, and a step that serves none is a candidate to park or drop. When a
result lands, the overview and every paper it touches are revised; a run that a newer one supersedes moves
from included to excluded. Adding, merging or retiring a paper is direction, so it is decided with you. A
question's or an experiment's So far gives the current finding, not the story of the bugs on the way: the
replaced experiments and the reasons they were replaced keep that story.
**Storylines drive the work; the record names no storyline.** A **storyline** is one argument the lab is
building from its findings, for one audience: what a paper, a talk or a report will later be written from. It is
the argument, never the finished artifact, and it keeps moving while the work runs. A lab that keeps storylines
keeps two layers apart. The record (`goals/`, `decisions/`, `runs/`) is the trail: every question, run, failed
attempt and replaced experiment, so that every number has an origin. No card names a storyline, because
storylines change, split, merge and are dropped while the record stays as it is and is read by each of them.
Above the record, the lab's library holds one **overview** page that keeps the whole trail in one place,
whatever storyline it serves: the words on one running example, the workflow, every related-work row, every
established finding, every criticism and what answers it. Beside it, each **active storyline** has its own page,
written as that storyline's technical argument and nothing else: it never talks about the lab or how it works. A
storyline page opens, under its thesis, with a **scope table** of five rows: the target audience and venues, the
core thesis, the experiments included (the clean runs each claim rests on), the experiments excluded or
superseded (a run that hit a harness bug, a subset a full run replaced, work that belongs to another storyline),
and the open experiments the storyline still needs. Then come its words on one running example, its pipeline,
its comparison with the published work of its community, its established results citing only included work, the
criticisms a reviewer in that community will raise with what answers each, and what remains to run. When the
time comes to write the paper, the talk or the report itself, it is written from this page.

The control runs from the storylines to the lab, not the other way. Which questions and experiments are
proposed, ordered, parked or dropped follows the open rows and the criticisms on the active storyline pages: a
decision says which storyline row it serves, and a step that serves none is a candidate to park or drop. When
a result lands, the overview and every storyline it touches are revised; a run that a newer one supersedes
moves from included to excluded. Adding, merging or retiring a storyline is direction, so it is decided with
you. A question's or an experiment's So far gives the current finding, not the story of the bugs on the way:
the replaced experiments and the reasons they were replaced keep that story.

A lab opts in by naming the pages in `lab.toml` (section 9). Then `lab check` holds each scope table:
included lists only finished work that is not void, replaced or dropped, open only work still to do, nothing
parked or dropped is in either, and a goal, a question or a step sits in one row; a paper page committed
before a result about something it lists under included or open is noted. `lab now` lists each paper's open
experiments, and the live steps no paper lists, by themselves or
by their question or goal.
parked or dropped is in either, and a goal, a question or a step sits in one row; a storyline page committed
before a result about something it lists under included or open is noted. `lab now` lists each storyline's
open experiments, and the live steps no storyline lists, by themselves or by their question or goal.

## 5. What the agent uses

Expand Down Expand Up @@ -492,13 +494,13 @@ Eight rules:
6. Record what was decided and why, in the lab's words, and show the operator the text as recorded.
Never record a decision that was not discussed with them.
7. Say what you are on. When you start on a card, log what you are doing and why now.
8. Papers drive the work; the record names no paper. The papers' open rows and criticisms say what to
propose, order, park or drop, and a result revises the overview and every paper it touches.
8. Storylines drive the work; the record names no storyline. The storylines' open rows and criticisms say
what to propose, order, park or drop, and a result revises the overview and every storyline it touches.

`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
card, short cards that write only their own front matter, a test on every line, a reason on every
replacement, unchanged locks, sealed runs, results that still re-derive and were reviewed, use inside
the resources' amounts, what each paper's scope table lists when the lab names its papers, a decision behind every goal, question and metered amount, an experiment
the resources' amounts, what each storyline's scope table lists when the lab names its storylines, a decision behind every goal, question and metered amount, an experiment
behind every answer, the method and the skills as the kit installed them, and a history that only
grows. What it cannot read as this page describes (a mistyped folder, a list written as one value, a
file that is not text) is a problem it reports; no command stops on it.
Expand Down Expand Up @@ -935,16 +937,16 @@ holds the line `launched`, else next, and `lab check` asks for the status to be
reports a mission that breaks any of this, one whose `carries:` is not a decision, and a current mission whose
decision is still open.

**Papers.** `lab.toml` names the library's paper pages in a table, as library paths (the path under
**Storylines.** `lab.toml` names the library's storyline pages in a table, as library paths (the path under
`content/`, as `see:` writes it):

```
[papers]
[storylines]
overview = "entries/where-the-results-stand"
active = ["entries/paper-a", "entries/paper-b"]
active = ["entries/storyline-a", "entries/storyline-b"]
```

`overview` is the page that keeps the whole trail; it is never an active paper. Each page under `active` is
`overview` is the page that keeps the whole trail; it is never an active storyline. Each page under `active` is
in the library and marks the three cells of its scope table that list work, `data-scope="included"`,
`data-scope="excluded"` and `data-scope="open"`, empty when it lists nothing:

Expand All @@ -960,7 +962,7 @@ a question or a step has one row on a page: where another row needs to mention i
without its link. A question written in one row and a step under it written in another is allowed: the open
question with its one finished step included is the usual case. A decision may be cited in any row. In
`lab now` and in the note on a stale page, a goal or a question written under included or open stands for
every step under it. A lab without `[papers]` has none of this.
every step under it. A lab without `[storylines]` has none of this.

**Worked-out states.** A goal is open until `reached: true` makes it done or `dropped:` drops it. A
question is waiting while the decision it came from is open, then open, then done with its answer; it
Expand Down
15 changes: 8 additions & 7 deletions method/METHOD.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
checks the solver leaves open", not "of 20". *The numbers and the budgets are held by `lab check`; whether a page
can be read cold is judged, and the reviewer reads for it.*
5. **Decide everything that is not direction or resources, and never wait idle.** Direction is the
goals, the questions and the active papers. Resources are what `resources.toml` lists and how much. For those two,
goals, the questions and the active storylines. Resources are what `resources.toml` lists and how much. For those two,
open a decision that says what was seen, the options and what you recommend, and work on what it
does not hold. What a decision settled needs no further yes. Everything else is yours: decide,
record it, go on. A mission (`missions/`) carries out what a settled decision settled across sessions, and approves
Expand All @@ -50,11 +50,12 @@ judgement. The lab's own `AGENTS.md` adds only what is local.
should never have to ask you. When you start on a card or move to another, log it:
`lab log <id> doing "<what>" "<why now>"`. The line stands on the front page until a result, a
stuck line or a choice about the same card ends it. *Judged.*
8. **Papers drive the work; the record names no paper.** The record is the trail, and no card names a paper.
When the lab writes papers, its library keeps one overview of the whole trail, and one page per active
paper that is that paper's argument and nothing else. A paper page opens with its scope table: audience,
8. **Storylines drive the work; the record names no storyline.** The record is the trail, and no card names a storyline.
When the lab keeps storylines (the arguments its papers, talks or reports will be written from), its
library keeps one overview of the whole trail, and one page per active
storyline that is that storyline's argument and nothing else. A storyline page opens with its scope table: audience,
thesis, the experiments included, those excluded or superseded, and those still open. What you propose,
order, park or drop follows the papers' open rows and their reviewers' criticisms; when a result lands,
revise the overview and every paper it touches, and move what a newer run supersedes to excluded. Adding,
merging or retiring a paper is direction. *Held by `lab check` when `lab.toml` names the papers; otherwise
order, park or drop follows the storylines' open rows and their reviewers' criticisms; when a result lands,
revise the overview and every storyline it touches, and move what a newer run supersedes to excluded. Adding,
merging or retiring a storyline is direction. *Held by `lab check` when `lab.toml` names the storylines; otherwise
judged.*
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ build-backend = "hatchling.build"
[project]
dynamic = ["readme"]
name = "lab-kit-cli"
version = "1.12.0"
version = "1.13.0"
description = "A research lab's record, its method, and the command that keeps both."
license = "MIT"
authors = [{ name = "Piergiuseppe Mallozzi" }]
Expand Down
2 changes: 1 addition & 1 deletion skills/lab-review/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@ A failed plan is fixed by its author and read again.
the first sentence and folds the rest.

A failed results review is final for that experiment. Say in the note what a replacement must do
differently. Its numbers can then be cited nowhere: if a paper page lists it under included, `lab check`
differently. Its numbers can then be cited nowhere: if a storyline page lists it under included, `lab check`
says so, and the author takes it off.

When you read a plan, also read the card as someone who was not there. If an arm is named and not
Expand Down
9 changes: 5 additions & 4 deletions skills/lab-set-up/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,13 +43,14 @@ You set the lab up in one discussion with the operator, so that everything it se
here first.
11. The site: the lab's `docs/` folder is a folio library whose charter lists `lab_kit.site` under
`views:`. Set it up with folio's own skill if it is not there.
12. If the lab will write papers, ask the operator which papers it aims at now, for whom and where (it is
direction, and may stay empty). Write the overview page (for example `entries/where-the-results-stand`) with folio's
12. If the lab will argue its findings to an audience (a paper, a talk, a report), ask the operator which
storylines it aims at now, for whom and where (it is direction, and may stay empty). A storyline is the
argument such an output is written from, not the output itself. Write the overview page (for example `entries/where-the-results-stand`) with folio's
write skill: the words on one running example, the workflow, the related work, and empty sections for the
findings and the criticisms. For each paper, write `entries/paper-<slug>`: its thesis, then the scope table
findings and the criticisms. For each storyline, write `entries/storyline-<slug>`: its thesis, then the scope table
(target audience and venues, core thesis, experiments included, excluded or superseded, open), with the
last three cells marked `data-scope="included"`, `"excluded"` and `"open"`. Name them in `lab.toml` under
`[papers]` (`overview`, `active`). No card names a paper (method rule 8).
`[storylines]` (`overview`, `active`). No card names a storyline (method rule 8).
13. Commit. Git is what holds the record: nothing is held before the first commit, and
`lab check --strict` says so.

Expand Down
Loading
Loading