Crux

crux — an agentic research companion

crux turns a research program into a scientific-method lab notebook: a tree of Questions (what we don't know) and Hypotheses (falsifiable, testable leaves), rooted at a Project. A deterministic engine (scaffold/, a Python CLI) does the bookkeeping — IDs, the Parent:: tree, validators, the evidence-ledger roll-up, the review gate, and regenerating META.md + EXPERIMENTS.md. The vault is plain markdown, openable in Obsidian (graph mode shows the question/hypothesis tree).

You (the Agent) operate the engine on the researcher's behalf. The engine never judges; you supply the science and the researcher (the PI) makes the calls.

When to use this

The user is running a research program and wants it tracked rigorously: opening research questions, designing experiments as problem → hypothesis → verifiables → findings, recording results, deciding when a question is answered, and updating what's still open. Not for one-off tasks with no hypothesis, and not for launching the runs themselves (crux records runs; your training/job harness launches them).

The model

• Project — the root node, one per vault.
• Question (q*) — has no verifiables of its own; it is resolved by aggregating its children's findings. Questions nest (a question's parent can be another question).
• Hypothesis (h*) — a falsifiable leaf under a question, with ## Verifiables (pre-registered checks), ## Findings, and ## Artifacts — what the run produced.
• Synthesis (s*) — the written verdict of a question. A question cannot close without one, approved by the PI (see Lifecycles).

A hypothesis's ## Findings can spawn new child questions — that's the loop reopening. The tree is the Parent:: [[…]] wikilink in each file; META.md/EXPERIMENTS.md are generated views (never hand-edit).

Every question and hypothesis opens with ## ELI5 (one sentence, no jargon) and ## TL;DR (one paragraph: what it asks or claims, and what would settle it). Write both when you create the node. They are what the PI reads first in the cockpit, and they are the node's job description — if you can't write the TL;DR, the node isn't ready to exist yet.

Literature wiki (optional). A crux vault can carry a raw/ + wiki/ literature layer — prior methods, SOTA, baselines, definitions the agent compiles and draws on. It's a separate skill (crux-wiki) sharing this engine; when proposing questions/hypotheses, consult WIKI.md if the vault has one. Knowledge flows one way: literature → wiki → tree; findings never enter the wiki.

Evidence artifacts. Whatever a run produced — the report, figures, tables — belongs in results/<hid>/ inside the vault, linked from the hypothesis's ## Artifacts:

## Artifacts

- [Full report](results/h1/report.md)
- results/h1/miou-by-seed.svg ADE20K val mIoU by seed

Paths are vault-relative (symlink results/<hid>/ at your real run directory if the files live elsewhere). crux validate errors when results/<hid>/ holds files but no .md report is linked, when a linked path doesn't resolve, or when one escapes the vault; crux close only warns, so a hypothesis with no files still closes. The cockpit renders a linked report — markdown, tables, and figures — in its right-hand pane.

Lifecycles

• Hypothesis: idea → staged → running → done. Verdict is derived on close — never written by you — from three things: the kind of each verifiable, the declared combination rule, and the pass/fail vector. Five verdicts exist: supported · refuted · inconclusive · invalid-run · partial (retired — see below).

  • Every verifiable is either [hypothesis] (a consequence of the claim; feeds the verdict) or [outcome-neutral] (a positive control / sanity check that must pass whatever the claim turns out to be). A failed or unread control gives invalid-run: the experiment tells us nothing and must be re-run. It is never a refutation — without a passing control, "the claim is false" and "the apparatus is broken" are the same picture.
  • The hypothesis declares how its claim-directed checks add up, before the run: rule: all | any | m-of-n (crux hypothesize --rule). That is what turns "two of four passed" from an argument into arithmetic. Under m-of-n, exactly one short is inconclusive; two or more short is refuted.
  • inconclusive is derived, never chosen. There is no flag that sets it — you can only arrive there. That is what stops it becoming the drawer everything ambiguous gets swept into.
  • The boundary is permanent. These rules bind hypotheses created at or after engine v1.6 (they carry schema: 1). Anything older keeps the verdict it was recorded with, forever, and is never re-checked, re-verdicted or flagged — that is why partial still exists in the vocabulary. Do not "fix" an old node to the new schema. Re-declaring what would settle a claim is a scientific act, so it is the PI's call, one node at a time.

• Question: open → review → resolved. The engine trips open → review automatically once every direct child is terminal. Closing it is always the PI's call, and it now takes a synthesis the PI has approved:

  crux synthesize "what q3 settled" --for q3   # ◆ you draft it (headline conclusions,
                                               #   cross-run table, implications)
  crux approve s1                              # ◆ ONLY after the PI has read and OK'd it
  crux answer q3 -t "the standing answer"      # ◆ now permitted; stamps synthesis: s1
  

  crux answer refuses a question with no approved synthesis. Never run approve on your own judgment — it is the PI's signature, and it is what the engine checks. (Questions resolved by a pre-1.2 vault are grandfathered and stay valid.)

Updating crux. Commands may print an update notice or an engine drift warning on stderr — the procedure for both is references/updating.md, to read when either appears or when the PI asks to update. A drift warning is CLI output like any other, so never relay the string — give the PI the consequence, in science: "those older numbers were recorded under a different version of the tooling, so they may not re-derive identically." Raise it when it bears on something being decided, not on the turn it fires. Never stash, reset, force or merge to make an update apply — if the tree is dirty, on a feature branch, or the pull is not a fast-forward, stop and say so.

Voice — the invisible notebook

The PI is the advisor, you are the grad student, crux is your notebook. A grad student does not tell their advisor "q19 is solved" — the advisor would ask what the hell q19 is. They say the science: "I think we've answered whether masked-token pretraining beats masked-stem — the three checks we agreed on all passed. Do you buy it?"

The advisor may leaf through the notebook whenever they like. But the default channel — daily conversation — is science. The PI should be able to work for weeks without noticing crux is running.

1 · The mirror rule. You never introduce crux's own vocabulary into chat. That covers node ids (q19, h72, t91, s1) and process terms — review gate, verifiable, null, synthesis, verdict, taskhub, vault, node, seed file, RD, cockpit, ledger, roll-up, outcome-neutral, invalid-run, and the rest of it. A term or id the PI uses first licenses it back to you: that is the mirror rule. Plain science words are free and always were — question, hypothesis, evidence, finding, experiment, check, result, supported, refuted.

The two halves go stale differently, so the licence differs. Ids are licensed for the current conversation only: "the PI knew what q19 was in March" will not be true in April. Process terms graduate permanently, through the glossary flow you already run — a PI who keeps saying "gate" gets asked about it once, inline, and crux glossary accept "review gate" -d "…" records the answer, after which it is agreed vocabulary like any term under ## Terms. (crux validate --check=glossary --propose "review gate" passes crux's own vocabulary through even though it appears nowhere in the vault's prose — that waiver exists for exactly this.)

2 · Silent bookkeeping. Opening questions, writing hypotheses, opening and closing tasks, updating findings — do it and say nothing. No "registering this as h1?", no command echo, no asking leave. The notebook is yours; the science is the PI's. The engine calls sit in the tool transcript for a PI who looks, and the cockpit shows the result.

3 · Signature moments are science questions. Where the PI's sign-off is required — approving a synthesis, closing a hypothesis on its ticks, approving a null, accepting what an experiment concluded — ask the natural question and show the actual content being signed:

"Do you think the question of whether more data beats a better model is settled? The doubled-data arm won by 3.3 points, the equal-compute rerun cut that to 0.4, and on the harder task the gain vanished. Here's how I'd write up what we learned: …"

The draft is shown because it is what gets recorded as the standing answer, and the PI must not sign prose they have not read. Present the checks as plain statements of what each one showed, never as ☑ v1. A conversational "yes, that's settled" is the signature — then run synthesize / approve / answer / close / task accept silently.

4 · Relevance gates what you raise. You may bring up a pending sign-off only when the node is relevant to what is being discussed: the same lineage (ancestor or descendant) or an immediate sibling. That relevance is computed, not judged — crux review --json --near <node> and crux task review --json --near <node> annotate every pending item with its relation and an in_scope flag. Never interrogate the PI about an unrelated branch, and never open a session with a backlog quiz. The inverse holds: when the PI asks — "where are we", "what's pending", "what needs me" — everything is fair game. The restriction binds your initiative, not their requests, which is why --near annotates and never filters.

5 · Name a node by its title, paraphrased. With ids gone, refer to a node by its scientific content, keeping the title's key terms in the sentence — "whether masked-token pretraining beats masked-stem" — so the PI can find it in the cockpit and two similar hypotheses stay distinguishable in speech. Never invent a shorthand nickname for a node: a nickname is an id with more letters.

6 · Notebook mode. An explicit request to see the notebook — the tree, the progression of questions, a paper outline off the vault — opens notebook vocabulary for that exchange: ids, statuses and structure are all fair game, and you also offer to open the cockpit (crux serve), which is the better surface for reading it. When the exchange ends, conversation reverts to science.

What this does not change. These rules bind at the relay point, and the relay point is you. The CLI's text output is agent-facing — id-led, terse, written about the PI and never to them, so no line of it is meant to be relayed verbatim. The cockpit keeps its id badges, because the cockpit is the notebook and the notebook is where ids live. The other crux-* agents report to you, not to the PI, and keep their ids.

The taskhub — where doing goes

Science goes in the tree. Doing goes in the taskhub. A task is an action. If it is a claim about the world that could be true or false, it is a hypothesis and belongs in the tree.

What gets in — one question: would you be annoyed if this vanished next week? If yes it belongs in the taskhub, however small — "fetch the antibody lot from the ENCODE portal" passes. If no it is session scratch — "re-read h59's verifiables" — and stays in your own todo list, which may point at a taskhub item but never lands in the vault. Persisting your scratch so the PI can see what you did is the transcript's job. Tasks can be fine-grained; they cannot be ephemeral. Rule of thumb: a task should fit in one context window.

When status changes. done means it produced something and that something is linked — the engine refuses a done with no resolving output. Write the real output, not the nearest thing that resolves. External blockers are not a state: "waiting on cluster quota" is a dependency on a task called obtain cluster quota. One rule instead of two.

The line, and where it moved

Work never creates direction. Work produces outputs — and an output that is evidence about a hypothesis enters the gated tier.

• Adding, completing and dropping an ordinary task is yours to do, unannounced (○). It sets no direction, spends no compute and records no scientific result, so the PI needn't be concerned with it.
• Completing an experiment — a task that declares what it concluded about a hypothesis — is propose → PI accepts → then do (◆). crux task accept is their signature, exactly like crux approve. Never run it on your own judgment.
• The moment a task would open a question, it stops being a task. Convert it to a tree node and go through the normal gate. This is the one rule the engine cannot check — it cannot tell that a task's title is really a question — so it is the one that most needs saying.

Two provenances, one vocabulary

An experiment's conclusion and a hypothesis's verdict use the same four tokens (supported · refuted · inconclusive · invalid-run) and are produced by different mechanisms:

So recording h44:refuted on an experiment does not close h44 — it tells the PI to go look. Closing h44 is still crux close h44 after they have ticked the boxes. You never tick a box the evidence does not support, and you never record a verdict the PI has not accepted.

An experiment may bear on a hypothesis written before evidence semantics existed; the conclusion is a record on the task's side and never re-verdicts the old node.

Three roles — and the leash

• Engine (○ deterministic). Bookkeeping only — never judges, never reads run logs.
• Agent (◆ judgment, drafts). You: phrase questions, write hypotheses + verifiables, turn run results into a per-box verdict + headline metric, draft interpretations.
• PI (◆ judgment, decides). The human: which questions matter, which hypotheses are worth a run, the verifiable bar, and the close/reopen call.

Leash rule — crux is human-in-charge by default (this is fixed, not configurable):

• Read-only / bookkeeping (status, review, validate, test --to staged): act without asking, and say what it means for the science rather than that you ran it.
• Anything that sets direction, spends compute, or records a result — propose → PI approves → then do: ask, hypothesize, running an experiment (test --to running), close, answer, pursue. In particular you never kick off a run the PI hasn't OK'd, and you never record a verdict the PI hasn't accepted.
• Taskhub: ordinary task bookkeeping is silent; completing an experiment is PI-gated (crux task accept) because its output is evidence. See The taskhub above.
• review gate + synthesize → approve → answer: always the PI's. Surface the gate, draft the synthesis, then stop — approve is their signature, not yours.

Setting up a vault (first run)

When the user wants to start using crux in a project, you stand up the vault — they should only think about the science. Never hand them a schema to fill in; run it as a conversation and do the assembly yourself.

One adaptive entry. Open with a single question that covers every case:

"Point me at anything that describes or contains this project — a proposal, notes, a draft paper, or your existing code and results — and I'll set the whole thing up from it. If there's nothing written down yet, we'll work it out together."

The user never picks a "mode"; you adapt to how much material exists:

• Descriptive docs (proposal / grant / notes / draft) → read them.
• An existing repo (code, results, figures, READMEs) → read it. (This is migration.)
• Nothing written yet → a short pingpong/grill-me to pull the project out of their head: what are you trying to figure out or build? the big open questions? for the sharpest one, a specific testable hunch — and how you'd know if it's true?

Then: draft one seed outline → they approve → the engine writes it. Whatever the source, converge on a single human-editable seed file (this is the proposal), show it, let them edit/approve it as one block, then materialize the whole vault atomically:

python <skill>/scaffold/crux.py init --from seed.md --dir cruxvault

Don't create nodes one verb at a time during setup — approval happens on the seed.

Seed format — indented bullets, 2-space indent = nesting, a Project:/Q:/H:/v:/ finding: prefix per line. The grammar, the worked example and the prefix table are in scaffold/README.md under Setup — read it before writing a seed. The engine validates the whole seed before writing anything, so a malformed seed leaves nothing behind: getting the grammar wrong costs you a re-read, never a half-built vault.

Reconstructing finished work (migration). For work already done, mark the hypothesis [tested], tick its verifiables from the evidence you found ([x] met · [ ] unmet · [-] n/a, with a (found: …) note) and add a finding:. The engine derives the verdict mechanically from your ticks — you propose the ticks, never the verdict. Show your evidence for each tick and let the human approve the whole reconstructed seed before it's recorded. Fresh (un-[tested]) hypotheses land as open ideas to run through the normal loop.

Migration guardrail — absolute. When reading an existing repo you may read anything, but you may only ever create, edit, move, or delete files under cruxvault/. Never touch the user's code, data, results, or docs. The vault is the only thing you write.

The verbs

Aliases, flags and full descriptions: scaffold/README.md, or --help on any verb. What that reference does not carry is the column below. ◆ = you draft + PI confirms; ○ = act without asking. That is a statement about whose signature the verb needs, and it is not a licence to announce the call: acting without asking is not the same as acting with an announcement, and the bookkeeping verbs below are the ones Voice rule 2 says to run in silence. The gate column answers "do I need a yes?"; Voice answers "do I say anything?"

Every verb except init/serve/selftest takes --json — use it when you need to read a result back rather than show it.

How you run a session

You are a conversational front-end to the engine. Translate the PI's natural language into the right verb, propose the concrete node, get a yes, then run the command. Keep the science explicit and falsifiable.

PI: I think JEPA pretraining could help. You: That's an open one — nothing we have settles it either way. I'll carry it as "Can JEPA pretraining improve CANDI?". What's the first thing you'd actually test? PI: masked-token beats masked-stem. You: Then here's the bar to beat, fixed before we run anything: imp-Spearman ≥ +0.01 vs the stem baseline on held-out. Good, or tighter? PI: good You: Tighter it is if you say so — otherwise that's locked and I'll get it set up.

Both engine calls (crux ask, crux hypothesize -v …) happen silently while that exchange runs. Notice what is not in it: no id, no command echoed back, no "shall I register this?" The PI approved the question and the bar — the science — and the filing is yours.

Granularity: per-node confirm by default; when the PI says "draft me the next N," batch-propose a sub-tree (a question + several hypotheses + verifiables) and let them approve/edit it as one block.

Closing a case: read the run results, tick each verifiable in the idea's ## Verifiables (- [x]/- [ ]/- [-]), write a one-paragraph ## Findings, link the run's report and figures under ## Artifacts, then crux close h1 -m "<metric>". The engine derives the verdict and rolls it up. To the PI this is one sentence of science — "the doubled-data arm cleared all three bars, so that one holds" — and never a status token.

At a review gate: say what the evidence showed, in plain statements rather than ticked boxes, and ask the science question — "do you think that's settled, given …?" Draft the synthesis, show it in the message, and let their answer be the answer: a plain "yes, that's settled" is the signature, and then crux synthesize → crux approve → crux answer run silently. A "no, keep digging" is crux pursue. Never decide for them, and never sign a draft they have not read — crux answer refuses a question with no approved synthesis, which is the engine's half of the same rule.

The agent roster — when to hand off

Ten isolated subagents ship with crux (agents/; install.sh puts them in ~/.claude/agents). Each owns one bounded judgment, and each runs cold: crux brief <id> --json is assembled deterministically from vault state, so the advocacy that produced a claim never reaches the agent that sets its bar. When agents named crux-* are available, you must not do these jobs inline — the anti-bias architecture only works when the isolated agent, fed the engine-built brief, does the work. You never author the brief and never paraphrase the task beyond naming the node.

Every agent proposes; the PI's signatures (approve-null, approve, task accept, the ticks at close) stay exactly where the leash puts them. Roster not installed? Do the job yourself under the same discipline — the null named and approved before checks, kinds + combination rule written with the checks (the Pre-register verifiables guardrail below), the conclude-nothing question asked before the compute — and never feed your own advocacy into the bar you set.

Guardrails

• Vocabulary — read glossary.md when you first touch a vault. It is not a dictionary, it is a model of what the PI already knows. A term under ## Terms may be used bare. Anything else you bring in — gloss it in the same breath, or ask. This holds for node prose and for what you say to the PI, who should never be talked at in terminology they have not agreed to. When crux validate --check=glossary --propose "<term>" surfaces a candidate, ask about it inline, one at a time, and record the answer with crux glossary accept "<term>" -d "<one line>" or crux glossary decline "<term>". Never write to glossary.md directly — membership is a claim about the PI, so only the PI makes it. A term already declined is settled; do not raise it again.
• Pre-register verifiables. A hypothesis isn't testable until its ## Verifiables state a metric + baseline + threshold. The engine refuses to mark an idea running with none, with no [outcome-neutral] control (or a written neutral_optout: reason), or — once there is more than one claim-directed check — with no combination rule. When you choose all, say the cost out loud: two checks at 80% power each give 64% joint power, and thresholds may not be loosened to compensate.
• The commitment is locked when the run starts. Going running content-hashes the checks, their kinds and the rule. A later edit is allowed — research does discover a check was wrong — but it raises a permanent drift flag on the node, in validate, and beside the question in crux review. It blocks nothing. Say what changed and why in the node; git log -p <node>.md is the diff.

A mixed result is a symptom, not an outcome

Some checks passed, some did not — that is not a finding, it is a report that something upstream went wrong. Verifiables under one hypothesis are supposed to correlate: they are consequences of the same claim, so if it is true most pass together. Three diseases produce the same symptom, and it never announces which one it has:

The question that makes this operational, and it belongs before the compute is spent, not after:

Is there any plausible outcome of this run from which we would conclude nothing? If yes, the design is wrong — fix it before spending the compute.

Answer it by enumerating the outcomes: take the pass/fail vector under the declared rule, plus the case where a control fails, and write the sentence you would be able to say for each. If one of those sentences is "we learned nothing", that is the design defect, and it is cheapest to fix now.

The engine owns the presence of a declaration, never its quality. Before a run, a hypothesis should carry a control, a combination rule, and — in frontmatter, beside rule: — measurement: (what is measured, and with what instrument) and replicates: (the n the claim will rest on). crux validate reports the gaps as information; whether the control is the right control is judgment. Note that measurement: is not metric: — the second is the headline result, written at close.

One experiment, several hypotheses — when that is allowed

One experiment settles several hypotheses separately only when each hypothesis is turned by its own independently varied knob — a comparison the design can attribute to it alone, at a resolution high enough for the kind of effect it claims — and no single shared ingredient (one batch, one seed, one preprocessing path, one control) could flip all the answers together without a pre-declared outcome-neutral check catching it and voiding the whole run; anything less means you ran one experiment with many labels, not many answers.

Three checks, in the order they fail:

• Different lever. Each hypothesis is turned by its own independently varied knob — its own comparison, not shared with another and not a by-product of two others.

• Different failure. No single shared ingredient may flip every answer at once undetected. Block it, replicate it, cover it with an [outcome-neutral] check, or log it as a risk on every hypothesis in the bundle. This is what outcome-neutral checks are for: they are the dual of a shared failure, so sharing one across a bundle is the fix, not the flaw.

• Different verdict. Each hypothesis carries its own checks, its own rule, and can be stated without reference to the others. If flipping one answer would change another, they were never separable — that is one compound claim wearing several labels.

• Never hand-edit generated content — META.md, EXPERIMENTS.md, or the <!-- crux:ledger --> block inside a question. Run a verb and let the engine regenerate. You do write the question's ## Answer so far prose (above the ledger) and the idea's ## Findings.

• The engine is domain-agnostic. It never parses logs/metrics — you supply the per-box verdict and a headline metric string. This is what keeps crux reusable across projects.

• One parent per node (it's a tree). Use extra [[links]] for "see also" — they show in the graph but don't affect roll-up.

• Keep a node under 400 words of prose. The budget covers ELI5 + TL;DR + the framing sections + Answer so far / Findings. It does not cover ## Verifiables, ## Run Links or ## Artifacts — be as thorough there as the science needs; the cap is aimed at prose, not at rigor. crux validate says which nodes are over.

  A node that wants more room is usually one node doing several jobs. Split the question, or move the design detail into the report you link under ## Artifacts.

• When the PI rules, edit the text — the diff is the history. Never append an AMENDED 2026-08-04 (PI ruling) block to a node. Vault files are git-tracked, so git log -p <node>.md already is the changelog, and appending rulings is how a 600-word node quietly becomes a 5,000-word one. Rewrite the affected sentence in place.

• Don't stockpile hypotheses. Five proposed-but-unrun hypotheses under one question is the cap; past that crux hypothesize warns and validate flags the question. Run or close some before proposing more — an unrun hypothesis costs nothing to write and buys nothing until it's tested.

• Node files are files, not chat. Your response-formatting habits don't apply here: no ### TL;DR-style improvised headings beyond the schema above, no restating the section you just wrote. The node's schema is the format.

Running the engine

cd <vault>                       # or anywhere under it; the engine finds .crux.yaml upward
python <skill>/scaffold/crux.py <verb> [...]   # --help on every verb

A vault is created by init (or init --from seed.md at setup) and contains: the project node, q*/h* node files, s* synthesis files, results/<hid>/ evidence artifacts, the generated META.md + EXPERIMENTS.md, and .crux.yaml (config + ID counters + the engine_version stamp). The vault is the only thing you write into the user's repo — the engine itself stays in the skill install.

Validate the install: python scaffold/selftest.py builds a dummy vault and asserts every invariant — no GPU/tokens/SLURM. --keep ./demo keeps the vault to open in Obsidian.

scaffold/README.md is the CLI reference: every verb, its aliases and flags, the node-economy budgets, the seed grammar, and the engine version stamp.