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).

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 from the verifiable checkboxes: all - [x] → supported; any unmet → refuted/partial; only - [-] (couldn't-evaluate) remaining → inconclusive.

• 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. Any crux command may print crux: vX.Y.Z is available … on stderr (once a day, from a cache — it never blocks and never installs anything). If the PI asks you to update:

1. A clone install (the notice names it — git -C <root> pull --ff-only): check the tree is clean and on the default branch first (git -C <root> status --short --branch). If it is dirty, on a feature branch, or the pull is not a fast-forward, stop and say so — do not stash, reset, force, or merge to make it apply.
2. A skills install: npx skills update.
3. Then tell the PI to re-run their command; the new engine takes effect on the next invocation, not the one in flight.

A newer engine may carry a newer vault format. The first command against an existing vault will warn about engine drift and re-stamp it — surface that warning verbatim; if the PI needs to reproduce recorded results exactly, the answer is to pin the old engine, not to ignore the warning. CRUX_NO_UPDATE_CHECK=1 switches the whole check off.

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, then report.
• 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.
• 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/results — and I'll draft your crux setup from it. If there's nothing to read yet, we'll define it 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 (full table in scaffold/README.md) — indented bullets, 2-space indent = nesting, a type prefix per line:

- Project: TITLE — GOAL
  - Q: an open question
    - Q: a nested question
      - H: a hypothesis to run
        - v: metric ≥ threshold vs baseline
      - H: [tested] work already done          # migration only
        - v: [x] a met check (found: 0.46 → 0.48)
        - v: [ ] an unmet check
        - finding: one-line result

The engine enforces the model: exactly one Project; Q under Project/Q; H under a Q; v/finding under an H. It validates the whole seed before writing anything, so a malformed seed leaves nothing behind.

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

Run them via the engine CLI (see scaffold/README.md). ◆ = you draft + PI confirms; ○ = act-and-report.

verb	aliases	role	what it does
init	start, new	○	bootstrap a vault (--from seed.md = materialize a whole tree; see Setup)
ask	question, q, meta	◆	open a Question under the project or another question
hypothesize	hypothesis, idea	◆	add a hypothesis under a question — register -v verifiables
test	experiment, run, stage, launch	◆	idea → staged → running, attach a run link — running needs PI's OK
close	record, conclude, verdict, land	◆	derive verdict from verifiables + write findings → roll up
review	gate, decide	○	list questions awaiting the PI's decision
answer	resolve, settle	◆	PI resolves a question — requires an approved synthesis
pursue	branch, extend, reopen	◆	keep a question open; optionally spawn a fresh hypothesis
status	map, tree, where, show	○	print the tree / a node's ledger
synthesize	weave, rollup	◆	draft the synthesis that closes a question (--for q3), or weave several
approve	sign-off, signoff	◆	the PI's signature on a synthesis — never run this on your own judgment
ingest	source, add-source	○→◆	register a PI-curated raw/ source into the literature wiki (then compile pages — see the crux-wiki skill)
serve	gui, ui, cockpit	○	open the read-only browser cockpit (localhost; view-only — tree, review gate, rendered reports + figures; launch playbook: the crux-cockpit skill)
validate	lint, check	○	integrity checks (tree + wiki structural lint)

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 a Question (no single verifiable). Open it under the project as "Can JEPA pretraining improve CANDI?" — yes? PI: yes You: → crux ask "Can JEPA pretraining improve CANDI?" (q1). First hypothesis under it? PI: masked-token beats masked-stem. You: Verifiable bar — I'd set imp-Spearman ≥ +0.01 vs the stem baseline on held-out. Good, or tighter? PI: good You: → crux hypothesize "masked-token beats masked-stem" -p q1 -v "imp-Spearman ≥ +0.01 vs stem"

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.

At a review gate: present the question's ledger and your read of the evidence, then let the PI choose answer (resolve) or pursue (keep digging). Never decide for them. If they resolve it, draft the synthesis (crux synthesize "…" --for q3), show it, and wait — crux approve is theirs, and crux answer will refuse until it's signed.

Guardrails

• 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.
• 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.

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. On a version mismatch the engine warns about drift and re-stamps; surface that warning to the PI.

Validate the install: python scaffold/selftest.py builds a dummy vault and asserts every invariant (roll-up, gate, idempotency, integrity, CLI help) — no GPU/tokens/SLURM. Add --keep ./demo to keep the vault and open it in Obsidian.

scaffold/

crux.py (CLI) · engine.py (model, validators, ledger, gate, transitions) · render.py (generated views) · templates/ (node skeletons — editable) · selftest.py · README.md (CLI reference).