AGENTS.md — experiments

Temporary subtrees outside the main quality bar. Each owns its gate; none is in check-all.

An experiment consumes the monorepo's packages to answer one empirical question, then gets promoted or deleted. README.md states the policy and how to add one. This file is what an agent needs when working inside an experiment: what isolation means here, and which gate actually runs.

Map

Diagram

flowchart TD
  accTitle: how an experiment relates to the repository gate
  accDescr: The root check-all target covers the packages only; each experiment owns a separate make check that the root never invokes, and a promoted experiment leaves as a package or an ADR.

  ROOT["make check-all<br/>root plus five packages"]
  PKG["the packages"]

  subgraph EXP["experiments/ (you are here)"]
    BV["backend-validation<br/>make -C ... check"]
    TA["trace-analytics<br/>make -C ... check"]
    SIGN["PROBES.yaml sign-off<br/>stops until a human signs"]
  end

  OUT["promoted to a package or an ADR,<br/>or deleted"]

  ROOT --> PKG
  PKG --> BV
  PKG --> TA
  BV --> SIGN
  BV --> OUT
  TA --> OUT

  classDef here fill:#e8f0fe,stroke:#1a73e8,stroke-width:2px
  class EXP here

Rules that bite here

• Nothing here is in make check-all. The root gate will stay green while an experiment is broken, so run the experiment's own gate yourself. That isolation is the point, not an oversight.
• The dependency arrow points one way. An experiment may depend on the harness and the packages; the root and the packages must never depend on an experiment. An experiment that something imports is a package, and should be promoted rather than imported.
• Zero writes outside the subtree. backend-validation has a PR-scoped isolation check for exactly this, and trace-analytics states it as an invariant.
• trace-analytics deliberately has no pyproject.toml. A manifest there would pull in dependency and coverage obligations the experiment does not have. Do not add one to make tooling happy.
• Keep README.md's experiment table in sync. Both backend-validation and trace-analytics must appear there when present on disk; add a row when you introduce an experiment rather than leaving the index to drift.
• Live probes are sign-off gated. backend-validation's preflight phase stops with a distinct exit code until a human sign-off file exists. Do not route around it.

Verify

make -C experiments/trace-analytics check
make -C experiments/backend-validation check

Subagents

See also