Keep agent work bounded, auditable, and evidence-backed.

Guardrails

Guardrails are runtime rules that constrain agent output and repo mutation. They live in the target harness, are attached through the manifest, and can be hard-blocking or advisory. For the full YAML schema, matching behavior, secret-scan details, hook behavior, stale-rule rules, and troubleshooting, open the Guardrails Reference.

Rule Authoring

Start with narrow, explainable rules. A useful guardrail tells the agent exactly what was blocked and what a safe next action looks like. The Guardrails Reference documents exact field defaults and matching semantics.

roles:
  engineer:
    guardrails:
      - guardrails/safety.yaml
      - guardrails/conventions.yaml

rules:
  - id: no-hardcoded-secrets
    name: No hardcoded secrets
    severity: hard
    scope: global
    pattern: '(?i)(password|secret|api_key|token)'
    message: Use environment variables or local secret storage.

rules:
  - id: require-tests
    name: New code needs tests
    severity: advisory
    scope: engineer
    message: Add or update tests before asking for review.

• Prefer role-scoped rules when only one role needs the policy.
• Use file_pattern to keep broad regex checks from firing on unrelated files.
• Set realistic stale_days values and review stale rules during doctor.
• Keep secret values, credentials, and private customer data out of rule files.

Secret Scanning

Secret scanning is available as an operator command and as an optional git hook. Findings are redacted and should be treated as blockers until the secret is removed and rotated if necessary. The Authentication And Credentials Reference explains where credential values should live.

mars guardrails secret-scan --repo ~/my-project
mars guardrails secret-scan --repo ~/my-project --json

mars guardrails secret-scan --repo ~/my-project --staged

mars guardrails install-hooks --repo ~/my-project
git commit

Blast Radius And Workspace Hygiene

MARS keeps agent changes small enough to inspect. Built-in policies classify generated output, dependency churn, ticket lifecycle moves, source writes, validation artifacts, and destructive commands before they can turn into confusing repo state.

Trust Levels

Trust controls what roles and external clients may do. Manual overrides are allowed, but they require a reason so the audit trail explains why capability changed. Execution profile is an independent outer ceiling: mutation also requires acknowledged host execution, and target trust cannot grant it.

mars trust --repo ~/my-project
mars trust --repo ~/my-project --db ~/.mars/db/my-project/mars.db

mars trust set engineer ~/my-project contributor \
  --reason "Human approved bounded ticket delivery"

Scores

Scores turn job outcomes into role health signals. They are not vanity numbers; they help operators understand whether roles are delivering real value, stalling, hitting guardrails, or needing self-improvement work.

mars scores --repo ~/my-project
mars scores --repo ~/my-project --db ~/.mars/db/my-project/mars.db

Quality Score Export

docs/QUALITY_SCORE.md is the repo-visible quality artifact. It summarizes score evidence, telemetry, ticket state, dogfood findings, guardrails, check outcomes, no-op signals, human follow-up, convergence failures, and factory pace while preserving manual notes.

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

mars scores export \
  --repo ~/my-project \
  --create-intervention-debt

mars scores export \
  --repo ~/my-project \
  --db ~/.mars/db/my-project/mars.db

mars checks run --repo ~/my-project --name go-test -- go test ./...
mars scores export --repo ~/my-project --window-days 30

Opt-In Aggregate Telemetry

Telemetry is local-first and off by default. When enabled, MARS can preview, enqueue, send, collect, and triage sanitized aggregate reports. Raw target details stay local under the current allowlist; foundation triage works from repeated minimized patterns. The configured anonymous mode does not make the network transport anonymous: the collector and network path can observe ordinary transport metadata.

Operator Recipes

mars guardrails secret-scan --repo ~/my-project --staged
mars docsync audit --repo ~/my-project
mars scores export --repo ~/my-project

mars scores --repo ~/my-project
mars scores export --repo ~/my-project --window-days 14
mars telemetry preview --repo ~/my-project

mars mcp serve \
  --repo ~/my-project \
  --trust observer \
  --allowlist file_read,file_search,grep,git_status

Troubleshooting