science

The daily surface of verifiably: the layer people and agents use

The commands a researcher or a coding agent runs in place of a folder of scripts and result tables: state a question as a typed claim, hold the data, declare the analysis, run it sealed, verify it from scratch, and read what the checked results add up to. Its scientific records live in a beliefs corpus, checked by the kernel, so the work stays traceable whoever did it. A CLI and an MCP server.

Authority: docs/commands.md, docs/sessions.md

Part of verifiably: verifiably builds understanding of the world from small, reproducible data analyses: each one a precise question asked of real data, recorded so anyone can run it again, with the data leading and unverified claims kept out. Overview

atoms · nodes · refs · beliefs · science · autonomy

Install

From a checkout, with atoms, nodes, and beliefs checked out beside it as sibling repositories (python/pyproject.toml takes beliefs from ../beliefs, which takes atoms and nodes from ../atoms and ../nodes):

git clone https://github.com/verifiably/atoms
git clone https://github.com/verifiably/nodes
git clone https://github.com/verifiably/beliefs
git clone https://github.com/verifiably/science
cd science && git config core.hooksPath .githooks
cd python && uv sync --frozen

From the repository root, just test-one <pytest args> runs a focused test selection, just check runs the hygiene checks, and just test-full forces the full test suite on a certified host (see AGENTS.md for the test execution policy and hosted CI split).

Usage

Start with Using science: explicit configuration, a synthetic source-checkout example through its verdict, and the path for your own data and analysis. Writes require certified storage; runs require normal confinement. The example uses public fixtures and demonstrates plumbing, not a biological finding.

From python/ after installation:

uv run science status --config /absolute/path/science.toml
uv run science build
uv run science adapters build --out /absolute/path/generated-adapters

World commands read --config or SCIENCE_CONFIG; configuration is never discovered from the working directory. Initialize/admit roots through the kernel's write protocol, then name them in configuration. CLI writes use an attended science serve --config <file>; science mcp serve --config <file> provides the same command dispatcher over stdio. See sessions.

The command surface is recorded in tools/cli.toml:

• Analysis: dataset, claim, spec, run, assess, verify, belief, next, recheck.
• Coordination: project, question, hypothesis, task, decide, revise, reuse, project-select, projects, project-show.
• Sharing: publish, publish-preview, provider-inspect, provider-bind, adopt, fetch, show.
• World and tooling: status, build, epoch, serve, mcp, adapters.

Scientific writes are kernel acts recorded in beliefs corpora. Selection and sharing leave session-ledger evidence; science's registry projects sharing lines. Historical sharing commentary is retained separately beside the ledger for exact replay. Sharing explains acceptance and those retention costs. belief computes its answer: honest NoBelief is distinct from zero or a refusal.

Research skills

With the generated science plugin installed, /science:sweep-assumptions compares research questions across explicitly named permitted inputs. It preserves discovery before feasibility assessment in an eight-part report. It makes no scientific record writes or biological analyses. Authored skills are product inputs; the adapter build includes them in the harness plugin.

Layout

• commands/ — one declaration and prompt per command.
• skills/ — authored research workflows.
• adapters/ — generated harness adapters.
• python/ — package, dispatcher, CLI, MCP and tests.
• docs/ — current public references. Task records and historical working documents live in the maintainer's separate records home; application use does not need it.

Documentation

• Guide — setup, analysis, selection, sharing and refusals.
• Configuration — keys, paths, contracts and mount profiles.
• Commands — declaration schema, handlers, reports and cursors.
• Sessions — launch, invocation, replay and transports.
• Sharing — publication, pins, acceptance and retirement.
• Stores — inherited stores, admission, relocation and recovery.
• Development — changes, tests, adapters and snapshots.
• Kernel guide — scientific record and belief concepts.

License

MIT, see LICENSE.