MarginCI

Adopting MarginCI in an existing repository

If the default branch predates your wrapper or workload, it cannot execute the same operation yet. MarginCI refuses the comparison before any provider request. It never copies candidate application code, wrappers or workload into the baseline.

  1. Make a setup-only branch. Install the locked CLI, run init, expose the real operation and configure cases, success, provider/model, rates, credentials, threshold and spend guard.
  2. Declare wrapper, success-check helpers and external workload files in comparison_files. Keep application implementation files out of that list so implementation changes can be measured. Inputs embedded in config are shared automatically.
  3. Commit the setup. Required tracked files are package.json, the selected lockfile, marginci.yml, .gitignore, marginci/research.cjs and declared workload/helper files. Only generated .marginci/ and node_modules are ignored. Never put required comparison inputs under .marginci/.
  4. Run ./node_modules/.bin/marginci doctor research --against HEAD, then ./node_modules/.bin/marginci test research --against HEAD. This measures the setup commit against its current working snapshot, using paid providers if so configured.
  5. Land the setup commit before enabling the economic required check. A setup PR against a baseline that lacks the harness will return ERROR, not PASS. Review/merge setup through the repository’s separate adoption policy; do not mark the unavailable economic comparison approved.
  6. On the next application-change branch, fetch history and run the comparison against a baseline that includes setup. In CI, use the PR’s immutable base SHA. Locally, origin/HEAD is the default; if that ref is absent, use --against <commit> or establish the remote HEAD through your normal Git workflow. No default branch name is assumed.

Example after you have defined the operation:

git add package.json package-lock.json .gitignore marginci.yml marginci/
git commit -m "Set up MarginCI research workload"
./node_modules/.bin/marginci doctor research --against HEAD
./node_modules/.bin/marginci test research --against HEAD

Changes to declared frozen files must land as a new setup/workload revision before comparing application revisions. Dirty, untracked, ignored, candidate-only, missing or inconsistent frozen files are ERROR. Changing workload/config cases deliberately changes the question: candidate cases/config are frozen and shared across both sides, and their identity is recorded. Review workload changes separately from economic gate approval.

Config itself and the CLI installation need not historically exist in the baseline under the engine’s existing policy: the running CLI shares candidate config. The canonical procedure commits them with setup for repeatability. The baseline must contain the executable entry point and every declared frozen file. Dependency metadata and application modules stay revision-owned.