MARS Integrations And Validation Guide

Optional surfaces: integrations augment repo-owned work; they do not replace it. Review local and opt-in boundaries before enabling external systems.

Local-First Integration Model

External systems augment the repo-owned operating model. They do not become the system of record by default, and missing credentials should not block source install, local setup, dry runs, or scoped target operation. When configured, GitHub, JIRA, and remote MCP exchange the repository identifiers, issue or work-item content, tool inputs, and results required for the scoped request. Update and model-download workflows likewise contact their configured hosts for the requested artifacts.

Opt-in profiles

Missing or unknown integration config falls back to ceo-led. Board-driven behavior is never inferred from partial config.

Secrets by env-var name

Config stores names such as base_url_env and webhook_secret_env, not secret values. See the Authentication And Credentials Reference.

Mirror before fan-out

JIRA ingestion creates or reconciles local tickets. It does not enqueue LLM work directly from webhooks.

Evidence stays durable

Validation reports, matrix runs, ticket evidence, and release blockers live in repo docs, not only dashboard state or chat.

Optional GitHub Integration

GitHub support is optional. It can verify webhook signatures, deduplicate deliveries, create PRs, create or update check runs, and post comments when configured. It does not replace strict-trunk repo-owned commits as the default delivery model.

Capability	Status	User guidance
PAT and App client modes	Implemented client validation.	Use actionable configuration errors to fix auth mode, token, or base URL issues.
App setup flow	Implemented setup, manifest, callback, and code exchange tests.	Use setup when you want GitHub App credentials rather than PAT mode.
Webhook receiver	Implemented signature, duplicate, method, and size handling.	Use a configured webhook secret and keep unsupported events bounded.
Remote reporting	Client supports PRs, check runs, and comments.	Use remote signals as coordination, not as the only source of truth.
Local-first absent credentials	Required behavior.	Commands should report unavailable integration status rather than fail core local operation.

Separate release auth: mars auth github is primarily for private MARS release assets and binary update. Optional code-host integration uses its own configured credentials.

JIRA Mirror

JIRA ingestion is a mirror, not a direct trigger-to-agent path. A scoped issue can create or update one local Markdown ticket by stable jira_key; the local ticket lifecycle remains the work item that agents deliver.

Map project to exactly one repo

project_repo_map must disambiguate where mirrored tickets belong.
Apply workspace and label scope

Allowed workspaces and required labels prevent broad board content from entering the repo.
Normalize issue fields

Mirrored tickets carry front matter such as jira_key, priority, sprint, rank, status, blockers, and epic.
Preserve target-owned work

Reconciliation updates JIRA-owned front matter and requirements blocks while preserving lifecycle directory, evidence fields, scoped markers, and agent notes.

Atlassian MCP

Atlassian MCP is a job-scoped JIRA read provider. MARS can start an explicit local proxy, probe available tools, call approved JIRA search/read tools, close the session, and then apply the same containment rules before writing local tickets.

Provider detail	User meaning	Safety boundary
`provider: rest`	Use direct Atlassian REST search.	Still needs project, workspace, label, and mapping gates.
`provider: atlassian_mcp`	Use Atlassian MCP tools for scoped reads.	Session/proxy is job-scoped and cleaned up after sync.
`proxy_transport: sidecar`	Start helper while MARS speaks HTTP to the endpoint.	Helper command is explicit config.
`proxy_transport: stdio`	Speak MCP JSON-RPC to a helper subprocess.	Supports OAuth helpers such as `npx mcp-remote`.
Board-aware read tool missing	MARS records `board_scope_not_enforced_by_provider`.	It relies on project, workspace, label, and JQL containment instead of silently widening scope.

# Operator-owned example only; keep tenant values in env vars.
npx mcp-remote https://mcp.atlassian.com/v1/mcp/authv2

Board-Driven Profile

The default target flow is ceo-led. The board-driven profile is an opt-in operating mode for teams that use JIRA as work-order input. Current implementation covers the config substrate and initial JIRA mirror paths; selector, cost guard, Figma, PR delivery, and release-traceability plans are staged work.

Area	Current user contract	Boundary
No config	Falls back to CEO-led behavior.	No JIRA routes, pollers, or board dispatch are enabled.
Profile loading	`.harness/integrations.example.yaml` may be generated; real config is operator-created.	`.harness/integrations.yaml` is never written by default.
Schedule changes	Board-driven suppresses CEO-led planning cron registrations when enabled.	Roles remain available for explicit dispatch.
Tool injection	Future integration tools are appended only when profile, section gate, and registry agree.	No static broad tool grants in generated manifests.
PR delivery	Planned explicit mode.	No force-push, no auto-merge, base remains `main`, and trust gates apply.

Configuration

Integration config belongs to the target harness and should keep tenant-specific identifiers behind environment variable names when operators do not want those values committed.

version: 1
flow_profile: board-driven

ingestion:
  jira:
    enabled: true
    provider: atlassian_mcp
    site_url_env: JIRA_SITE_URL
    cloud_id_env: JIRA_CLOUD_ID
    webhook_secret_env: JIRA_WEBHOOK_SECRET
    scope:
      allowed_workspaces_env: JIRA_ALLOWED_WORKSPACES
      required_labels:
        - example-required-label
      board_id_env: JIRA_BOARD_ID
    project_repo_map:
      DEMO: /absolute/path/to/my-project

delivery:
  mode: trunk

Do not commit raw tokens, board dumps, private issue bodies, or unnecessary personal data.
Use env-var name fields for site URLs, cloud IDs, board IDs, workspace URLs, and custom-field IDs when those are sensitive.
Classify failures as foundation-owned, deployed-owned, mixed/unclear, or evidence-only before creating tickets.

Validation Artifacts

Validation evidence is durable repo documentation. Matrix run reports, clean-project lifecycle reports, release blockers, and target dogfood reports should be inspectable without relying on terminal scrollback. Code-intel metrics and benchmarks can help choose likely files, tests, and docs, but they are not replacement validation evidence; see the Code Intelligence Reference.

Artifact	Location	Use
Reusable profiles	`docs/validation/profiles/`	Target profile, trust level, command list, and graduation criteria.
Agent smoke matrix	`docs/validation/agent-smoke/`	Checked-in cases and generators for compartmentalized role smoke tests.
Run reports	`docs/validation/reports/`	Completed or blocked validation evidence.
Baselines	`docs/validation/baselines/`	Dated factory-pace before measurements.
Release blockers	`docs/validation/release-blockers.md`	Per-version asset, mirror, or publication blockers.
Target dogfood reports	`docs/reports/dogfood/` in target repos	Evidence written during deployed target validation.

Agent Smoke

mars validation agent-smoke creates ephemeral target repos, seeds them through foundation scaffold/tool surfaces, executes selected roles through the server job path, records evidence, and discards successful runs unless told otherwise. It is the fast compartmentalized lane for source maintainers who need to check a role, project type, or dispatch contract without running a whole clean-project lifecycle sweep.

Run it from the MARS source checkout. The command reads docs/validation/agent-smoke/matrix.yaml from the foundation repo. Each generated target gets its own docs/validation/agent-smoke/current-case.md; agents should read that target-local contract, not the foundation matrix.

Rotating fast smoke

mars validation agent-smoke \
  --suite fast \
  --cycle 2026-06-29 \
  --json \
  --report docs/validation/reports/2026-06-29-agent-smoke-fast.md

fast is the default suite. It selects one case per role and uses --cycle to rotate which case is chosen.

Inspect one retained run

mars validation agent-smoke \
  --case static-web-ticket \
  --role engineer \
  --project-type static-web \
  --suite fast \
  --keep-runs

Use --case when replaying one failure. --keep-runs keeps successful run folders so you can inspect the generated target, trace, log, DB, result.json, and manifest.json.

Held-out parallel smoke

mars validation agent-smoke \
  --suite held-out \
  --parallel 2 \
  --single-server \
  --single-server-tier coding \
  --timeout 10m

The default local path uses one shared llama-server tier. Pass --single-server=false only when you deliberately want tiered role routing.

Fixture recipe check

mars validation agent-smoke --suite full --fixture-only --json

This generates and lints fixtures without running roles. It is useful for debugging the matrix or generator, but it is not live role evidence.

Clean up retained runs

mars validation agent-smoke --cleanup-only

Use the same --root when cleaning a custom run location. Cleanup removes every run-* directory under that root and exits before matrix loading or report writing.

Agent Smoke Command Reference

The command filters the checked-in matrix, creates one fresh run directory per selected case, and runs each case with isolated target files, SQLite state, logs, and trace output.

No --repo flag: run this command from the MARS source checkout, or pass --root only to move run storage. The matrix still comes from the current foundation checkout.

Option	Default	User meaning
`--suite fast\|default\|full\|held-out`	`fast`	Selects the matrix lane. `fast` rotates one case per role. `default` runs representative cases. `held-out` checks anti-overfit cases. `full` runs every case.
`--cycle <key>`	empty	Stable rotation key for `fast` selection. Use a date, release, or ticket key when you want repeatable rotation.
`--case <id>`	empty	Runs one case by exact matrix ID. Best for replaying a failed or changed contract.
`--role <role>`	empty	Runs only cases for one role, such as `engineer`, `qa`, or `dogfood`.
`--project-type <type>`	empty	Runs only cases for one generated target shape, such as `go-api`, `static-web`, `react-web`, or `browser-game-phaser`.
`--parallel <n>`	`1`	Runs up to this many selected cases at once. With the default single-server mode, MARS raises local server parallelism to match when needed.
`--timeout <duration>`	`10m`	Per-case timeout. A timeout is a failed case, not a skipped case.
`--max-turns <n>`	`32`	Maximum role turns for live execution. Fixture-only runs do not use the live agent loop.
`--model-endpoint <url>`	local router	Uses an operator-supplied OpenAI-compatible endpoint. It must be a real model endpoint for validation claims; fake, scripted, stub, mock, or canned endpoints prove plumbing only.
`--single-server`	`true`	Uses one local inference server for all selected roles. Pass `--single-server=false` to use tiered local routing.
`--single-server-tier coding\|reasoning\|fast`	`coding`	Selects the local tier used by the shared server.
`--fixture-only`	`false`	Generates and checks targets without running the role. Good for generator debugging; not live role evidence.
`--json`	`false`	Writes a machine-readable report to stdout.
`--report <path>`	empty	Writes a Markdown report. Use `docs/validation/reports/` when the run is durable evidence.
`--keep-runs`	`false`	Keeps successful run directories for inspection. Without it, successful runs are deleted after their result artifacts are written.
`--discard-failed`	`false`	Deletes failed run directories too. Avoid this when diagnosing role behavior.
`--cleanup-only`	`false`	Deletes retained `run-*` folders under the agent-smoke root and exits without loading cases or writing a Markdown report.
`--root <path>`	`../demo/validation-runs/agent-smoke`	Parent directory for ephemeral runs, resolved from the MARS source checkout unless you pass an absolute path.

Agent Smoke Output And Retention

A passing text run prints a summary and one line per case. A JSON run includes the selected count, pass/fail counts, evidence source, model source, inference topology, cleanup count, optional report path, and a result object for each case.

Field or file	What it tells you	How to use it
`evidence`	`local-model`, `endpoint-override`, `fixture-only`, or `cleanup-only`.	Use it to decide whether the run can support a live validation claim.
`model_source`	The local router topology or endpoint-override note.	Record this in durable validation reports when the model path matters.
`single_server`, `single_server_tier`, `server_parallel`	Local inference topology used for the run.	Use these when claiming single-server parallel coverage.
`results[].execution_mode`	`live`, `fixture-only`, or `source-only`.	Only `live` proves role execution against a target. Source-only foundation role cases do not execute a target manifest role.
`results[].terminal_disposition`, `terminal_next_need`, `terminal_suggested_role`	The recorded job disposition and suppressed follow-on routing.	Compare with the case contract before using the run as evidence.
`results[].run_path`	The retained run directory, or discarded status in the Markdown report.	Open it when diagnosing a failure or a kept success.
`target/`	The generated repo used by the case.	Inspect generated files, tickets, reports, commits, and target-local case contract.
`db/mars.db`	Case-local queue, trace, trust, and org-state data.	Use for deep diagnosis without mixing cases or target repos.
`logs/<role>.log`	Role terminal log for the case.	Start here when a role failed or timed out.
`trace/`	Created and reported as a case trace path. Trace data is currently SQLite-backed in `db/mars.db`.	Use the DB with the log and result files to inspect tool and disposition behavior.
`result.json`	Full per-case result object.	Useful for scripts and for copying exact fields into a validation report.
`manifest.json`	Run ID, case, role, target path, DB path, execution mode, job ID, status, disposition, and would-dispatch role.	Use as a quick retained-run index.

Failure class	Likely meaning	First place to look
`fixture-invalid`	The generated target does not match the case contract.	Target files and `current-case.md`.
`foundation-tool-generation`	Foundation seeding or artifact writing failed.	Generation tool provenance and run artifacts.
`environment/model`	Model, LLM, or inference setup failed.	Model source, local config, and role log.
`role-behavior`	The role failed the expected behavior, terminal disposition, turn budget, or post-run assertions.	Role log, trace, target commits, and `result.json`.
`tool-policy`	A tool call was blocked by policy.	Role log and case contract tool expectations.
`dispatch-context`	The disposition, next need, suggested role, or dispatch contract did not match.	Org-state DB and terminal disposition fields.
`project-type-gap`	The matrix names a target shape the generator does not support.	Matrix case and generator support.
`cleanup-failed`	MARS could not delete a run directory after a pass.	Run root permissions and open files.
`unknown`	A failure did not match a known class.	Use the retained run path and exact error text.

Evidence Rules

Validation claims need the right kind of evidence. A narrow passing check should not be used to claim a broad lifecycle fix, and fake model endpoints must not be used as live model evidence.

Primary Outcome Contract

Reports lead with Primary Outcome, Primary Pass Gate, Primary Status, Current Primary Blocker, Next Primary Action, and Supporting Evidence.

Clean-project replay

Foundation runtime changes need representative clean target validation before broad lifecycle claims.

No fake live evidence

Fake, stub, mock, canned, or scripted LLM endpoints prove plumbing only, not live role/model/lifecycle quality.

Fixture-only is not a pass claim

--fixture-only can prove generator recipes still build target fixtures. It does not prove an agent role executed or made a good decision.

Failure ownership

Classify observed failures as foundation-owned, deployed-owned, mixed/unclear, or evidence-only before creating fixes or tickets.

Recipes

Enable a scoped JIRA mirror

cp .harness/integrations.example.yaml .harness/integrations.yaml
$EDITOR .harness/integrations.yaml
mars doctor --repo ~/my-project --json

Keep values in env vars where possible and verify scope before writing local tickets.

Validate a source runtime change

make install
mars validation agent-smoke --suite fast --json
mars docsync audit --repo .

Record a blocked matrix attempt

mkdir -p docs/validation/reports
$EDITOR docs/validation/reports/YYYY-MM-DD-short-name.md

Record the matrix, command, source ref, model identity, paths, result, failure class, cleanup status, and exact rerun command.

Troubleshooting

Symptom	Likely cause	User action
No JIRA route appears in a target.	No real `.harness/integrations.yaml` exists or profile remains `ceo-led`.	Copy the example config deliberately and set `flow_profile: board-driven`.
JIRA issue is dropped.	Project map, workspace, board, label, or JQL scope did not match.	Inspect sanitized drop reason, adjust config, and rerun mirror only for intended scope.
Atlassian MCP shows no JIRA search tool.	Credential or permission group lacks JIRA tool availability.	Use OAuth-capable helper or adjust Atlassian permissions; do not bypass containment with raw board dumps.
Validation passes with a fake endpoint.	The run only proved deterministic plumbing.	Record it as supporting evidence and run real model validation before claiming live role quality.
Matrix run fails before execution.	Setup, model, auth, or environment blocked the run.	Create a matrix report with the blocker and exact replay command.

Connect external signals without giving up local-first control.

Local-First Integration Model

Opt-in profiles

Secrets by env-var name

Mirror before fan-out

Evidence stays durable

Optional GitHub Integration

JIRA Mirror

Map project to exactly one repo

Apply workspace and label scope

Normalize issue fields

Preserve target-owned work

Atlassian MCP

Board-Driven Profile

Configuration

Validation Artifacts

Agent Smoke

Rotating fast smoke

Inspect one retained run

Held-out parallel smoke

Fixture recipe check

Clean up retained runs

Agent Smoke Command Reference

Agent Smoke Output And Retention

Evidence Rules

Primary Outcome Contract

Clean-project replay

No fake live evidence

Fixture-only is not a pass claim

Failure ownership

Recipes

Enable a scoped JIRA mirror

Validate a source runtime change

Record a blocked matrix attempt

Troubleshooting