researchforge-plan

Plan experiments

You author the plan and patches; the engine validates every layer before anything can run. One plan targets one hypothesis.

1. Export planning context

researchforge experiment plan <hypothesis-id> --json

This writes .researchforge/experiments/context.json: the hypothesis, the approved contract (metric, constraints, editable and protected paths, limits), baseline metrics, repository scan, and the embedded schema for the plan file. Read it fully before writing anything.

2. Write the plan and patches

• .researchforge/experiments/plan.yaml conforming to the embedded schema: hypothesis_id, approach_summary, and one entry per experiment (key, title, change_summary, patch_file).
• One unified diff per variant under .researchforge/experiments/patches/, applying cleanly to the frozen baseline commit.

Hard constraints the engine enforces (do not fight them):

• patches may only touch permissions.editable_paths; a patch touching a protected path is recorded as rejected at import and will never run — never edit benchmarks, evaluation code, or .researchforge/ to make a metric look better;
• changed files are extracted by git from the patch itself, never from your description;
• keep variants small and single-idea: the funnel measures one change at a time;
• to BUILD ON a prior result, set parent: on an entry (another key in this plan or an exp-NNN from the context's prior_experiments) — the parent's patch chain is applied first and your diff must be written against that combined state. A branched child's improvement is still measured against the baseline; report its increment over the parent separately and honestly.

3. Import (engine validates, six layers)

researchforge experiment import .researchforge/experiments/plan.yaml --json

On failure, the --json payload lists exactly what to fix (schema fields, unknown hypothesis, patch that does not apply, protected-path violations). Fix the plan or patch files and re-import.