lab-kit-cli 0.1.0__tar.gz

lab_kit_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: gate
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Install folio and lab-kit
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Tests
+        run: python -m pytest -q
+      - name: Example lab
+        working-directory: examples/monte-carlo-lab
+        run: lab-kit check

lab_kit_cli-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,37 @@
+name: release
+
+# Publishes lab-kit to PyPI through trusted publishing: no token is stored anywhere.
+# One-time setup on pypi.org: Account, Publishing, add a publisher for
+#   project lab-kit-cli, owner pierg, repository lab-kit, workflow release.yml, environment pypi.
+# Run it by hand from the Actions tab. Pushing a tag does not publish.
+
+on:
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Configure git for the tests' temporary repositories
+        run: |
+          git config --global user.name "ci"
+          git config --global user.email "ci@example.invalid"
+      # Never publish untested: the same gate CI runs, against folio-kb from PyPI.
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest -q
+      - name: Example lab
+        working-directory: examples/monte-carlo-lab
+        run: lab-kit check
+      - name: Build
+        run: |
+          python -m pip install build
+          python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

lab_kit_cli-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+build/
+*.egg-info/

lab_kit_cli-0.1.0/AGENTS.md

@@ -0,0 +1,28 @@
+# AGENTS.md: lab-kit
+
+This file is the only copy of the operating rules for this checkout. `CLAUDE.md` is the one line `@AGENTS.md`.
+
+## Read
+
+- `README.md`: what lab-kit is and how it uses folio.
+- `docs/spec/lab-model.md`: the contract. When code, a skill or the method disagrees with it, it wins.
+- `method/`: `DISCIPLINE.md` and `LADDER.md`, the operating contract every lab inherits.
+- `skills/`: set-up-lab, plan-mission, run-mission, experiment, review. `agents/`: scout, runner, reviewer, reporter.
+- `src/lab_kit/`: the `lab-kit` command and the lab checks.
+- `examples/monte-carlo-lab/`: a small lab that passes the gate.
+
+## The gate
+
+```bash
+python -m pytest -q
+(cd examples/monte-carlo-lab && lab-kit check)
+```
+
+The tests, then `lab-kit check` on the example lab. CI runs the same two commands.
+
+## Rules
+
+- folio owns documents. lab-kit writes none, adds no genres and no journal kinds, and uses the lab pack's names exactly.
+- A check is added to `docs/spec/lab-model.md` §5, the registry in `src/lab_kit/checks/run.py` and a failing test in the same change.
+- The example lab's run evidence, lock record and run record are never edited by hand.
+- Never `git add -A`. Add the files you touched.

lab_kit_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0
+
+The first release.
+
+- The method: `DISCIPLINE.md` and `LADDER.md`, copied into each lab's `.lab/method/`.
+- Five skills, set-up-lab, plan-mission, run-mission, experiment and review, and four agent roles, scout, runner, reviewer and reporter. A mission has two phases: plan-mission drafts it with the operator and records the approval; run-mission carries out an approved mission on its own and refuses a draft.
+- The `lab-kit` command: `init`, `check`, `experiment`, `lock`, `run`, `runs`, `score`, `rederive`, `freeze`, `status` and `version`.
+- The lab gate: `folio check`, then seventeen lab checks, in one report. `lab-mission-approved` holds the mission's approval: nothing runs under a draft.
+- An example lab, `examples/monte-carlo-lab`, that passes the gate: does the error of a Monte Carlo estimate of pi shrink as 1/sqrt(n)?
+- Built on folio 0.1.0 and its lab pack.

lab_kit_cli-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

lab_kit_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# Contributing
+
+## Set up
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ../folio -e '.[dev]'
+```
+
+Use a checkout of folio beside this one, or `pip install folio-kb`.
+
+## The gate
+
+```bash
+python -m pytest -q
+(cd examples/monte-carlo-lab && lab-kit check)
+```
+
+The tests, then `lab-kit check` on the example lab. CI runs the same two commands.
+
+## How a change lands
+
+- The contract is `docs/spec/lab-model.md`. A change to a command or a check changes it in the same commit.
+- Every lab check has a test that breaks a copy of the example lab and asserts the check's name.
+- The method, the skills and the roles ship inside the package. A lab gets a new version of them from `lab-kit init`, never by hand.
+- If the example lab changes, rebuild it with the commands it shows: `lab-kit lock`, `lab-kit run`, `lab-kit score`, and folio's commands for its documents. Its run evidence is never edited by hand.
+- Write plain words in short sentences. Name no particular project, person or organisation in the docs or the code.
+- Fail loud. A problem lab-kit cannot work around is an error with a message that says what to do.

lab_kit_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piergiuseppe Mallozzi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lab_kit_cli-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: lab-kit-cli
+Version: 0.1.0
+Summary: A research lab's method and machinery on top of folio: pre-register, lock, run, score, re-derive.
+Project-URL: Homepage, https://github.com/pierg/lab-kit
+Project-URL: Issues, https://github.com/pierg/lab-kit/issues
+Author: Piergiuseppe Mallozzi
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: folio-kb>=0.1.0
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lab-kit
+
+lab-kit turns your coding agent into the staff of a research lab: it pre-registers each experiment, locks the plan before the first number, runs the lab's own code against the lock, scores the outcome against it, and records only numbers that re-derive from committed evidence. It is built on [folio](https://github.com/pierg/folio). folio decides what a document is; lab-kit decides when a result counts.
+
+You do not run lab-kit yourself, and you do not walk the agent through each step. You install it by handing your agent one line, set up the lab with its question, and then plan each mission with the agent in plain words. Once you approve the plan, the agent runs it end to end: it drafts the protocol, has a reviewer read it, locks it, runs it, scores it, has the numbers re-derived by an independent reviewer, records the result and writes the report, running the gate before every commit. It stops only where the plan and the method say it must.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pierg/lab-kit/main/docs/figures/how-lab-kit-works-dark.svg">
+  <img alt="How lab-kit works. You set up a lab for your question, plan a mission with your coding agent in plain words and approve it, then ask how it is going. The agent works through lab-kit's skills (set-up-lab, plan-mission, run-mission, experiment, review) and folio's skills for documents, and every change passes lab-kit check before it is committed. The lab in git has two zones: the folio library holds the question, the protocol, the result, the claim, the report and the journal; lab-kit's files hold the lock, the runs with sealed evidence, and the score. A protocol crosses into the lab files only through the lock, and a result comes back only through the reviewer pass." src="https://raw.githubusercontent.com/pierg/lab-kit/main/docs/figures/how-lab-kit-works-light.svg">
+</picture>
+
+## Install
+
+Paste this into your coding agent, in the repository that will hold the lab:
+
+```text
+Install lab-kit here: run `uv tool install lab-kit-cli --with-executables-from folio-kb` (or `pipx install --include-deps lab-kit-cli`), then `lab-kit init`, then read .agents/skills/set-up-lab/SKILL.md and follow it.
+```
+
+Installing lab-kit brings folio with it; the flag puts folio's command on the path too. The agent asks you at most three questions in one message (the lab's question, where the library lives, which paths are frozen), sets up the library with folio's lab pack, records the question as `Q-1`, and leaves the gate passing. A longer version of the prompt is in [SETUP.md](https://github.com/pierg/lab-kit/blob/main/SETUP.md). lab-kit needs Python 3.10 or later.
+
+## Give it a mission
+
+**1. Plan the mission together.** Once the lab is set up, state an objective:
+
+```text
+Mission: find out whether our pi estimator's error falls as 1/sqrt(n).
+```
+
+The **plan-mission** skill reads the lab, then asks in one message only what it cannot look up: "How many sample sizes and repeats count as enough? Token-free only? What would make you stop it early?" It drafts the plan: the question served, observable milestones, the scope, the spend, what it never touches, and where it must stop. You change what you want and say "approved". It records your approval and starts nothing.
+
+**2. Let it run.** The **run-mission** skill carries out the approved plan alone; it refuses an unapproved one. It dispatches workers through the **experiment** and **review** skills, sends a reviewer before the protocol locks and before any result counts, and keeps `ops/STATE.md` current so a crashed session resumes from the record. It comes back to you only at the plan's stops, or when a run would spend past the cap, a change would touch a frozen surface, a lock or a recorded result, or the work would leave the plan's scope.
+
+It reports the result by id, the misses as plainly as the hits, and its recommended next step. Meanwhile, ask "how is the mission going?" or "what should we do next?".
+
+## The loop
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pierg/lab-kit/main/docs/figures/lab-loop-dark.svg">
+  <img alt="The lab loop: in the folio library, a question leads to a draft protocol; it enters lab-kit's files only through the lock, runs and is scored there, and comes back to the library only through the reviewer pass, where the result is re-derived; then the result, the claim and the report. The journal records the lock, the run, the result and the lesson or kill, and lab-kit check runs under everything." src="https://raw.githubusercontent.com/pierg/lab-kit/main/docs/figures/lab-loop-light.svg">
+</picture>
+
+The documents (questions, protocols, results, claims, reports, the journal) are folio's, through its lab pack. The steps between them are lab-kit's skills: **set-up-lab** (once), **plan-mission** (with you, until you approve), **run-mission** (alone: dispatch, supervise, recover, report), **experiment** (draft, lock, launch, watch) and **review** (fold, score, record, report). Four agent roles do the work: **scout**, **runner**, **reviewer** and **reporter**.
+
+## The checks
+
+The gate, `lab-kit check`, runs folio's checks and then the lab's. It runs offline, names every problem in one pass, and changes nothing. CI runs the same command.
+
+- **Locks.** A locked protocol has a lock record, and its bytes still match it (`lab-lock-recorded`, `lab-lock-intact`).
+- **Runs.** Every run started after its lock, used exactly the pinned configuration, and its evidence matches its manifest (`lab-run-after-lock`, `lab-roster-frozen`, `lab-evidence-sealed`).
+- **Results.** Every live result re-derives exactly, rests on a finished run of a locked protocol, and passed an independent reviewer (`lab-rederive`, `lab-result-grounded`).
+- **Scores.** A scorecard scores exactly the ids the lock names (`lab-score-exact`), and a scored experiment is reported or explained (`lab-scored-reported`).
+- **Lab files.** Ids resolve, frozen surfaces are untouched, scripts pass `--selftest`, nothing runs under an unapproved mission, spend stays within its cap, records only grow, the method is current, and the state file stays a short pointer.
+
+Together they hold a chain from every number on a page back to the lock:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/pierg/lab-kit/main/docs/figures/number-chain-dark.svg">
+  <img alt="The chain behind one number in the example lab: the report's slope of -0.493 cites result R-2; R-2's re-derive command must print -0.493 again from the committed estimates.tsv; the evidence still matches its manifest; the run's lock hash matches the lock record; and the run used exactly the protocol's pinned configuration. Each link names the check that holds it." src="https://raw.githubusercontent.com/pierg/lab-kit/main/docs/figures/number-chain-light.svg">
+</picture>
+
+The gate checks that the record is consistent. Whether it is honest is the reviewer's job.
+
+## An example
+
+[`examples/monte-carlo-lab`](https://github.com/pierg/lab-kit/blob/main/examples/monte-carlo-lab) asks one question: does the error of a Monte Carlo estimate of pi shrink as 1/sqrt(n)? Its protocol, locked before the run, draws 100 seeded estimates at each of five sample sizes from 64 to 16,384 points, in pure Python, in under a second. The RMS error fell with a fitted log-log slope of -0.493 (`R-2`), so the hypothesis is kept; two of the four predictions missed, and the report says so as plainly as it says the rest. `R-2` supersedes `R-1`, which fitted the wrong error measure. Every record in it was made by the loop above, and `lab-kit check` passes on it with no error and no warning.
+
+Open it with your agent and ask "check this lab" or "re-derive R-2".
+
+## Reference
+
+The `lab-kit` command is the interface for agents and CI, the way git is: `init`, `check`, `experiment`, `lock`, `run`, `runs`, `score`, `rederive`, `freeze`, `status` and `version`. Each is specified in [`docs/spec/lab-model.md`](https://github.com/pierg/lab-kit/blob/main/docs/spec/lab-model.md) §6, the contract the skills, the roles, the checks and the command all build on. To work on lab-kit itself, see [CONTRIBUTING.md](https://github.com/pierg/lab-kit/blob/main/CONTRIBUTING.md). Changes: [CHANGELOG.md](https://github.com/pierg/lab-kit/blob/main/CHANGELOG.md).
+
+## License
+
+MIT. See [`LICENSE`](https://github.com/pierg/lab-kit/blob/main/LICENSE).

lab_kit_cli-0.1.0/README.md

@@ -0,0 +1,76 @@
+# lab-kit
+
+lab-kit turns your coding agent into the staff of a research lab: it pre-registers each experiment, locks the plan before the first number, runs the lab's own code against the lock, scores the outcome against it, and records only numbers that re-derive from committed evidence. It is built on [folio](https://github.com/pierg/folio). folio decides what a document is; lab-kit decides when a result counts.
+
+You do not run lab-kit yourself, and you do not walk the agent through each step. You install it by handing your agent one line, set up the lab with its question, and then plan each mission with the agent in plain words. Once you approve the plan, the agent runs it end to end: it drafts the protocol, has a reviewer read it, locks it, runs it, scores it, has the numbers re-derived by an independent reviewer, records the result and writes the report, running the gate before every commit. It stops only where the plan and the method say it must.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/figures/how-lab-kit-works-dark.svg">
+  <img alt="How lab-kit works. You set up a lab for your question, plan a mission with your coding agent in plain words and approve it, then ask how it is going. The agent works through lab-kit's skills (set-up-lab, plan-mission, run-mission, experiment, review) and folio's skills for documents, and every change passes lab-kit check before it is committed. The lab in git has two zones: the folio library holds the question, the protocol, the result, the claim, the report and the journal; lab-kit's files hold the lock, the runs with sealed evidence, and the score. A protocol crosses into the lab files only through the lock, and a result comes back only through the reviewer pass." src="docs/figures/how-lab-kit-works-light.svg">
+</picture>
+
+## Install
+
+Paste this into your coding agent, in the repository that will hold the lab:
+
+```text
+Install lab-kit here: run `uv tool install lab-kit-cli --with-executables-from folio-kb` (or `pipx install --include-deps lab-kit-cli`), then `lab-kit init`, then read .agents/skills/set-up-lab/SKILL.md and follow it.
+```
+
+Installing lab-kit brings folio with it; the flag puts folio's command on the path too. The agent asks you at most three questions in one message (the lab's question, where the library lives, which paths are frozen), sets up the library with folio's lab pack, records the question as `Q-1`, and leaves the gate passing. A longer version of the prompt is in [SETUP.md](SETUP.md). lab-kit needs Python 3.10 or later.
+
+## Give it a mission
+
+**1. Plan the mission together.** Once the lab is set up, state an objective:
+
+```text
+Mission: find out whether our pi estimator's error falls as 1/sqrt(n).
+```
+
+The **plan-mission** skill reads the lab, then asks in one message only what it cannot look up: "How many sample sizes and repeats count as enough? Token-free only? What would make you stop it early?" It drafts the plan: the question served, observable milestones, the scope, the spend, what it never touches, and where it must stop. You change what you want and say "approved". It records your approval and starts nothing.
+
+**2. Let it run.** The **run-mission** skill carries out the approved plan alone; it refuses an unapproved one. It dispatches workers through the **experiment** and **review** skills, sends a reviewer before the protocol locks and before any result counts, and keeps `ops/STATE.md` current so a crashed session resumes from the record. It comes back to you only at the plan's stops, or when a run would spend past the cap, a change would touch a frozen surface, a lock or a recorded result, or the work would leave the plan's scope.
+
+It reports the result by id, the misses as plainly as the hits, and its recommended next step. Meanwhile, ask "how is the mission going?" or "what should we do next?".
+
+## The loop
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/figures/lab-loop-dark.svg">
+  <img alt="The lab loop: in the folio library, a question leads to a draft protocol; it enters lab-kit's files only through the lock, runs and is scored there, and comes back to the library only through the reviewer pass, where the result is re-derived; then the result, the claim and the report. The journal records the lock, the run, the result and the lesson or kill, and lab-kit check runs under everything." src="docs/figures/lab-loop-light.svg">
+</picture>
+
+The documents (questions, protocols, results, claims, reports, the journal) are folio's, through its lab pack. The steps between them are lab-kit's skills: **set-up-lab** (once), **plan-mission** (with you, until you approve), **run-mission** (alone: dispatch, supervise, recover, report), **experiment** (draft, lock, launch, watch) and **review** (fold, score, record, report). Four agent roles do the work: **scout**, **runner**, **reviewer** and **reporter**.
+
+## The checks
+
+The gate, `lab-kit check`, runs folio's checks and then the lab's. It runs offline, names every problem in one pass, and changes nothing. CI runs the same command.
+
+- **Locks.** A locked protocol has a lock record, and its bytes still match it (`lab-lock-recorded`, `lab-lock-intact`).
+- **Runs.** Every run started after its lock, used exactly the pinned configuration, and its evidence matches its manifest (`lab-run-after-lock`, `lab-roster-frozen`, `lab-evidence-sealed`).
+- **Results.** Every live result re-derives exactly, rests on a finished run of a locked protocol, and passed an independent reviewer (`lab-rederive`, `lab-result-grounded`).
+- **Scores.** A scorecard scores exactly the ids the lock names (`lab-score-exact`), and a scored experiment is reported or explained (`lab-scored-reported`).
+- **Lab files.** Ids resolve, frozen surfaces are untouched, scripts pass `--selftest`, nothing runs under an unapproved mission, spend stays within its cap, records only grow, the method is current, and the state file stays a short pointer.
+
+Together they hold a chain from every number on a page back to the lock:
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/figures/number-chain-dark.svg">
+  <img alt="The chain behind one number in the example lab: the report's slope of -0.493 cites result R-2; R-2's re-derive command must print -0.493 again from the committed estimates.tsv; the evidence still matches its manifest; the run's lock hash matches the lock record; and the run used exactly the protocol's pinned configuration. Each link names the check that holds it." src="docs/figures/number-chain-light.svg">
+</picture>
+
+The gate checks that the record is consistent. Whether it is honest is the reviewer's job.
+
+## An example
+
+[`examples/monte-carlo-lab`](examples/monte-carlo-lab) asks one question: does the error of a Monte Carlo estimate of pi shrink as 1/sqrt(n)? Its protocol, locked before the run, draws 100 seeded estimates at each of five sample sizes from 64 to 16,384 points, in pure Python, in under a second. The RMS error fell with a fitted log-log slope of -0.493 (`R-2`), so the hypothesis is kept; two of the four predictions missed, and the report says so as plainly as it says the rest. `R-2` supersedes `R-1`, which fitted the wrong error measure. Every record in it was made by the loop above, and `lab-kit check` passes on it with no error and no warning.
+
+Open it with your agent and ask "check this lab" or "re-derive R-2".
+
+## Reference
+
+The `lab-kit` command is the interface for agents and CI, the way git is: `init`, `check`, `experiment`, `lock`, `run`, `runs`, `score`, `rederive`, `freeze`, `status` and `version`. Each is specified in [`docs/spec/lab-model.md`](docs/spec/lab-model.md) §6, the contract the skills, the roles, the checks and the command all build on. To work on lab-kit itself, see [CONTRIBUTING.md](CONTRIBUTING.md). Changes: [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

lab_kit_cli-0.1.0/SETUP.md

@@ -0,0 +1,17 @@
+# Set up a lab
+
+Paste everything below this line into your coding agent, in the repository that will hold the lab. The one-line prompt in the README does the same thing.
+
+---
+
+Set up a research lab here with lab-kit. lab-kit runs the lab's method on top of folio, which keeps the lab's documents. I will not run lab-kit or folio commands myself. You run them, through the skills they install.
+
+1. Install the engines. The Python package `lab-kit-cli` provides the `lab-kit` command and depends on `folio-kb`, which provides `folio`:
+   - If `lab-kit version` and `folio version` both print a version, go to step 2.
+   - Otherwise: `uv tool install lab-kit-cli --with-executables-from folio-kb`, or `pipx install --include-deps lab-kit-cli`. Both also put `folio` on the path. `pip install lab-kit-cli` in the project's environment works too.
+   - If none of these works, tell me and stop.
+2. Run `lab-kit init` in the repository root. Before a library exists, it installs only lab-kit's method, skills and roles.
+3. Read `.agents/skills/set-up-lab/SKILL.md` and follow it. It asks me at most three questions in one message: the lab's question, where the library lives, and which paths are frozen.
+4. Finish with `lab-kit check` passing and the setup committed. Then tell me, in a few lines, where the library is and the question's id, and ask me for the first mission.
+
+From then on a mission has two phases. First we plan it together with the plan-mission skill: I state the objective in plain words, you ask only what you cannot look up, and you write the plan as a draft until I approve it. Then the run-mission skill carries out the approved mission on its own, and comes back to me only at the stops the plan names. Between missions I may ask in plain words ("how is the mission going?", "what should we do next?"). Do not run an experiment, spend tokens on a live run, or push anything without my word.

lab_kit_cli-0.1.0/agents/reporter.md

@@ -0,0 +1,30 @@
+---
+name: reporter
+description: >-
+  Keeps a lab's front door current: its "where we are" state, its reviewed date, and one sentence
+  per new result. Use after a milestone
+  lands, a blocker changes, a decision is taken, a review concludes or a result is recorded.
+  Event-driven, never speculative.
+tools: Read, Grep, Glob, Bash, Write, Edit
+---
+
+You keep a lab's reader-facing pages in step with the record. You follow the record; you are never a second source of truth.
+
+Every change you make goes through folio's write skill. You never write a document by hand, and you never touch a generated index.
+
+Two kinds of page, kept apart:
+
+- **The front door** is the project document `lab.yaml` names under `front:`. It is the one page that carries rolling state. Refresh its `state`, "where we are", and set its `reviewed` date to today, for every operational change. That means a run paused or resumed, a blocker hit or cleared, a decision taken, or a budget spent. When a result is recorded, add exactly one plain sentence to its `learned` section, "What we have learned", citing the result's id. Never rewrite an earlier sentence to fold a new one in.
+- **A report** is frozen once `live`. The review skill writes it, through folio's `write-a-report` workflow. You never edit one. When a result it cites is superseded or retracted, folio shows a banner on the report. If it seems to need more, report back instead of editing.
+
+Content rules:
+
+1. Update a page only from what has landed in the record: the journal, a result, a run's evidence, a relayed operator decision. Never from a chat message.
+2. A number enters a page only by citing a result id. Never round, extrapolate or tidy it. The lab pack's rule checks this.
+3. An id is a link, never the subject of a sentence. Write "the larger cache cut median latency by a third (`R-7`)", not "`R-7` shows".
+4. Misses, nulls, blockers and retractions appear as prominently as wins. No deadline framing.
+5. Never turn another page into a rolling status page. State lives on the front door alone.
+
+Before finishing, run `lab-kit check` from the lab root and fix what it names. Commit only the documents you changed, their annotation files, and `.folio/` (what `folio index` regenerated). Never stage everything at once. Do not push: publishing is the operator's call.
+
+Report back: what changed on which page, the commit, and anything you refused to write for lack of a result to cite.

lab_kit_cli-0.1.0/agents/reviewer.md

@@ -0,0 +1,36 @@
+---
+name: reviewer
+description: >-
+  Independent review of a draft protocol, a scored experiment, a result, a claim, a report or an
+  instrument change, before it locks, is recorded, is published or merges. Read-only, with fresh
+  context every time. Use before any protocol locks, any result is recorded, or any instrument
+  change merges.
+tools: Read, Grep, Glob, Bash
+---
+
+You are an independent reviewer for this lab. Your verdict is the whole point of your role. Your independence is structural, not a courtesy.
+
+Rules:
+
+1. **Read-only.** You have no write or edit tools. You keep the shell to re-derive numbers and run checks. You use it read-only: logs, diffs, listings, and commands that change nothing outside a temporary folder. You never write into a run, the library, a lab file or another session's files.
+2. **Your verdict goes to the commander.** Never to the worker whose work you review. The commander records it and decides, or escalates to the operator.
+3. **Blind first.** Form your own reading of the artefact before reading anyone's account of it. Order: the locked protocol, the lock record, the evidence and the score; then the journal entries, the report and the brief.
+4. **The lock is the bar.** Score against the locked protocol, not against what the run seems to show. Check the protocol's hash against `lock.json`. A verdict is bounded by its weakest instrument. Undecided is not a pass. A miss is a miss.
+5. **Numbers re-derive.** Re-run the fold and every result's re-derive command. A number you cannot reproduce from the evidence is a defect.
+6. **Frozen surfaces.** Check that no surface `lab.yaml` freezes was touched, and that each run's configuration equals the protocol's.
+7. **The gate is the floor.** Run `lab-kit check`. It checks that the record is consistent, not that it is honest. That second part is yours.
+8. **Confirmation passes are narrow.** Re-derive everything once, in your first pass. After fixes, check only that each fix does what it claims, that changed numbers re-derive, that new measurements re-derive, and that no new overclaim entered. Cite your first pass for the rest.
+
+For a draft protocol, also check that:
+
+- the one variable fits in a sentence;
+- the kill rule exists and can fire;
+- every prediction can be wrong;
+- every measure names its denominator;
+- the configuration is pinned, and the allowed moves are listed.
+
+Verdict format, most severe first, one line each:
+
+`CONFIRMED|PLAUSIBLE | <the defect in one sentence> | <path, line or run id> | <how it fails>`
+
+Then one paragraph: safe to lock, record, publish or merge, or not, and what would change your mind. If you find nothing, say so plainly. Never invent a defect.

lab_kit_cli-0.1.0/agents/runner.md

@@ -0,0 +1,41 @@
+---
+name: runner
+description: >-
+  Executes a fully specified pipeline for a locked protocol: builds workspaces, invokes tools and
+  containers, launches runs with lab-kit, recovers pinned artefacts, folds evidence, and scores
+  predictions neutrally. Use when the design is done (a locked protocol or a complete brief
+  exists) and what remains is disciplined execution. Not for designing protocols or interpreting
+  results.
+tools: Read, Grep, Glob, Bash, Write, Edit
+---
+
+You execute measurement pipelines. The design is done. Your job is disciplined, fail-loud execution and an accurate account.
+
+Execution:
+
+- Work only from a locked protocol or a complete brief. If the protocol is not locked, stop and say so.
+- Launch every run with `lab-kit run`. It checks the lock and the configuration, and hashes the evidence into its manifest when the command exits.
+- Copy the mechanics of the earlier experiment the protocol names: its scripts, its pins, its gitignore. Do not invent new ones.
+- Verify every recovered artefact against its expected hash. Report a mismatch; never substitute silently.
+- Write only in the experiment's `bin/` and in a run's `work/`. Evidence reaches `out/` through the run's own command.
+- Fail loud. An apparatus failure is a result to report, not a thing to patch around.
+
+Reporting:
+
+- Report once, at completion, with the full account the brief asks for. No step-by-step narration.
+- To wait on long work, arm one watcher that fires only on the end marker or an error signature. Silence between launch and end is correct.
+- List every deviation and surprise with its time, so the experiment skill can journal it.
+
+Hard limits:
+
+- No commits. No documents: you never write in the library, the journal included.
+- Never edit a locked protocol, a finished run, a lock record or a frozen surface.
+- Never change the configuration the protocol pins, and never raise a budget cap.
+- Never read a held-out or sealed set into a workspace you build.
+- Respect the concurrency cap in the brief. On a shared machine, default to modest parallelism.
+
+Honesty:
+
+- Score predictions neutrally: hits, misses and indeterminates alike.
+- A miss or a null is a full result.
+- Never word a claim more strongly than the brief allows.

lab_kit_cli-0.1.0/agents/scout.md

@@ -0,0 +1,28 @@
+---
+name: scout
+description: >-
+  Read-only reconnaissance inside a lab: the state, the active mission, recent journal entries,
+  open questions, run status, git state, a document lookup. Use for any sweep whose output the
+  commander needs only in summary, so raw files stay out of the commander's context.
+tools: Read, Grep, Glob, Bash
+---
+
+You are the lab's scout. You read; you never write. Your shell use is read-only: status, logs, listings, searches. Never anything that changes a file, a repository or a process.
+
+Orient in this order:
+
+1. `lab.yaml` and the lab's `AGENTS.md`: where the library is, and the frozen surfaces.
+2. `ops/STATE.md` and the active mission file: what is true now.
+3. `lab-kit status` and `lab-kit runs`: live, finished and orphaned runs.
+4. The journal: `folio journal --since <date>` or `folio journal --about <id>`, newest first: what happened.
+5. The library's questions, results and claims, by id: `folio search`, `folio cite <id>`.
+6. For one experiment: its protocol, its `lock.json`, its runs' `run.json`, and its `score.yaml`.
+
+Report style:
+
+- Lead with the direct answer to what you were asked.
+- Then the specifics that carry it: paths, ids, short quotes, dates, run ids.
+- Say which parts the record states and which you infer.
+- Name every contradiction between two files, with both paths. Never smooth one over.
+- A number you report carries its result id, or the evidence path it came from.
+- Stay within the word budget you were given. The default is 500 words.