Core Capabilities

This page explains why OpenGantry’s capabilities exist and when to use them. For commands and step-by-step flows, see index.md (How section) — especially ADOPTION.md and DOMAINS.md.

Deep design records: .gitagent/out-of-scope/ ADRs.

Scope Enforcement

Agents operate within a Target Mission Verification Context (TMVC). OpenGantry physically drops mutations attempted outside these declared file boundaries. The Planner may seal a per-mission contract (tmvc_roots, forbidden_zones, allowed_imports, banned_imports) that can only tighten the skill and org-policy floor (ADR-0045). gantry verify re-reads the contract from the Planner stamp commit (GXT_CONTRACT_TAMPERED on drift) and scans import sites (import(), require(), export … from included).

When to use: Always — init scaffolds defaults; Planner narrows per mission via gantry legislate --from-intent or gxt_propose_contract.

How: gantry contract propose|check|show · gantry context-request · ADOPTION.md § Prevent unreviewed edits · TMVC and forbidden zones below

Architectural Perimeters

OpenGantry enforces your project’s TARGET_ARCHITECTURE.yaml. It acts as a strict architectural gateway for import layers and content rules, ensuring agents do not introduce unauthorized public surface area.

When to use: New repo bootstrap, after major structural change, or when onboarding an external executor.

How: DOMAINS.md · Discover → blueprint → perimeter below

Static Analysis

Mission gate_command hooks seamlessly wire into your existing linters and type checkers to enforce standard code hygiene automatically. For tool-native findings[] (file, line, rule_id), set gate_adapter: eslint with npm run lint:json (eslint --format json) or gate_adapter: tsc with npx tsc --noEmit --pretty false. One adapter per mission — do not concatenate tools in gate_command (ADR-0041); typed adapters fail closed on unquoted &&, ||, ;, or line break (GXT_GATE_ADAPTER_MISCONFIG). gantry doctor and MCP gxt_doctor preflight typed adapters (binaries, config, lint:json) before a verification gate spawns; gantry doctor --adapter-baseline / gxt_doctor adapter_baseline warn about pre-existing tsc/eslint debt.

When to use: Before merge, in CI, and on autonomous retry edges.

How: ADOPTION.md § Standard change graph · DEVELOPMENT.md § Feature-mission adapter gates

Deterministic feedback edges

We do not just block bad commits. When an Execution Gate fails, OpenGantry returns structured JSON findings[] with offending_file, line, and resolution hint when a structured producer supplies them; generic gates emit a coarse row and gate_log_path on the context-feed — so agents can self-correct without human intervention.

When to use: Autonomous agent graphs and headless orchestrators that need machine-readable retry input.

How: ADOPTION.md § Verify troubleshooting · AGENT-GRAPH.md

Feature reference

The sections below expand on the verification pipeline with GXT graph detail, domain adapters, and integration patterns.

Mission graph (GXT)

Why: Agent work without a declared mission YAML drifts — scope expands, substrate files get edited silently, and “done” means whatever the last chat said.

What it does: Everything revolves around a mission (.gitagent/missions/MSN-XXXX.yaml): declared intent, TMVC scope, gate_command, interrogation record (operator answers to deterministic gap findings), trace rows. Three roles — Planner commits the mission (gantry legislate runs gap analysis and writes mission law), Executor works in scope, Verifier runs gantry verify — enforce segregation of duties.

When to use: Any substantive agent-assisted change you want merge-ready evidence for.

How: ADOPTION.md § Standard change graph · KATA.md

TMVC and forbidden zones

Why: “Don’t touch X” in a prompt is not enforceable. Auditors and security teams need declared edit boundaries tied to skills and missions.

What it does: MANIFEST.json defines tmvc_roots per skill; missions may narrow further. forbidden_zones block substrate paths (.gitagent/foreman/, RULES.md, etc.). Out-of-scope access requires a logged Context Request in EXECUTOR_LOG.md.

When to use: Always — init scaffolds defaults; Planner narrows per mission.

How: gantry context-request · ADOPTION.md § Prevent unreviewed edits

Discover → blueprint → perimeter

Why: Governance tools that take minutes to “understand” a repo block the agent graph before work starts. Rules written without evidence become fiction on the next refactor.

What it does: Three phases, any domain:

Discovery uses streaming regex (budgeted for large monorepos in CI) — fast context without loading a whole compiler graph. Blueprint turns human-confirmed conventions into machine-checkable perimeter rules.

When to use: New repo bootstrap, after major structural change, or when onboarding an external executor that needs required_skills and gate_commands from the verification plan.

How: DOMAINS.md · AGENT-GRAPH.md

Domain adapters (code, content)

Why: The mission/verify graph is domain-neutral; enforcement rules are not. TypeScript needs import layers; marketing copy needs regex disclaimers.

What it does: Built-in adapters plug deterministic discovery, blueprint, and perimeter into the same graph. Binary enforcement: pass/fail only — content discovery uses exact-match boilerplate, not statistical inference that flips on unrelated edits.

When to use: code for TS/JS repos; content for brand/compliance corpora. Custom domains use gate_command + TMVC globs until you add a custom adapter.

How: DOMAINS.md · examples/content-governance/

gantry verify and findings[]

Why: Autonomous agents choke on unstructured stderr — stack traces, ANSI codes, and multi-line test output are unreliable retry input. Models hallucinate fixes and loop. Merge gates still need deterministic pass/fail, not LLM opinions.

What it does: Runs shell gate_command, trace mapping, git-proof (Planner legislation commit), and optional KPI/stale-evidence checks. On failure, emits structured findings[] with failed_gate, offending_file, line, resolution_hint, and (v3) optional rule_id, evidence, and fingerprints. Structured gate producers (import-layer JSON, banned-import stderr) populate file/line; generic gates emit a coarse row plus gate_log_path on the context-feed. Same shape on --json, SARIF, JUnit, and MCP gxt_verify.

When to use: Before merge, in CI, and on autonomous retry edges.

How: ADOPTION.md § Verify troubleshooting · AGENT-GRAPH.md · CI.md (--format sarif / --format junit)

Trace evidence and stale binding

Why: Verifiers must cite verbatim execution evidence — not source-code quotes alone — or PASS claims are ungrounded.

What it does: EXECUTOR_LOG.md holds gate output quotes. Verify binds committed PASS lines to TMVC via git blame + git diff — if code drifted after attestation, trace is STALE (GXT_TRACE_STALE).

When to use: Every mission with trace rows. Add EXECUTOR_LOG.md to formatter ignore lists to avoid line-number drift.

How: ADOPTION.md § Stale trace evidence

Enforcement boundary (hooks, runtime exec)

Why: IDE Agent Write/Edit is convenient but advisory. Compliance and security claims require fail-closed mechanisms.

When to use: Regulated teams and headless orchestrators should adopt process-boundary + merge verify; advisory-only is acceptable only when documented.

How: INTEGRATIONS.md · COMPLIANCE-ISO.md

Zero-config cage (gantry cage)

Why: Teams want a guardrail before they adopt missions. gantry cage -- <command...> (standalone bin: gantry-cage, with opengantry-cage kept as an alias in the full package; also published on its own as the slim @jeger-ai/opengantry-cage package, whose only bin is gantry-cage: shared sources, commander as the only runtime dependency, no native modules, no install scripts) runs any command, including an interactive agent session, with inherited stdio, and restores a built-in protected set while it runs and once more at exit. It needs no manifest and no gantry init. The root is the enclosing git work tree, or the current directory outside git.

The whole-tree scan for .env*, lockfiles and .cage.yaml globs skips node_modules, .git, .venv, venv and __pycache__.

Project rules (.cage.yaml, optional). A file at the cage root adds paths to the protected set. It can only add: the built-in rules above are a floor that nothing in the repo can lower (ADR-0048).

mode: revert                     # optional default for the entries below (never for built-in rules)
contest_limit: 3                 # optional: live restores of one path before cage halts the command (0 never halts)
protect:
  - path: db/migrations          # file or directory tree, relative to the cage root
  - glob: "**/*.pem"             # * stays in one path segment, ** spans any depth
  - path: docs/generated.md
    mode: report                 # list the change but keep it (default: the top-level mode, else revert)

• Strict, fail closed: cage exits 2 before the command runs (GXT_CAGE_CONFIG_INVALID) on invalid YAML, YAML aliases, unknown keys, subtractive keys such as relax or exclude, an entry with both or neither of path: and glob:, absolute or .. paths, a contest_limit: that is not a non-negative integer, or mode: report (per entry or as the top-level default) on a path a built-in rule reverts. Format follows ADR-0047.
• Scoped default: the top-level mode: applies only to protect: entries without their own mode:. Built-in rules keep reverting whatever it says.
• Self-protected: .cage.yaml is the built-in cage_config target. An edit during the session is restored, and a .cage.yaml created during the session is removed. The push guard uses the rules the session started with, so editing the file mid-session cannot loosen it.
• On record: cage reads the working tree. When .cage.yaml is untracked or differs from HEAD, it warns on stderr (cage: warning: .cage.yaml is untracked or has uncommitted changes; review and commit it) and still runs.
• Caps: if the protected set at the start holds more than 5,000 files or 64 MiB, cage aborts before the command runs (GXT_CAGE_LIMITS_EXCEEDED, exit 2) and reports both totals. Narrow broad globs or zones.

Proposals (gantry cage suggest). A setup step you run yourself: it scans the repo statically and proposes protect: entries, each with a category and a reason. It looks for migration directories, Terraform, Kubernetes and Helm, Docker and compose files, package registry config (.npmrc, .pypirc, …), CODEOWNERS, other CI systems (Jenkins, Buildkite, Bitbucket, Drone, Travis, Woodpecker, Cloud Build, .github/actions), committed git hook config (.githooks/, .husky/, .pre-commit-config.yaml, Lefthook) and key files (*.pem, *.key, *.p12, *.pfx).

• Entries already protected by a built-in rule or your .cage.yaml are left out; node_modules/, dist/, build/, vendor/ and target/ are not scanned. Output is sorted the same way on every machine.
• gantry cage suggest prints the proposal. --write saves it as .cage.yaml.suggested (--force replaces an existing one; otherwise GXT_CAGE_SUGGEST_EXISTS). --json emits the suggestions as JSON.
• It never writes .cage.yaml, and cage never reads .cage.yaml.suggested. Review the proposal, move what you keep into .cage.yaml, and commit it.
• Cage sets GANTRY_CAGE_SESSION=1 for the wrapped command, and cage suggest refuses to run inside a session (GXT_CAGE_SUGGEST_IN_SESSION). No MCP tool exposes it.
• gantry cage -- suggest still runs a command named suggest; the standalone gantry-cage bin has no subcommands.

Overrides (--allow-override <path>). For one run, changes under <path> are reported instead of restored. Repeat the flag for more paths.

• It never applies to git hooks and config or to .cage.yaml, and it is refused for a path no revert rule covers (GXT_CAGE_OVERRIDE_INVALID, exit 2, before the command runs).

• It is always announced: a stderr line at start and in the exit summary (cage: OVERRIDE (--allow-override): changes are reported, not restored, under: <paths>), overrides[] in the JSON report, and overridden: true on affected rows. Overridden changes do not cause exit 3.

• The push guard lets overridden paths through, like any report-mode path.

• Live restore (default): every --watch-interval-ms (default 1000) cage re-snapshots the protected set and restores revert-rule changes. --no-watch checks only once, at exit.

• Contested paths halt the command: when a revert-rule path is rewritten again after the contest limit of live restores (default 3), cage restores it once more, sends SIGTERM to the command and every descendant it can enumerate, waits a short grace period, then SIGKILLs what is left. Status halted, exit 4, a halt event in the session log, and a stderr line naming the path and rule. The limit resolves --contest-limit <n>, then .cage.yaml contest_limit:, then 3; 0 turns the halt off, in which case the path is marked contested after 3 restores and restored once at exit. Report-mode and overridden paths never halt. The command is not run in its own process group (that would stop interactive agents on SIGTTIN), so a descendant reparented between the two passes can survive.

• Quiet while running: one start line (cage: watching N protected file(s); live events: <log>), then only a terminal bell per event. Events go to a JSONL session log in the OS temp dir (paths, rules and outcomes; never file bodies).

• Session push guard: the caged process tree gets a temporary core.hooksPath (via GIT_CONFIG_* env, in the OS temp dir) whose pre-push refuses outgoing commits that touch revert-rule paths, prints the reason, then runs your repo’s own hooks. Nothing is written to the repo; the temp dir is removed at exit. Lockfile commits are allowed.

• Snapshot: held in memory for live restore, with a copy in the session journal (below) until a clean exit; it must hold every revert-rule file. A file over --max-file-bytes (default 5 MiB), or a protected set whose revert-rule bytes exceed the 64 MiB budget, stops cage before the command runs (GXT_CAGE_FILE_TOO_LARGE with every offending path and size, or GXT_CAGE_SNAPSHOT_BUDGET_EXCEEDED with the total; exit 2). Nothing is left detect_only. Raise the cap, or --allow-override <path> to report that path instead of restoring it; --report-only keeps no bytes and is unaffected (ADR-0048 decision 8).

• Restore: write to a temp file, then rename, so a failed restore never truncates the target. File mode is restored (for example, a hook’s 0755). Added files are removed. mtime-only changes are ignored.

• Exit codes: 4 when cage halted the command (status halted); 3 when any revert-rule path changed during the session or at exit (status violations_reverted or violations_unresolved); 2 when the command could not start, or when .cage.yaml, an override, the scan caps, a revert-rule file over the per-file cap or the snapshot budget, a still-running earlier session or a corrupt journal fail closed before it runs; otherwise the command’s own exit code (128 + N for signal N).

• Report: human summary on stderr at exit; --json emits gantry.cage-report.v1 on stdout. Each change row has path, kind, rule, source (builtin, manifest or cage_yaml), overridden, sha256_before, sha256_after, outcome and error_code, and never file bodies (ADR-0034). watch (enabled, interval_ms, live_restores, contested, contest_limit, halt with path, rule and live_restores or null, session_log) and push_guard (enabled, refused_pushes) summarize the session; cage_config (present, entries, committed) and overrides describe the rules in force; trapped_signal names a signal cage answered by terminating the command, and recovery (previous_pid, started_at, restored, orphans_killed, or null) describes an interrupted session cleaned up before this one. It is not an attestation receipt (ADR-0036).

• --report-only: detect and exit 3 without restoring (no live restore).

• Fail closed: an invalid MANIFEST.json or .cage.yaml, an invalid --allow-override, a protected set over the scan caps, or a revert-rule file the snapshot cannot hold (per-file cap or total budget) aborts before the command runs with exit 2.

• Signals: cage traps SIGTERM, SIGHUP and SIGINT so it always outlives the command. SIGTERM, SIGHUP, and SIGINT when stdin is not a terminal (an orchestrator stopping the run), terminate the command and every descendant cage can enumerate: SIGTERM, a short grace period, then SIGKILL, the same path as the contested-file halt and never a detached process group (ADR-0048 decision 7). Cage then restores the protected set, prints cage: trapped SIGTERM: …, sets trapped_signal and exits 3 if anything was restored, otherwise with the command’s own exit code (128 + N when the signal killed it). On a terminal, Ctrl-C reaches the agent through the foreground group, as agents use it to interrupt rather than quit, and cage keeps supervising.

• Interrupted sessions (kill -9 on cage): before the command starts, cage writes a journal to <git dir>/gantry-cage-journal/ (outside git, a root-keyed directory in the OS temp dir): the baseline entries and the bytes of revert-rule files, files 0600, plus the pids of the command and its descendants with their start times, refreshed every watch interval and at most every 500 ms. Every JSON file has a sha256 sidecar. A clean exit, including a trapped signal, removes it. If cage itself is killed, the next cage run in that root kills recorded processes still alive (matched by start time, so a reused pid is never hit), restores the protected set from the journal, clears it, prints cage: recovered an interrupted session … and reports recovery, and only then starts the new command. It refuses to start while the earlier cage is still running (GXT_CAGE_SESSION_ACTIVE, exit 2), and on any hash mismatch or missing blob (GXT_CAGE_JOURNAL_CORRUPT, exit 2): nothing is restored from an untrusted journal and it is kept for inspection; remove the directory to continue.

Limits (printed in every report): restore, not blocking. A change can be committed or used in the gap before the next check, and the halt ends the session after the fact rather than preventing the write. The push guard only covers git push run inside the session and is skipped by --no-verify; a refused or committed change stays in local history, because cage restores the working tree, not commits or a remote. Reads, network/API side effects and writes outside the protected set or repo are not detected. If cage itself is killed with kill -9, the tamper and the agent’s processes stay until the next cage run in that repo cleans them up; nothing restores them in between. Agents that run git push -u will see the upstream entry in .git/config reverted. That is intentional.

When to use: As the zero-config on-ramp: start the agent you already use inside it (gantry cage -- claude). Missions add scope enforcement on every write, Planner-signed law and gantry verify in CI; gantry runtime exec needs a pinned mission and enforces TMVC and forbidden zones with telemetry.

How: npx @jeger-ai/opengantry-cage -- claude · npx -p @jeger-ai/opengantry gantry-cage -- claude · gantry cage -- aider · gantry cage --json -- <cmd> · gantry cage suggest --write · gantry cage --allow-override .env.local -- <cmd> · gantry cage --contest-limit 1 -- <cmd> · ADOPTION.md

Role-based CLI output (--audience)

Why: Executors, Planners, and CI verifiers need different verbosity — constraint-forward next steps vs silent pass/fail.

What it does: gantry --audience executor|planner|verifier tailors verify/start output. GXT_AUDIENCE env var mirrors global --audience.

How: ADOPTION.md § Role-based CLI output

Trusted automation policy

Why: Low-risk bot maintenance (e.g. Dependabot workflow pin bumps, security autofix PRs) should not require a full mission per bot commit when constraints are narrow and git-derived.

What it does: Declarative rules in .gitagent/config.json — allowed_actors, allowed_paths, one allowed_structural_changes kind per rule (workflow_version_pin or bounded_content), max_net_loc with per-kind hard caps. Evaluation is git-derived only; missing config → full MSN workflow.

When to use: Committed automation you can bound with strict path and churn limits.

How: ADOPTION.md § Trusted automation policy

Break-glass

Why: Production emergencies happen; silent policy bypass is worse than explicit, auditable bypass.

What it does: gantry verify --break-glass --reason "…" with GXT_BYPASS_SECRET matching .gitagent/foreman/BYPASS.sha256. Records forensic note on refs/notes/gxt-bypass. Does not disable runtime exec forbidden-zone enforcement.

When to use: Emergency only — post-incident Planner review required.

How: ADOPTION.md § Break-glass

Metrics (gantry metrics)

Why: Leadership asks “how much agent work is legislated vs traced?” without a vendor telemetry silo.

What it does: Git-native counters from a single git log pass — legislative_commits vs worker_trace_commits (path-touch proxy, documented in JSON metadata). No local event ledger.

How: ADOPTION.md § Metrics

Inspection dashboard (gantry report)

Why: A last-fail JSON dump does not answer “what work has happened in this repo?” Humans need git-native history, substrate readiness, and a way to drill into the latest verify without a hosted console.

What it does: Spins up a read-only HTTP server on 127.0.0.1 (default port 3134, walks +1..+10 on EADDRINUSE when --port is omitted). Home (/) is a project overview: gantry status readiness, gantry metrics KPIs, a mission timeline from git, and a capped local 20-run verify ring (.gitagent/tmp/verify-runs/, gitignored; one atomic JSON file per run, sorted by filename). Drill-down: /verify is the last run; /run/:id is any ring entry; /mission/:msn_id is the latest local verify for that mission. Each view shows PASS/FAIL/ABORT, circuit-breaker ring, phase bars, findings, and a streamed gate log (/log?run=:id when scoped). Git metrics are recomputed per request. Writes nothing from the HTTP server; exits on Ctrl+C.

How: gantry report · gantry report --last · gantry report --no-open · gantry report --json (overview) · gantry report --json --last (last-verify model)

Defensive profiles and architecture cage

Why: Missions can authorize scope; they should not authorize unbounded churn or architecture violations.

What it does: TARGET_ARCHITECTURE.yaml + gantry arch check / gantry perimeter check enforce import layers or regex rules. Defensive profiles add severity-tiered guards (net LOC, file scope, test-to-code ratio). gantry arch fetch resolves external architecture pointers offline.

How: DOMAINS.md · ARCHITECTURE.md (contributor layer rules)

LLM evidence + KPI gate

Why: Some checks are nondeterministic (LLM rubrics) but merge must stay deterministic.

What it does: gantry scan commits JSON evidence; gantry verify evaluates kpi_gate.thresholds against committed reports. KPI stale binding mirrors trace evidence.

When to use: Optional mission fields — not required for basic adoption.

How: DEVELOPMENT.md § LLM evidence + KPI gate · ADR-0020

Ephemeral virtualization

Why: Some integration checks need transient runtime outputs without rewriting the verify engine.

What it does: Opt-in .gitagent/virtual/ scratch mapped into KPI/file-matching gates; never committed; crash-safe per-flight cleanup.

How: ADR-EPHEMERAL-VIRTUALIZATION.md

Hybrid hub and spoke (metadata plane)

Why: Teams need local developer control and org-wide auditability without uploading source trees or gate stdout to a vendor cloud. Execution stays on the spoke; optional hub metadata is digests only.

What it does:

When to use: Local-first agent governance today; git-native organization control plane (policy floor, ledger, cross-repo gates) without changing the spoke-enforces / hub-aggregates model.

How: ADR-0034 · SECURITY.md

Experimental contract preflight

Why: Mission Architect still spends a turn inferring skill_key and path hints before the deterministic proposer. A typed classifier can suggest those hints. It must not become mission law.

What it does: gantry contract preflight and MCP gxt_preflight_contract are advisory and read-only. They do not write contract or contract_sha256 (ADR-0046). The default provider is the offline heuristic. Optional provider jev calls TypeSafe System One when TYPESAFE_API_KEY is set.

Jev builds its request from the live .gitagent/foreman/MANIFEST.json. Every skill is included (desc and tmvc_roots). There is no hard-coded skill list.

Fail-open: the fetch limit is 2000ms. A timeout, or any non-OK HTTP status including 500, returns the offline heuristic with a jev_fallback: rationale. The agent loop is not thrown. A missing TYPESAFE_API_KEY is an explicit error before any fetch.

When to use: Before gxt_propose_contract, when you want skill and tmvc_roots hints. Treat jev_fallback: as the heuristic payload and keep going.

How: examples/jev-preflight/README.md · ADR-0046

Advisory performance judge

Why: Deterministic gates cannot evaluate code against documented performance strategies (pooling, blocking I/O, memoization) in PERFORMANCE.md or ADRs.

What it does:

When to use: After architecture rubric (#16); when missions touch hot paths and you want semantic performance sanity checks alongside deterministic gates.

How: ADR-0035 · examples/performance-judge/

OpenGantry vs execution firewall

Why: Unmonitored tool calls and tool-poisoning are real, but they are a different problem from architectural scope and verify evidence. Defense in depth means both layers.

What it does: OpenGantry is the deterministic routing engine and architecture cage (missions, TMVC, perimeter, verify, receipts). A standalone security proxy sandboxes MCP tools and verifies skill hashes at invoke time. Pair them when you need both citeable Git evidence and runtime isolation.

When to use: Always use OpenGantry for mission/verify and tamper-evident trails. Add a sandbox proxy when untrusted tools are on the critical path.

How: SECURITY.md § OpenGantry vs a standalone security proxy

What OpenGantry is not

• Not an agent — it does not chat, plan features, or generate PRs
• Not a hosted execution console — gates and cages run on your machine/CI; no source upload for verify
• Not Gantry.io — no bundled hosted observability dashboard (optional future metadata hub is digest-only)
• Not an LLM judge for merge — gates stay deterministic; LLM evidence is optional and committed separately
• Not an MCP execution firewall — sandboxing and skill-hash checks belong to a complementary proxy layer
• Not a full prompt/diff recorder by default — hash_only telemetry and digest receipts prove outcomes without shipping raw corpora

For product positioning and a hands-on tour, see README.