MARS Developer docs

Evidence

Record local checks so MARS can use the result.

A local check is a command you already trust, such as a test, build, lint, smoke test, or release gate. mars checks run runs that command and records whether it passed or failed.

When To Use It

Use mars checks run when the result should count as evidence for MARS. Do not use it for one-off exploration.

Use it forDo not use it for
A test command that proves a ticket or fix.Listing files or checking what folder you are in.
A build, lint, smoke, or release check.Commands that print secrets or private logs.
A repeatable command you would mention in a review.Broad discovery commands that do not prove behavior.

Quick Path

  1. Run the check through MARS

    mars checks run --repo ~/my-project --name go-test -- go test ./...

    The command after -- runs inside ~/my-project.

  2. Refresh the quality file if the result matters

    mars scores export --repo ~/my-project --window-days 30

    This updates docs/QUALITY_SCORE.md from the latest score and check evidence.

  3. Commit the quality file when it supports your claim

    Commit docs/QUALITY_SCORE.md only when the change is useful review evidence. The check itself is stored in the local MARS database.

What Happens

The check runs in the target repo

MARS changes into the repo from --repo, then runs the command after --. It does not use a shell unless you ask for one, for example -- sh -c "...".

The output still goes to your terminal

You see stdout and stderr while the command runs. MARS records the result, not the full output.

The result becomes scoring evidence

A passing command records checks_passed. A failing command records checks_failed.

Failed Checks

A failed check is still useful evidence. MARS records it first, then exits non-zero. 

mars checks run --repo ~/my-project --name unit -- go test ./...

If go test ./... exits with code 1, MARS records checks_failed and then returns an error like: 

checks run: command failed with exit code 1
Do not hide failing checks. They help MARS route repair work and stop people claiming a repo is healthy when it is not.

What Gets Stored

MARS stores one row in the scoring database. It does not write a file into the target repo.

StoredNot stored
Check name from --name.Full stdout.
Command arguments.Full stderr.
Exit code and duration..mars/checks/latest.json.
Repo ID, role, and timestamp.Secret values outside the command arguments.

The default database is ~/.mars/db/{repo-name}/mars.db. Use --db only when you intentionally use another MARS database outside the target repo.

Inspect Evidence

Refresh the repo quality file

mars scores export --repo ~/my-project --window-days 30

Use this when you want the check result reflected in docs/QUALITY_SCORE.md.

Look for failed-check repair work

mars serve --addr 127.0.0.1:9091 \
  --execution-profile host --acknowledge-host-execution

When the repo is registered and the role exists, the survey loop can route recent failed checks to pipeline-fixer.

Keep terminal output separately if needed

mars checks run --repo ~/my-project --name go-test-log -- bash -lc 'set -o pipefail; go test ./... 2>&1 | tee /tmp/go-test.log'

MARS stores the result, not the full output. If a reviewer needs the full log, save it separately and keep secrets out of it.

Recipes

Go tests

mars checks run --repo ~/my-project --name go-test -- go test ./...

Node tests

mars checks run --repo ~/my-project --role qa --name npm-test -- npm test

Build check

mars checks run --repo ~/my-project --name build -- npm run build

Shell command

mars checks run --repo ~/my-project --name combined -- sh -c "go test ./... && go vet ./..."

Use a shell only when you need shell behavior such as &&.

Troubleshooting

ProblemWhat it meansWhat to do
--repo is requiredMARS needs to know which repo owns the evidence.Pass --repo /path/to/repo.
--name is requiredEvery check needs a stable name.Use names such as go-test, build, or browser-smoke.
The command after -- is not found.The command is run directly in the target repo.Use the real executable, or use sh -c when you need shell syntax.
mars scores does not show the new result.The check was recorded as an outcome; cached role scores are separate.Run mars scores export --repo ... to refresh docs/QUALITY_SCORE.md.
You need full failure logs later.MARS does not store stdout or stderr for the check.Save output with your own log command and keep secrets out of logs.