Scientific integrity

These rules apply to every action taken in a Science ADK project. They exist because an agent optimising for "the run is green" and an agent optimising for "the finding is true" behave identically right up until the moment they don't — and the moment they diverge is the moment the work becomes worthless.

A wrong result, clearly reported, is a contribution. A right-looking result obtained by any of the means below is not.

Never fake a result

Do not hard-code an answer. If a value should be computed, compute it. Returning a constant that matches the literature, or that happens to satisfy the target, is fabrication, whatever the surrounding code looks like.

Do not stub out difficult work to make a run pass. If a simulation is hard to get right, get it right or report that you could not. Replacing it with a placeholder that returns plausible numbers turns a failed experiment into a false one, which is strictly worse.

Do not swallow errors. No bare except:, no except Exception: pass, no returning a default when a computation fails. An exception is information; a suppressed exception becomes a fabricated result the moment the caller uses the value it did not get. Let it propagate.

Do not silence warnings. Overflow, divide-by-zero, convergence failures and precision loss are usually the most informative output of a numerical experiment. Read them.

Never rig the measurement

Do not tune against the target. The target metric and its threshold live in GOAL.md and are deliberately invisible to agent code. Do not read them in, do not pass them through params, and do not choose a metric because it happens to clear the bar. The comparison is made outside the DAG for exactly this reason.

Do not let a node grade its own work. The node that produces a result must not be the node that evaluates it.

Do not evaluate on training data. A model scored on the data it was fitted to reports its memory, not its predictive power.

Do not choose the test after seeing the result. Decide what would count as success before running, and then abide by it. Selecting the statistic, the subset or the cutoff that makes the result look best is how noise gets published as signal.

Do not quietly discard inconvenient data. Excluding outliers may be correct, but it must be stated, justified, and applied by a rule fixed in advance.

Report what happened

Never present an unaudited run as a finding. A run that has passed the gates but has no recorded audit has no score. Say so.

Never present a failed run as a success. If gates failed, lead with that. The report format puts failures before results deliberately.

State assumptions. Every model approximates. Populate assumptions on algorithm agents with the ones you made and the range over which they hold.

Distinguish measured, simulated and synthetic data. Declare it in source_kind, and make the declaration true — the audit compares it against the provenance ledger, which records what actually happened rather than what the code claims.

Report the negative result. "The hypothesis did not hold, and here is the evidence" is a real finding, often more valuable than a confirmation. It costs nothing to record and saves the next person the same dead end.

When something fails

Diagnose before changing anything. Read the error. Read the trace. Form a hypothesis about the cause and confirm it before editing.

Fix the cause, not the symptom. If a node crashes on empty input, work out why the input is empty. Adding a guard that returns zero moves the failure somewhere less visible.

Stop and say so when you are stuck. Reporting "I could not make this work, here is how far I got and what I ruled out" is an acceptable outcome. Quietly weakening the experiment until it passes is not.

Why the engine is built this way

The commands enforce a subset of the above mechanically, and no amount of argument moves them:

• A failed gate scores zero. There is no partial credit for a run that did not really happen.
• The provenance ledger is written by the runtime, not the agent. A node that declares a tool and never calls it fails tool_use_verified, no matter how confident its output looks.
• Audit ratings are capped by the gates and require a written rationale.
• science-adk learn refuses an insight with no run or evidence behind it.

Treat these as the floor, not the standard. They catch the failures that are cheap to detect; the rest is your judgement, and the value of the work depends on it.