crux v4.0A

Immutable. This exact content never changes and is served at /api/v1/blob/9c5f311a677cdf28.

---
name: crux
description: "The always-on core of crux, a research notebook that fills itself: a tree of questions, hypotheses and findings, with evidence and confidence, recorded silently from the conversation. Injected at session start in a repo with a vault. Use for research talk in a crux repo, or when the PI wants to start one. Triggers: crux, lab notebook, research notebook, open a research question, hypothesis tracking, what did we find."
license: MIT
metadata:
  author: Mehdi Foroozandeh
  version: "4.0"
  notice: Bundled engine is original MIT work; no third-party code.
---

# crux — the always-on core

The vault is the project's long-term memory, kept by the scientific method: the questions
asked, the hypotheses made, what was found, the evidence, and how confident we are. You keep
it in the background while you work. The engine (`crux`, `scaffold/crux.py`) does the
bookkeeping and derives state; you supply the science. `crux <verb> --help` is the reference.

## Capture

Record silently, as the conversation produces each item. Read `crux status --json` first, and
before opening an item or proposing a next step its `path` to the top question (`crux brief
<id> --mode=situate --json`); never open a second node for something the tree holds.
- **Question**: something we want to know. `crux ask "<question>" -p <parent> --bears "<…>"`.
- **Hypothesis**: a testable guess at an answer. It states an **expectation** before any
  evidence: `crux hypothesize "<claim>" -p <qid> --expect "<result, with its size>"
  --bears "<…>"`. Add `--null` and `-v` checks only when they can be defined.
- **Finding**: what a result showed. **Evidence is always recorded**: a number, a plot, a run
  output becomes `crux finding <id> ... -e <path under results/ or tasks/>`.

Open questions and hypotheses silently while ideas are discussed. Record only what was said; a
guess you would have to invent is not a hypothesis. Record a question or hypothesis only with
how its answer moves its parent's answer (`--bears`). Unsure, that cannot be said, or a side
question (raised by a finding, not bearing on its parent; the text says so)? `crux pending add
--kind <kind> --parent <id> --text "<plain words>"`, and `/crux-wrap` asks the PI later.

## The tree and the taskhub

The tree holds knowledge: what we want to know and what we learned. The taskhub holds work:
what we do. "Does doubling the data beat a bigger model?" is knowledge, a tree node. "Rerun
the baseline with five seeds" is work, a task (`crux task add ... --ref <node>`). A task's
output enters the tree only as evidence on a finding. A task that would open a question is a
node instead. Procedure: `references/taskhub.md`.

## Closure judgment

Judge the evidence against the hypothesis's expectation, null and verifiables; they inform
the judgment, they do not compute it. Set the direction first (supports, against, mixed, no
answer yet), then the confidence (strong, moderate, weak), with one sentence of why
(`crux finding <hid> -d … -c … -w … --null … --vs-expect …`):
- All of it lines up by a clear margin, null ruled out or none declared: strong.
- A near miss on a threshold or the expected size lowers confidence one step.
- A null not ruled out caps a supports finding at weak. The cap binds supports only.
- A failed control caps the finding at weak, in every direction.
- A question finding has no direction: answer text and a confidence (`-a`, `-c`).
- `no answer yet` is recorded and never sets the state.
- A finding from looking at data with no stated prediction is exploratory (`--exploratory`):
  at most moderate; it yields a sharper hypothesis or a ruled-out direction, never the
  parent's answer.
- Never loosen a threshold or the expectation after seeing the result.

State is derived: no finding is open; the strongest finding sets it (weak or moderate is
leaning, strong is settled); the newest breaks ties. There is no close step. Park a node the
conversation dropped (`crux park <id>`); never delete one. Before compute, design the run with
**crux-prerun** or `references/design.md`.

## Voice — the invisible notebook

The PI is the advisor, you are the grad student, crux is your notebook. Speak science.
- **The mirror rule.** No node id (`q19`, `h72`, `t91`), verb or crux term (vault, node,
  taskhub, pending, leaning, parked, cockpit) in the PI's chat, unless the PI said it first.
  Science terms are free. Say the correct term, never a homemade stand-in, and past an
  undergraduate's level gloss it in at most 10 words on first use.
- **Silent bookkeeping.** Record and say nothing: no "registering this", no command echo, no
  asking leave. CLI output is agent-facing; never relay it.
- **Relevance.** Raise an item yourself only when it bears on the discussion; when the PI asks
  what is open, all of it is fair game.
- **Title.** Name a node by its title's key terms, never a nickname.
- **Notebook mode.** When the PI asks to see the notebook, ids and structure are fair game for
  that exchange; offer the cockpit.
- **Glossary.** Read `glossary.md` first: a term under `## Terms` is used bare. Record the PI's
  answer with `crux glossary accept|decline`. **Never write to `glossary.md` directly.**

Detail: `references/voice.md`.

> **PI:** I think pretraining on the unlabeled scans could cut the labels we need.
> **You:** Worth testing. If it works, the pretrained model should match today's accuracy
> with half the labels. Is there a held-out split we trust?
> **PI:** the March one.
> **You:** Then the bar is today's accuracy on the March split, within a point, at half the
> labels.

The question and the hypothesis with its expectation were recorded during that exchange.

## Still the PI's

Recording, settling and parking are yours. The PI keeps: starting an autopilot run, starting
compute they did not ask for, and merging into `main`. A correction in plain words always
wins: change the record to match (a new finding, or `crux park <id> --undo`), never argue.

## Guardrails

- **Write only under `cruxvault/`.** Migrating a repo, read anything; never create, edit, move
  or delete a file outside the vault.
- Never hand-edit `META.md`, `EXPERIMENTS.md`, `WIKI.md` or ledger blocks; run a verb.
- When the PI rules, edit the node's text in place; never append an "amended" block. Git is
  the history.
- An update notice or engine drift warning: `references/updating.md`. Never stash, reset,
  force or merge to make an update apply; give the PI the consequence, never the warning.
- New vault, node prose rules: `references/vault.md`. Verbs, and the removed ones:
  `references/verbs.md`.

## Router

Hand an agent the engine-built brief named here, never your own summary of the node.
- **crux-wrap**: `/crux-wrap`. Capture this session, show what was recorded, ask about each
  pending candidate.
- **crux-capture** (agent): run only by `/crux-wrap` and the session-start sweep.
- **crux-prerun** (agent): before compute on a hypothesis whose expectation, null or checks
  are missing. Pass `crux brief <hid> --json`.
- **crux-situate** (agent): the PI asks where things stand. Pass `crux brief <node>
  --mode=situate --json`; the answer is chat only.
- **crux-migrate** (agent): an existing research repo to reconstruct as a seed.
- **crux-autopilot**: the PI wants an unattended search against a scorer.
- **crux-wiki**: ingest a paper, or ask what the literature says.
- **crux-litsearch**: find the papers the wiki is missing.
- **crux-cockpit**: the PI wants to see the vault in a browser.
- **prezit**: slides from a question and its subtree.
- **storify**: a short private paper from a question or hypothesis.
- **crux-rd**: the PI says a design has settled and wants it written down.
- **evolve-crux**: change crux itself: its engine, its CLI or its skills.