@jeger-ai/opengantry 2.6.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +132 -327
- package/dist/cli/commands/arch.d.ts +1 -0
- package/dist/cli/commands/arch.d.ts.map +1 -1
- package/dist/cli/commands/arch.js +56 -93
- package/dist/cli/commands/arch.js.map +1 -1
- package/dist/cli/commands/blueprint.d.ts +7 -0
- package/dist/cli/commands/blueprint.d.ts.map +1 -0
- package/dist/cli/commands/blueprint.js +69 -0
- package/dist/cli/commands/blueprint.js.map +1 -0
- package/dist/cli/commands/init.d.ts +3 -0
- package/dist/cli/commands/init.d.ts.map +1 -1
- package/dist/cli/commands/init.js +30 -25
- package/dist/cli/commands/init.js.map +1 -1
- package/dist/cli/commands/onboarding.js +1 -1
- package/dist/cli/commands/onboarding.js.map +1 -1
- package/dist/cli/commands/perimeter.d.ts.map +1 -1
- package/dist/cli/commands/perimeter.js +3 -6
- package/dist/cli/commands/perimeter.js.map +1 -1
- package/dist/cli/commands/planner.d.ts.map +1 -1
- package/dist/cli/commands/planner.js +5 -17
- package/dist/cli/commands/planner.js.map +1 -1
- package/dist/cli/commands/upgrade.d.ts.map +1 -1
- package/dist/cli/commands/upgrade.js +6 -14
- package/dist/cli/commands/upgrade.js.map +1 -1
- package/dist/cli/commands/verify.d.ts.map +1 -1
- package/dist/cli/commands/verify.js +19 -27
- package/dist/cli/commands/verify.js.map +1 -1
- package/dist/cli/lib/architecture-drift-doctor.d.ts +4 -0
- package/dist/cli/lib/architecture-drift-doctor.d.ts.map +1 -0
- package/dist/cli/lib/architecture-drift-doctor.js +58 -0
- package/dist/cli/lib/architecture-drift-doctor.js.map +1 -0
- package/dist/cli/lib/blueprint-engine.d.ts +22 -0
- package/dist/cli/lib/blueprint-engine.d.ts.map +1 -0
- package/dist/cli/lib/blueprint-engine.js +127 -0
- package/dist/cli/lib/blueprint-engine.js.map +1 -0
- package/dist/cli/lib/command-boundary.d.ts +16 -0
- package/dist/cli/lib/command-boundary.d.ts.map +1 -0
- package/dist/cli/lib/command-boundary.js +45 -0
- package/dist/cli/lib/command-boundary.js.map +1 -0
- package/dist/cli/lib/command-reporter.d.ts +3 -3
- package/dist/cli/lib/command-reporter.d.ts.map +1 -1
- package/dist/cli/lib/context-feed-remediation.d.ts +1 -1
- package/dist/cli/lib/context-feed-remediation.d.ts.map +1 -1
- package/dist/cli/lib/defensive-guard.d.ts +2 -3
- package/dist/cli/lib/defensive-guard.d.ts.map +1 -1
- package/dist/cli/lib/defensive-guard.js +56 -69
- package/dist/cli/lib/defensive-guard.js.map +1 -1
- package/dist/cli/lib/discovery-proposal.d.ts +19 -0
- package/dist/cli/lib/discovery-proposal.d.ts.map +1 -0
- package/dist/cli/lib/discovery-proposal.js +110 -0
- package/dist/cli/lib/discovery-proposal.js.map +1 -0
- package/dist/cli/lib/discovery-scanner.d.ts +47 -0
- package/dist/cli/lib/discovery-scanner.d.ts.map +1 -0
- package/dist/cli/lib/discovery-scanner.js +81 -0
- package/dist/cli/lib/discovery-scanner.js.map +1 -0
- package/dist/cli/lib/doctor-core.d.ts.map +1 -1
- package/dist/cli/lib/doctor-core.js +2 -0
- package/dist/cli/lib/doctor-core.js.map +1 -1
- package/dist/cli/lib/domains/domain-adapter.d.ts +38 -0
- package/dist/cli/lib/domains/domain-adapter.d.ts.map +1 -0
- package/dist/cli/lib/domains/domain-adapter.js +20 -0
- package/dist/cli/lib/domains/domain-adapter.js.map +1 -0
- package/dist/cli/lib/domains/domain-code.d.ts +3 -0
- package/dist/cli/lib/domains/domain-code.d.ts.map +1 -0
- package/dist/cli/lib/domains/domain-code.js +171 -0
- package/dist/cli/lib/domains/domain-code.js.map +1 -0
- package/dist/cli/lib/domains/domain-content.d.ts +3 -0
- package/dist/cli/lib/domains/domain-content.d.ts.map +1 -0
- package/dist/cli/lib/domains/domain-content.js +190 -0
- package/dist/cli/lib/domains/domain-content.js.map +1 -0
- package/dist/cli/lib/domains/index.d.ts +5 -0
- package/dist/cli/lib/domains/index.d.ts.map +1 -0
- package/dist/cli/lib/domains/index.js +5 -0
- package/dist/cli/lib/domains/index.js.map +1 -0
- package/dist/cli/lib/errors.d.ts +2 -2
- package/dist/cli/lib/errors.d.ts.map +1 -1
- package/dist/cli/lib/errors.js +8 -8
- package/dist/cli/lib/errors.js.map +1 -1
- package/dist/cli/lib/executor-log-line-map.d.ts +0 -2
- package/dist/cli/lib/executor-log-line-map.d.ts.map +1 -1
- package/dist/cli/lib/executor-log-line-map.js +0 -5
- package/dist/cli/lib/executor-log-line-map.js.map +1 -1
- package/dist/cli/lib/git-proof.js +2 -2
- package/dist/cli/lib/gxt-error-codes.d.ts +2 -2
- package/dist/cli/lib/gxt-error-codes.js +7 -7
- package/dist/cli/lib/init-discover.d.ts +14 -0
- package/dist/cli/lib/init-discover.d.ts.map +1 -0
- package/dist/cli/lib/init-discover.js +45 -0
- package/dist/cli/lib/init-discover.js.map +1 -0
- package/dist/cli/lib/init-plan.d.ts +3 -1
- package/dist/cli/lib/init-plan.d.ts.map +1 -1
- package/dist/cli/lib/init-plan.js +2 -5
- package/dist/cli/lib/init-plan.js.map +1 -1
- package/dist/cli/lib/init-tutorial.js +1 -1
- package/dist/cli/lib/init-tutorial.js.map +1 -1
- package/dist/cli/lib/kpi-engine.d.ts +2 -2
- package/dist/cli/lib/kpi-engine.d.ts.map +1 -1
- package/dist/cli/lib/kpi-engine.js +3 -2
- package/dist/cli/lib/kpi-engine.js.map +1 -1
- package/dist/cli/lib/mcp-governance.d.ts.map +1 -1
- package/dist/cli/lib/mcp-governance.js +15 -15
- package/dist/cli/lib/mcp-governance.js.map +1 -1
- package/dist/cli/lib/mcp-runtime.d.ts +2 -2
- package/dist/cli/lib/mcp-runtime.d.ts.map +1 -1
- package/dist/cli/lib/mcp-runtime.js +1 -1
- package/dist/cli/lib/mcp-runtime.js.map +1 -1
- package/dist/cli/lib/mcp-upgrade.js +2 -2
- package/dist/cli/lib/mcp-write-guard.d.ts +2 -2
- package/dist/cli/lib/mcp-write-guard.js +2 -2
- package/dist/cli/lib/missions/parser.js +4 -4
- package/dist/cli/lib/surgeons/registry.d.ts +3 -2
- package/dist/cli/lib/surgeons/registry.d.ts.map +1 -1
- package/dist/cli/lib/surgeons/registry.js.map +1 -1
- package/dist/cli/lib/target-architecture.d.ts +12 -3
- package/dist/cli/lib/target-architecture.d.ts.map +1 -1
- package/dist/cli/lib/target-architecture.js +108 -8
- package/dist/cli/lib/target-architecture.js.map +1 -1
- package/dist/cli/lib/trace.d.ts +2 -1
- package/dist/cli/lib/trace.d.ts.map +1 -1
- package/dist/cli/lib/trace.js +21 -27
- package/dist/cli/lib/trace.js.map +1 -1
- package/dist/cli/lib/upgrade-apply.js +7 -7
- package/dist/cli/lib/verification-plan.d.ts +22 -0
- package/dist/cli/lib/verification-plan.d.ts.map +1 -0
- package/dist/cli/lib/verification-plan.js +26 -0
- package/dist/cli/lib/verification-plan.js.map +1 -0
- package/dist/cli/lib/verify-defensive-phase.d.ts +2 -13
- package/dist/cli/lib/verify-defensive-phase.d.ts.map +1 -1
- package/dist/cli/lib/verify-defensive-phase.js +11 -11
- package/dist/cli/lib/verify-defensive-phase.js.map +1 -1
- package/dist/cli/lib/verify-engine.d.ts +4 -36
- package/dist/cli/lib/verify-engine.d.ts.map +1 -1
- package/dist/cli/lib/verify-engine.js +28 -24
- package/dist/cli/lib/verify-engine.js.map +1 -1
- package/dist/cli/lib/verify-export.d.ts +1 -1
- package/dist/cli/lib/verify-export.d.ts.map +1 -1
- package/dist/cli/lib/verify-export.js +27 -17
- package/dist/cli/lib/verify-export.js.map +1 -1
- package/dist/cli/lib/verify-failure-normalize.d.ts +5 -10
- package/dist/cli/lib/verify-failure-normalize.d.ts.map +1 -1
- package/dist/cli/lib/verify-failure-normalize.js +128 -13
- package/dist/cli/lib/verify-failure-normalize.js.map +1 -1
- package/dist/cli/lib/verify-failure.d.ts +57 -0
- package/dist/cli/lib/verify-failure.d.ts.map +1 -0
- package/dist/cli/lib/verify-failure.js +2 -0
- package/dist/cli/lib/verify-failure.js.map +1 -0
- package/dist/cli/lib/verify-finding.d.ts +16 -0
- package/dist/cli/lib/verify-finding.d.ts.map +1 -0
- package/dist/cli/lib/verify-finding.js +11 -0
- package/dist/cli/lib/verify-finding.js.map +1 -0
- package/dist/cli/lib/verify-hints.d.ts +5 -18
- package/dist/cli/lib/verify-hints.d.ts.map +1 -1
- package/dist/cli/lib/verify-hints.js +40 -61
- package/dist/cli/lib/verify-hints.js.map +1 -1
- package/dist/cli/lib/verify-payload.d.ts +39 -2
- package/dist/cli/lib/verify-payload.d.ts.map +1 -1
- package/dist/cli/lib/verify-payload.js +1 -1
- package/dist/cli/lib/verify-payload.js.map +1 -1
- package/dist/cli/lib/verify-presenters.d.ts +3 -0
- package/dist/cli/lib/verify-presenters.d.ts.map +1 -1
- package/dist/cli/lib/verify-presenters.js +18 -5
- package/dist/cli/lib/verify-presenters.js.map +1 -1
- package/dist/cli/lib/verify-run.d.ts +0 -2
- package/dist/cli/lib/verify-run.d.ts.map +1 -1
- package/dist/cli/lib/verify-run.js +2 -2
- package/dist/cli/lib/version.gen.d.ts +1 -1
- package/dist/cli/lib/version.gen.js +1 -1
- package/dist/cli/program-blueprint.d.ts +3 -0
- package/dist/cli/program-blueprint.d.ts.map +1 -0
- package/dist/cli/program-blueprint.js +12 -0
- package/dist/cli/program-blueprint.js.map +1 -0
- package/dist/cli/program-core.d.ts.map +1 -1
- package/dist/cli/program-core.js +5 -1
- package/dist/cli/program-core.js.map +1 -1
- package/dist/cli/program-workflow.d.ts.map +1 -1
- package/dist/cli/program-workflow.js +19 -1
- package/dist/cli/program-workflow.js.map +1 -1
- package/dist/cli/program.d.ts.map +1 -1
- package/dist/cli/program.js +2 -0
- package/dist/cli/program.js.map +1 -1
- package/package.json +1 -1
- package/templates/.gitagent/foreman/SUBSTRATE.version.json +1 -1
- package/templates/integrations/compatibility.json +1 -1
- package/dist/cli/lib/verify-failure-normalize-phases.d.ts +0 -9
- package/dist/cli/lib/verify-failure-normalize-phases.d.ts.map +0 -1
- package/dist/cli/lib/verify-failure-normalize-phases.js +0 -84
- package/dist/cli/lib/verify-failure-normalize-phases.js.map +0 -1
- package/dist/cli/lib/verify-payload-types.d.ts +0 -36
- package/dist/cli/lib/verify-payload-types.d.ts.map +0 -1
- package/dist/cli/lib/verify-payload-types.js +0 -2
- package/dist/cli/lib/verify-payload-types.js.map +0 -1
- package/dist/cli/lib/verify-presentation.d.ts +0 -15
- package/dist/cli/lib/verify-presentation.d.ts.map +0 -1
- package/dist/cli/lib/verify-presentation.js +0 -12
- package/dist/cli/lib/verify-presentation.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,406 +1,211 @@
|
|
|
1
|
-
# OpenGantry
|
|
1
|
+
# OpenGantry: What It Is, Why It Exists, and How to Use It
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
## The one-line pitch
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
**OpenGantry is a local-first, Git-native governance layer for autonomous agents.** It does not write your code or content for you. It negotiates the contract before work starts, enforces deterministic boundaries during execution, and emits machine-readable verdicts when something fails.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Think of it as a **court of law** for agentic work: binary rules, reproducible checks, audit trail in Git.
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
> **Not [Gantry.io](https://gantry.io)?** OpenGantry is the open-source **`gantry` CLI** for local-first, Git-native governance in your repository, not a hosted observability dashboard.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
- **Evidence for regulated or security-sensitive change control:** keep verifiable proofs in Git (`[MSN-XXXX]`, deterministic gate outputs, trace quotes).
|
|
13
|
-
- **A reusable governance layer across many repos:** apply one Git-native workflow instead of building custom policy glue per project.
|
|
11
|
+
---
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
## Vision
|
|
16
14
|
|
|
17
|
-
|
|
18
|
-
- **No silent governance edits:** hooks and `gantry verify` fail closed on law, manifest, and mission paths without a Planner `[MSN-XXXX]` commit.
|
|
19
|
-
- **Audit in Git:** `git log --grep='MSN-0042'` plus `EXECUTOR_LOG.md` quotes that verifiers must cite verbatim.
|
|
15
|
+
Most AI agent tooling optimizes for *speed of generation*. OpenGantry optimizes for **trust at scale**:
|
|
20
16
|
|
|
21
|
-
|
|
17
|
+
- **Scope before execution:** no silent edits to governance files, no wandering outside approved paths
|
|
18
|
+
- **Deterministic verification:** gates are shell commands with pass/fail outcomes, not LLM opinions
|
|
19
|
+
- **Forensic trace:** every mission ties to `[MSN-XXXX]` commits and verbatim quotes in `EXECUTOR_LOG.md`
|
|
20
|
+
- **Domain-agnostic** (v3.0.0): the same loop governs TypeScript imports *and* brand/compliance copy
|
|
22
21
|
|
|
23
|
-
|
|
22
|
+
The long-term bet: external executors (Cursor agents, Hermes, CI bots) do the work; **OpenGantry owns the contract and the verdict**. That separation is what makes agentic delivery auditable in regulated or security-sensitive environments.
|
|
24
23
|
|
|
25
|
-
|
|
24
|
+
---
|
|
26
25
|
|
|
27
|
-
|
|
28
|
-
|------|------------|
|
|
29
|
-
| **Install + first mission** | [Install](#install) → [`docs/ADOPTION.md`](docs/ADOPTION.md) → [`docs/KATA.md`](docs/KATA.md) |
|
|
30
|
-
| **Gantry CLI command reference** | [gantry CLI](#gantry-cli) |
|
|
31
|
-
| **Git hooks + enforcement** | [Enforcement boundary](#enforcement-boundary) · [`docs/ADOPTION.md`](docs/ADOPTION.md) § Prevent unreviewed edits |
|
|
32
|
-
| **Wire IDE agents** | [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) |
|
|
26
|
+
## What problem it solves
|
|
33
27
|
|
|
34
|
-
|
|
28
|
+
Without governance glue, agent-assisted repos tend toward:
|
|
35
29
|
|
|
36
|
-
|
|
30
|
+
| Problem | OpenGantry answer |
|
|
31
|
+
|---------|-------------------|
|
|
32
|
+
| Agents edit `.gitagent/` or manifest silently | Git hooks + `gantry verify` fail closed |
|
|
33
|
+
| "It passed locally" with no proof | `gate_command` + trace quotes verifiers must cite |
|
|
34
|
+
| Architecture drift | `TARGET_ARCHITECTURE.yaml` + `gantry arch check` / `gantry perimeter check` |
|
|
35
|
+
| Opaque failures for retry loops | `findings[]` JSON envelope (file, line, hint); no terminal log parsing |
|
|
36
|
+
| One-off policy per repo | `gantry init` scaffolds the same GXT substrate everywhere |
|
|
37
37
|
|
|
38
|
-
|
|
39
|
-
npm install -g @jeger-ai/opengantry
|
|
40
|
-
gantry init --tutorial
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
Or without a global install:
|
|
38
|
+
---
|
|
44
39
|
|
|
45
|
-
|
|
46
|
-
npx @jeger-ai/opengantry init --tutorial
|
|
47
|
-
```
|
|
40
|
+
## The core loop (GXT)
|
|
48
41
|
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
*Want to see the ROI? Run `npm run examples:benchmark` to compare an orchestrator specimen (improvised agent glue) against OpenGantry's TMVC protocol.* (Requires clone + `npm run build` — see [`docs/ADOPTION.md`](docs/ADOPTION.md).)
|
|
52
|
-
|
|
53
|
-
## Documentation map (start here)
|
|
54
|
-
|
|
55
|
-
| Goal | Read first |
|
|
56
|
-
|------|------------|
|
|
57
|
-
| **Gantry CLI + local governance** | [Gantry CLI — local-first governance](#gantry-cli--local-first-governance) → [gantry CLI](#gantry-cli) |
|
|
58
|
-
| **Adopt in your repo (5 min)** | This README → [`docs/ADOPTION.md`](docs/ADOPTION.md) → [`docs/KATA.md`](docs/KATA.md) |
|
|
59
|
-
| **See benchmark ROI (3 min)** | [`examples/benchmark-agent/`](examples/benchmark-agent/) → [`docs/ADOPTION.md`](docs/ADOPTION.md) |
|
|
60
|
-
| **Wire IDE agents** | [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) |
|
|
61
|
-
| **Contribute / dogfood** | [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) |
|
|
62
|
-
| **Governance law + workflow** | [`.gitagent/README.md`](.gitagent/README.md) · [`.gitagent/planner/RULES.md`](.gitagent/planner/RULES.md) |
|
|
63
|
-
| **Roadmap / open work** | [`docs/BACKLOG.md`](docs/BACKLOG.md) |
|
|
64
|
-
| **Compliance framing** | [`docs/COMPLIANCE-ISO.md`](docs/COMPLIANCE-ISO.md) |
|
|
65
|
-
| **Ephemeral virtualization (stretch)** | [`docs/ADR-EPHEMERAL-VIRTUALIZATION.md`](docs/ADR-EPHEMERAL-VIRTUALIZATION.md) |
|
|
66
|
-
|
|
67
|
-
## Why teams adopt this
|
|
68
|
-
|
|
69
|
-
| Outcome | How OpenGantry delivers it |
|
|
70
|
-
|---------|---------------------------|
|
|
71
|
-
| **Lower onboarding friction** | `gantry init --tutorial`, `gantry onboarding`, `gantry start "<intent>"`, `gantry status --json` |
|
|
72
|
-
| **No unreviewed agent scope** | Planner reviews mission YAML **before** `runtime env` / executor execution; TMVC roots + forbidden zones enforce paths |
|
|
73
|
-
| **Audit-ready evidence** | `[MSN-XXXX]` commit subjects; verifier PASS requires a verbatim quote from `EXECUTOR_LOG.md` |
|
|
74
|
-
| **Regulated / ISO-aligned workflows** | SOD, mission authorization, and Git-native trace — see [`docs/COMPLIANCE-ISO.md`](docs/COMPLIANCE-ISO.md) (27001 change control, 42001 AI governance) |
|
|
75
|
-
| **Faster recovery from failure** | Stable `GXT_*` error codes, `gantry verify --fix`, role output via `--audience executor\|planner\|verifier` |
|
|
76
|
-
|
|
77
|
-
**Protocol maturity:** substrate law **v0.5.0**; **`gantry` v2.6.0** — unified CLI naming (`gantry` primary; legacy `gapman` alias). Current npm publish: **v2.6.0**. See [.gitagent/planner/RUNTIME.md](.gitagent/planner/RUNTIME.md).
|
|
78
|
-
|
|
79
|
-
## Release timeline (latest first)
|
|
80
|
-
|
|
81
|
-
Current npm release in this repository: **`gantry` v2.6.0**. Use [`docs/ADOPTION.md`](docs/ADOPTION.md) for the ordered runbook.
|
|
82
|
-
|
|
83
|
-
| Release | Highlights |
|
|
84
|
-
|---------|------------|
|
|
85
|
-
| **v2.6.0** | Defensive profile completion — presets + severity tiers (ADR-0029), file-scope / churn / test-to-code guards ([#88](https://github.com/jeger-ai/opengantry/issues/88)–[#91](https://github.com/jeger-ai/opengantry/issues/91)), init onboarding ([#86](https://github.com/jeger-ai/opengantry/issues/86)) |
|
|
86
|
-
| **v2.5.0** | Adopter-ready cage — generic `arch check` roots ([#114](https://github.com/jeger-ai/opengantry/issues/114)), `TARGET_ARCHITECTURE.yaml` init scaffold ([#115](https://github.com/jeger-ai/opengantry/issues/115)), schema 0.2.0 ([#116](https://github.com/jeger-ai/opengantry/issues/116)), defensive profile + net LOC guard ([#87](https://github.com/jeger-ai/opengantry/issues/87), [#90](https://github.com/jeger-ai/opengantry/issues/90)) |
|
|
87
|
-
| **v2.4.0** | Architecture cage — `gantry arch fetch` ([#34](https://github.com/jeger-ai/opengantry/issues/34)), `verify --format sarif\|junit` ([#36](https://github.com/jeger-ai/opengantry/issues/36)), `TARGET_ARCHITECTURE.yaml` + `gantry arch check` ([#15](https://github.com/jeger-ai/opengantry/issues/15)), `ARCHITECTURE_RUBRIC` advisory judge ([#16](https://github.com/jeger-ai/opengantry/issues/16)) |
|
|
88
|
-
| **v2.3.1** | **Breaking:** Planner/Executor rename ([#110](https://github.com/jeger-ai/opengantry/issues/110)) — `gantry planner`, `.gitagent/planner/`, `EXECUTOR_LOG.md`, `GXT_PLANNER_*` / `GXT_EXECUTOR_*` env vars (no aliases). ADR-gated cage: MCP write guard ([#14](https://github.com/jeger-ai/opengantry/issues/14)), break-glass ADR ([#17](https://github.com/jeger-ai/opengantry/issues/17)), optional `planner_signature` tier ([#37](https://github.com/jeger-ai/opengantry/issues/37)) |
|
|
89
|
-
| **v2.3.0** | Cage hardening — `gen:dogfood` ([#105](https://github.com/jeger-ai/opengantry/issues/105)), typed `kpiKind` ([#103](https://github.com/jeger-ai/opengantry/issues/103)), audience-tagged start ([#104](https://github.com/jeger-ai/opengantry/issues/104)), doctor EXECUTOR_LOG checks ([#38](https://github.com/jeger-ai/opengantry/issues/38)), TS/mjs parity ([#106](https://github.com/jeger-ai/opengantry/issues/106)), verify failure contract ([#102](https://github.com/jeger-ai/opengantry/issues/102)), legislate forbidden-zone warn ([#35](https://github.com/jeger-ai/opengantry/issues/35)); removed deprecated `upgrade --apply`/`--dry-run` parent flags |
|
|
90
|
-
| **v2.2.5** | Quality remediation — recursive test glob ([#99](https://github.com/jeger-ai/opengantry/issues/99)), dead verify code prune ([#100](https://github.com/jeger-ai/opengantry/issues/100)–[#101](https://github.com/jeger-ai/opengantry/issues/101)), mechanical cleanups ([#107](https://github.com/jeger-ai/opengantry/issues/107)) |
|
|
91
|
-
| **v2.2.4** | Unified gantry naming cutover ([#94](https://github.com/jeger-ai/opengantry/issues/94)); docs positioning — Gantry.io disambiguation, long-tail SEO (`Open Source Gantry`, `Gantry CLI`, `Gantry Git hook`), vendor-neutral local governance framing ([#95](https://github.com/jeger-ai/opengantry/issues/95)–[#97](https://github.com/jeger-ai/opengantry/issues/97)) |
|
|
92
|
-
| **v2.2.3** | Declarative `trusted_automation` policy in `.gitagent/config.json` — repository-legislated bot maintenance bypass with `max_net_loc <= 5` ([#92](https://github.com/jeger-ai/opengantry/issues/92)) |
|
|
93
|
-
| **v2.2.2** | Time-to-Scaffold benchmark — `npm run examples:benchmark`, measured LOC matrix, adoption discovery ([#79](https://github.com/jeger-ai/opengantry/issues/79)) |
|
|
94
|
-
| **v2.2.1** | Thermo remediation — unified `NormalizedVerifyFailure` contract across JSON/human/context-feed; race-safe remediation snapshot writes; canonical `verify-presentation` entrypoint |
|
|
95
|
-
| **v2.2.0** | `gantry context-feed`, `gantry audit-rigor`, `virtual_capture` ephemeral virtualization ([#68](https://github.com/jeger-ai/opengantry/issues/68)), product positioning, docs quality ([#66](https://github.com/jeger-ai/opengantry/issues/66)–[#69](https://github.com/jeger-ai/opengantry/issues/69), [#76](https://github.com/jeger-ai/opengantry/issues/76)) |
|
|
96
|
-
| **v2.1.0** | Import-layer Code Surgeon (`check-import-layers.mjs --json`, AST quarantine, `GXT_IMPORT_LAYER_VIOLATION`); workspace-resolved optional TypeScript for surgeons |
|
|
97
|
-
| **v2.0.0** | `gantry scan` + KPI gate, `register`, `check-imports`, `perimeter`; BYO `llm_verifiers`; KPI stale binding on `--pre-push`/`--ci` |
|
|
98
|
-
| **v1.1.2** | Verify pipeline close-out (MSN-0034–0035); typed verify phases, trace status at parse boundary |
|
|
99
|
-
| **v1.1.1** | Lib/command boundary, unified `runVerifyCore`, typed remediation, CommandReporter, mission YAML emitter |
|
|
100
|
-
| **v1.1.0** | Stale trace evidence, mission purity PR lock, CI target lock, `verify --json`, doctor substrate drift warn |
|
|
101
|
-
| **v1.0.0** | `gantry init --tutorial`, global `--audience` / `GXT_AUDIENCE`, adoption-first README + runbook |
|
|
102
|
-
| **v0.9.0** | `gantry start`, `verify --fix`, `status --json`, `onboarding`, GXT error codes |
|
|
103
|
-
|
|
104
|
-
## What you get
|
|
105
|
-
|
|
106
|
-
| Idea | Where it lives |
|
|
107
|
-
|------|----------------|
|
|
108
|
-
| **Law** (SOD, trace mapping, risk tiers, TMVC, manifest sync) | [`.gitagent/planner/RULES.md`](.gitagent/planner/RULES.md) |
|
|
109
|
-
| **Routing map** (skills, roots, forbidden zones, path risks) | [`.gitagent/foreman/MANIFEST.json`](.gitagent/foreman/MANIFEST.json) |
|
|
110
|
-
| **Foreman** (cheap, manifest-only triage) | [`.gitagent/foreman/SOUL.md`](.gitagent/foreman/SOUL.md) |
|
|
111
|
-
| **Executor Runtime Contract** (env exports for IDE agents / scripts) | [`.gitagent/planner/RUNTIME.md`](.gitagent/planner/RUNTIME.md) |
|
|
112
|
-
| **Bootstrap** (zero-friction substrate install) | `gantry init` + packaged [`templates/`](templates/) |
|
|
113
|
-
| **Architecture pointer** (where agents find code layout) | [`.gitagent/ARCHITECTURE.pointer.json`](.gitagent/ARCHITECTURE.pointer.json), [ARCHITECTURE-DISCOVERY.md](.gitagent/planner/ARCHITECTURE-DISCOVERY.md) |
|
|
114
|
-
| **Work order + commit receipt** | YAML via `gantry legislate` + [`.gitagent/planner/MISSION.example.yaml`](.gitagent/planner/MISSION.example.yaml); Markdown reference: [`.gitagent/planner/MISSION.template.md`](.gitagent/planner/MISSION.template.md), [`.gitagent/planner/commit-template.md`](.gitagent/planner/commit-template.md) |
|
|
115
|
-
| **gantry CLI** | `npm install -g @jeger-ai/opengantry` or `npx @jeger-ai/opengantry` — see [gantry](#gantry-cli) |
|
|
116
|
-
| **Full orientation + workflow diagram** | [`.gitagent/README.md`](.gitagent/README.md) |
|
|
117
|
-
|
|
118
|
-
Core behaviors in plain language:
|
|
119
|
-
|
|
120
|
-
- **Git-native missions:** commit subjects use **`[MSN-XXXX]`** so history is greppable (`git log --grep='MSN-0042'`).
|
|
121
|
-
- **Auditable execution log:** verifier PASS requires quotes from **`EXECUTOR_LOG.md`** (process control paired with SOD and deterministic gates).
|
|
122
|
-
- **Risk tiers:** cheap automation where safe; stricter human paths for sensitive areas.
|
|
123
|
-
- **Approved edit paths:** work under declared **tmvc_roots**; **forbidden zones** are hard stops; out-of-scope access needs a logged **context request**.
|
|
124
|
-
- **Honest limits:** trace mapping is **not cryptographic proof**—it records what ran under your reviewed mission (see [`.gitagent/planner/RULES.md`](.gitagent/planner/RULES.md)).
|
|
125
|
-
|
|
126
|
-
## Start here (5 minutes)
|
|
42
|
+
Everything revolves around a **mission**:
|
|
127
43
|
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
44
|
+
```mermaid
|
|
45
|
+
flowchart LR
|
|
46
|
+
A[Planner legislates MSN-XXXX] --> B[Executor works in TMVC scope]
|
|
47
|
+
B --> C[Trace in EXECUTOR_LOG.md]
|
|
48
|
+
C --> D[gantry verify]
|
|
49
|
+
D -->|fail| E[findings JSON → agent retries]
|
|
50
|
+
D -->|pass| F[Merge-ready evidence]
|
|
134
51
|
```
|
|
135
52
|
|
|
136
|
-
|
|
53
|
+
**Roles:**
|
|
137
54
|
|
|
138
|
-
|
|
55
|
+
- **Planner:** human (or Mission Architect in chat) approves mission YAML before execution
|
|
56
|
+
- **Executor:** agent or developer edits within TMVC roots; forbidden zones respected
|
|
57
|
+
- **Verifier:** `gantry verify` checks gate output and trace mapping
|
|
139
58
|
|
|
140
|
-
|
|
59
|
+
**Key artifacts in your repo:**
|
|
141
60
|
|
|
142
|
-
|
|
61
|
+
| File | Role |
|
|
62
|
+
|------|------|
|
|
63
|
+
| `.gitagent/missions/MSN-XXXX.yaml` | Scope, `gate_command`, trace rows |
|
|
64
|
+
| `.gitagent/foreman/MANIFEST.json` | Skill routing, TMVC roots, risk tiers |
|
|
65
|
+
| `.gitagent/planner/RULES.md` | Governance law (Tier-3, Planner-only) |
|
|
66
|
+
| `EXECUTOR_LOG.md` | Verbatim PASS quotes for verify |
|
|
67
|
+
| `TARGET_ARCHITECTURE.yaml` | Perimeter rules (imports or regex) |
|
|
143
68
|
|
|
144
|
-
|
|
69
|
+
---
|
|
145
70
|
|
|
146
|
-
|
|
71
|
+
## v3.0.0: Three phases, any domain
|
|
147
72
|
|
|
148
|
-
|
|
149
|
-
|------|-----------|-------------------|
|
|
150
|
-
| **Process-boundary** | `gantry runtime exec` | Agent cannot touch forbidden paths during orchestrated runs |
|
|
151
|
-
| **Deterministic hook** | Cursor `beforeShellExecution`, pre-push verify | Shell/hook writes to governance files require mission + verify |
|
|
152
|
-
| **Advisory** | IDE rules, `AGENTS.md`, sessionStart context | IDE suggestions alone do not count as approval |
|
|
73
|
+
v3.0.0 reframes the product as a **universal governance layer**, not just a TypeScript linter:
|
|
153
74
|
|
|
154
|
-
|
|
75
|
+
| Phase | Command | Output |
|
|
76
|
+
|-------|---------|--------|
|
|
77
|
+
| **Context ingestion** | `gantry init --discover --domain code\|content` | `.gitagent/discovery-proposal.json` |
|
|
78
|
+
| **Rules of engagement** | `gantry blueprint --domain code\|content` | `ARCHITECTURE.md`, `TARGET_ARCHITECTURE.yaml`, `verification_plan.json` |
|
|
79
|
+
| **Standardized audit API** | `gantry verify --json` | `findings[]` failure envelope |
|
|
155
80
|
|
|
156
|
-
###
|
|
81
|
+
### Built-in domain adapters
|
|
157
82
|
|
|
158
|
-
|
|
83
|
+
| Domain | Corpus | Enforcement |
|
|
84
|
+
|--------|--------|-------------|
|
|
85
|
+
| `code` | `.ts`, `.js`, … | Import layers, forbidden specifiers |
|
|
86
|
+
| `content` | `.md`, `.html`, `.txt`, … | `forbid_pattern`, `require_pattern` regex |
|
|
159
87
|
|
|
160
|
-
|
|
161
|
-
npm ci && npm run build # in the OpenGantry repo, or use a globally linked gantry
|
|
162
|
-
gantry init --tutorial # recommended first run; or gantry init (wizard / --yes)
|
|
163
|
-
gantry planner set "$(git config user.email)" # repo-local (recommended)
|
|
164
|
-
gantry doctor
|
|
165
|
-
git config core.hooksPath .githooks
|
|
166
|
-
```
|
|
88
|
+
List them: `gantry domains`
|
|
167
89
|
|
|
168
|
-
|
|
90
|
+
**Court-of-law principle:** enforcement is always binary. Content discovery uses exact-match boilerplate only; it does not infer "dominant terminology" from statistics that would flip on unrelated edits.
|
|
169
91
|
|
|
170
|
-
|
|
171
|
-
- **Non-TTY / CI:** auto-applies default profile (core + Cursor + hooks + CI) — no hang.
|
|
172
|
-
- **`--yes`:** default profile without prompts. **`--dry-run`:** print planned writes.
|
|
173
|
-
- **Flags:** `--ides cursor,claude-code`, `--docs-path`, `--skills minimal|specimen`, `--no-hooks`, `--no-ci`, `--arch-source`, `--arch-location`.
|
|
92
|
+
See [`docs/DOMAINS.md`](docs/DOMAINS.md) for adapter details and [`docs/AGENT-LOOP.md`](docs/AGENT-LOOP.md) for external executor integration.
|
|
174
93
|
|
|
175
|
-
|
|
94
|
+
---
|
|
176
95
|
|
|
177
|
-
|
|
178
|
-
- `managed_strict` runtime assets (workflow, validate script, hooks, schema/rules pointers) prompt before overwrite in an interactive terminal; use `--force` to skip the prompt.
|
|
96
|
+
## Feature tour: what to try first
|
|
179
97
|
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
After `init`, customize your manifest and skills, then legislate. See [`docs/ADOPTION.md`](docs/ADOPTION.md) for the exact ordered runbook.
|
|
183
|
-
|
|
184
|
-
### 2. Customize for your project
|
|
185
|
-
|
|
186
|
-
- Edit **[`.gitagent/foreman/MANIFEST.json`](.gitagent/foreman/MANIFEST.json)**
|
|
187
|
-
Set `path_risks`, `risk_keywords`, and each skill's `tmvc_roots`, `forbidden_zones`, and `trust_threshold` to match **your** directories and risk appetite.
|
|
188
|
-
- Align **[`.gitagent/planner/RULES.md`](.gitagent/planner/RULES.md)** with your review policy (tiers, who counts as "human audit", merge gates).
|
|
189
|
-
- Point **deterministic gates** in missions at **your** stack (`npm test`, `pytest`, `cargo test`, etc.).
|
|
190
|
-
- Store mission files you intend to **`gantry verify`** under **`.gitagent/missions/`** and configure **Planner allowlist** per repo (`gantry planner set`, `.gitagent/foreman/PLANNER.allowlist.local`, or `git config gantry.plannerEmails`).
|
|
191
|
-
|
|
192
|
-
**Concrete gate example** (YAML fields in a mission file; adjust paths and commands):
|
|
193
|
-
|
|
194
|
-
```yaml
|
|
195
|
-
gate_command: "npm test -- src/components/Button.test.tsx"
|
|
196
|
-
gate_success_substring: "Tests: 1 passed"
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
The gate is whatever command **fails closed** for your repo (lint, typecheck, integration suite). One explicit command beats a vague "run tests somewhere." Primary reference: [`.gitagent/planner/MISSION.example.yaml`](.gitagent/planner/MISSION.example.yaml). Markdown missions remain supported (`gantry verify` parses both); [`.gitagent/planner/MISSION.template.md`](.gitagent/planner/MISSION.template.md) is a human-readable reference, not the `legislate` default.
|
|
200
|
-
|
|
201
|
-
### gantry CLI
|
|
202
|
-
|
|
203
|
-
The **Gantry CLI** (`gantry`) is the primary interface for **Open Source Gantry** — local, vendor-neutral, git-native governance in your repository.
|
|
204
|
-
|
|
205
|
-
Requires **Node.js 24+** (Active LTS line). Published as **`@jeger-ai/opengantry`** on npm; the `gantry` binary is registered via `package.json` `bin` (see [`package.json`](package.json)). The legacy `gapman` command remains a compatibility alias. Config namespaces: `GANTRY_*` env vars and `git config gantry.*` (legacy `GAPMAN_*` / `gapman.*` values are still read silently). From source: `npm ci && npm run build` → `dist/cli/index.js`.
|
|
206
|
-
|
|
207
|
-
**Developing OpenGantry:** dogfood the full stack — [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) (missions, hooks, verify, `npm run validate`). Layer rules: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Adopters: [`docs/ADOPTION.md`](docs/ADOPTION.md). Roadmap: [`docs/BACKLOG.md`](docs/BACKLOG.md) · [Project board](https://github.com/orgs/jeger-ai/projects/2).
|
|
208
|
-
|
|
209
|
-
**Adoption path:**
|
|
210
|
-
|
|
211
|
-
| Step | Command | Outcome |
|
|
212
|
-
|------|---------|---------|
|
|
213
|
-
| Onboard | `gantry init --tutorial` or `gantry onboarding` | Feel Planner stamp + verify loop (~3 min) |
|
|
214
|
-
| Scope + approve | `gantry start` → Planner `[MSN-…]` commit | Unreviewed stub cannot pass full verify |
|
|
215
|
-
| Prove work | `gantry verify` | Gate + log quotes + greppable history |
|
|
216
|
-
|
|
217
|
-
**Global output:** `gantry --audience executor\|planner\|verifier\|platform <cmd>` (or `GXT_AUDIENCE=verifier` in CI — silence unless `[GXT_*]` errors).
|
|
218
|
-
|
|
219
|
-
| Command | Purpose |
|
|
220
|
-
|--------|---------|
|
|
221
|
-
| `gantry init` | Bootstrap substrate + IDE packs + hooks + CI. `--tutorial` runs guided first loop after scaffold. |
|
|
222
|
-
| `gantry upgrade` | Plan substrate updates (`gantry upgrade plan` / `--dry-run` for preview JSON). Stage with `gantry upgrade`; `gantry upgrade apply --mission …` after Planner commit. |
|
|
223
|
-
| `gantry check` | Validate `MANIFEST.json` shape + **Rule 4.4** sync: every `manifest.skills` key must have `skills/<key>.md`, with no orphan skill files. |
|
|
224
|
-
| `gantry status` | GXT readiness dashboard (`--json`, `--verbose`, `--audience executor\|planner\|verifier\|platform`). |
|
|
225
|
-
| `gantry start "<intent>"` | Goal-first orchestration: triage → legislate stub → runtime next steps (`--msn`, `--skill-key`, `--json`). |
|
|
226
|
-
| `gantry onboarding` | Interactive walkthrough of the strict mission loop. Blocks on corrupt configured integration state; allows pristine uninitialized repos. |
|
|
227
|
-
| `gantry doctor` | Active readiness check (manifest, Planner email, bypass secret match, hooks, architecture pointer, integration staleness). Warnings exit 0. `--audience` tailors next steps. |
|
|
228
|
-
| `gantry triage "<intent>"` | Foreman-style routing ([`SOUL.md`](.gitagent/foreman/SOUL.md)). `--json` for machine output (may include non-binding `adr_hints` from [`.gitagent/out-of-scope/`](.gitagent/out-of-scope/README.md)). `--emit-mission --msn MSN-0007` writes `.gitagent/missions/ACTIVE_MISSION.md` by default on **DIRECT_EXECUTION** only. |
|
|
229
|
-
| `gantry planner show\|set` | Repo-local Planner git-proof allowlist (`.gitagent/foreman/PLANNER.allowlist.local`; avoids global `GANTRY_PLANNER_EMAILS` leaking across projects). |
|
|
230
|
-
| `gantry legislate "<intent>" --msn MSN-0007` | Emit stub **YAML** mission under `.gitagent/missions/` with explicit MSN (`--skill-key` when triage would escalate; `--gate-command` / `--gate-success-substring` for one-click handoff). Planner still **`git commit`**-legislates from an allowlisted email. |
|
|
231
|
-
| `gantry mission validate --file <path>` | Validate a mission `.md` or `.yaml` (YAML checked against [`.gitagent/planner/MISSION.schema.yaml`](.gitagent/planner/MISSION.schema.yaml)). |
|
|
232
|
-
| `gantry mission snapshot --file <path>` | Write start-state JSON under `.gitagent/history/` (git HEAD, branch, dirty flag, manifest hash, hashes of files under the mission skill's `tmvc_roots`). |
|
|
233
|
-
| `gantry runtime env --mission <path>` | Executor Runtime Contract: emit `GXT_REPO_ROOT`, `GXT_MISSION_FILE`, `GXT_MSN_ID`, `GXT_SKILL_KEY`, `GXT_TMVC_ROOTS`, `GXT_FORBIDDEN_ZONES`, `GXT_EXECUTOR_LOG`. Default: POSIX `export …` lines; `--json` for scripts. [.gitagent/planner/RUNTIME.md](.gitagent/planner/RUNTIME.md). |
|
|
234
|
-
| `gantry runtime exec --mission <path> -- <cmd…>` | Run executor command with mission env, telemetry capture, and forbidden-zone scan (strongest TMVC trap). |
|
|
235
|
-
| `gantry context-request --path <p…> --reason <text>` | Append a PENDING Context Request to `EXECUTOR_LOG.md` (RULES §4 TMVC expansion). Uses pinned mission or `--mission`. `--stage-worker-log` opt-in stages the log. |
|
|
236
|
-
| `gantry tmvc guard [--strict]` | Pre-commit TMVC path guard: advisory warnings on staged paths outside mission `tmvc_roots` (stderr; exit 0). `--strict` or `GXT_TMVC_GUARD_STRICT=1` blocks. Skips when no pinned mission. |
|
|
237
|
-
| `gantry mcp serve` | Stdio MCP server exposing `gxt_*` tools (legislation, pin, runtime env, verify with `fix_hints`, `gxt_start_orchestration`, exec). `gxt_verify` uses the flat `--json` envelope — see [ADOPTION.md § MCP verify envelope](docs/ADOPTION.md). Configure via `.cursor/mcp.json`. |
|
|
238
|
-
| `gantry verify --mission <path>` | Teacher-approved mission commit + gate + trace. **`--json`** structured output (`status`, `phase`, `error_code`, `fix_hints`). **`--fix`** guided repair; when a **Code Surgeon** applies a quarantine mutation, logs `[SURGEON-MUTATION]` to `EXECUTOR_LOG.md` and reruns full verify with fix disabled (never auto-PASS). CI: `--audience verifier` (errors only). Failures emit **`GXT_*`** codes. Optional **`kpi_gate`** phase reads committed [KPI report](.gitagent/planner/KPI-REPORT.schema.yaml) (after gate, before trace). **`--ci`** / **`--pre-push`**: fail-closed on stale KPI evidence. |
|
|
239
|
-
| `gantry scan --mission <path>` | Run mission `llm_verifiers` (BYO commands) and write namespaced KPI report JSON for `kpi_gate`. |
|
|
240
|
-
| `gantry register <dir>` | AST discovery: propose skill scope from folder imports/exports (does not mutate `MANIFEST.json`). |
|
|
241
|
-
| `gantry check-imports <dir> --ban <spec…>` | Deterministic banned-import scan (usable as `gate_command`; no LLM). |
|
|
242
|
-
| `gantry perimeter [--base-ref <ref>] [--ci]` | Protected governance paths: local advisory; **`--ci`** requires verified commit signatures. |
|
|
243
|
-
| `gantry arch pointer` | Print architecture pointer summary for agents (`.gitagent/ARCHITECTURE.pointer.json`). |
|
|
244
|
-
| `gantry arch fetch` | Fetch `kind=external` architecture docs into a local cache (doctor stays offline). |
|
|
245
|
-
| `gantry arch check` | Evaluate `TARGET_ARCHITECTURE.yaml` import/layer rules for TypeScript paths under configured roots. |
|
|
246
|
-
| `gantry arch cred status\|set\|unset` | Git-ignored credential slots for authenticated external architecture sources (secrets via stdin only). |
|
|
247
|
-
| `gantry metrics [--json] [--ref main]` | Git-native governance rollup (`--json` includes `gxt_extension_metadata`). See [`docs/ADOPTION.md`](docs/ADOPTION.md). |
|
|
248
|
-
| `gantry context-feed [--json] [--clear]` | Read or atomically clear the latest verify remediation snapshot (`.gitagent/tmp/NEXT_REMEDIATION.json`) for IDE repair loops. |
|
|
249
|
-
| `gantry audit-rigor [--json] [--strict]` | Meta-governance audit: TypeScript strictness, coverage artifacts, MANIFEST wildcard hygiene. |
|
|
250
|
-
|
|
251
|
-
**Who can approve missions (Planner allowlist):** only allowlisted identities can legislate missions that verify accepts. Precedence:
|
|
252
|
-
|
|
253
|
-
1. `.gitagent/foreman/PLANNER.allowlist` (+ optional gitignored `.local` merge)
|
|
254
|
-
2. `git config gantry.plannerEmails "a@x.com,b@y.com"`
|
|
255
|
-
3. `GANTRY_PLANNER_EMAILS` env (CI escape hatch only)
|
|
256
|
-
4. implicit `git config user.email` when nothing else is set
|
|
257
|
-
|
|
258
|
-
Use **`gantry planner set "$(git config user.email)"`** after clone — do not rely on a global shell export when you work across multiple projects.
|
|
259
|
-
|
|
260
|
-
### Executor Runtime quickstart
|
|
261
|
-
|
|
262
|
-
Agents (Cursor, Junie, local scripts) should not guess TMVC roots — read them from **`gantry runtime env`**.
|
|
263
|
-
|
|
264
|
-
Each `--mission` path must refer to **an existing mission file** (ENOENT means the YAML or Markdown mission is missing). Split these into separate shell steps if you paste from docs.
|
|
98
|
+
### 1. Bootstrap a repo
|
|
265
99
|
|
|
266
100
|
```bash
|
|
267
|
-
npm
|
|
268
|
-
|
|
269
|
-
# Existing mission (tracked example — swap for yours after Planner legislates it):
|
|
270
|
-
eval "$(node dist/cli/index.js runtime env --mission .gitagent/missions/example.verify.yaml)"
|
|
271
|
-
|
|
272
|
-
# Or machine-readable JSON for a wrapper script:
|
|
273
|
-
node dist/cli/index.js runtime env --mission .gitagent/missions/example.verify.yaml --json
|
|
274
|
-
|
|
275
|
-
# Headless / CI — strongest TMVC trap:
|
|
276
|
-
node dist/cli/index.js runtime exec --mission .gitagent/missions/example.verify.yaml -- <your-agent-command>
|
|
101
|
+
npm install -g @jeger-ai/opengantry
|
|
102
|
+
gantry init --tutorial
|
|
277
103
|
```
|
|
278
104
|
|
|
279
|
-
|
|
105
|
+
Scaffolds `.gitagent/`, hooks, manifest, and walks you through the first mission loop.
|
|
280
106
|
|
|
281
|
-
|
|
107
|
+
### 2. Fast-path discovery
|
|
282
108
|
|
|
283
109
|
```bash
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
# eval "$(node dist/cli/index.js runtime env --mission .gitagent/missions/MSN-0007.<slug>.yaml)"
|
|
110
|
+
gantry init --discover --domain code # scan TS/JS imports
|
|
111
|
+
gantry init --discover --domain content # scan markdown corpora
|
|
287
112
|
```
|
|
288
113
|
|
|
289
|
-
|
|
114
|
+
Emits a proposal with evidence-anchored conventions and anomalies (`file:line` snippets). Nothing becomes law until a human confirms or runs blueprint.
|
|
290
115
|
|
|
291
|
-
|
|
116
|
+
**Speed:** the discovery scanner uses streaming regex per file, not a whole-repo AST. It is budgeted to finish a **5,000-file monorepo in under five seconds** (pinned in CI). OpenGantry ingests repository context in seconds without loading the tree into a heavy compiler graph or spiking RAM. Enterprise teams do not have to wait minutes for a governance tool to "understand" the repo before the agent loop starts.
|
|
292
117
|
|
|
293
|
-
|
|
294
|
-
- **[`AGENTS.md`](AGENTS.md)** tells agents to read **RULES** + **MANIFEST** before acting.
|
|
295
|
-
- **[`.cursor/rules/opengantry-gxt-substrate.mdc`](.cursor/rules/opengantry-gxt-substrate.mdc)** does the same for Cursor with `alwaysApply: true`.
|
|
296
|
-
- **CI:** this repo includes **[`.github/workflows/gxt-validate.yml`](.github/workflows/gxt-validate.yml)**:
|
|
297
|
-
- **PR governance (PR only):** mission PRs must target the **default branch** (`main` in this repo; `github.event.repository.default_branch` in init template, overridable via `GXT_INTEGRATION_BRANCH`) — prevents stacked mission merges.
|
|
298
|
-
- **gantry:** `npm ci` / `npm run build`, then `gantry check`, `gantry doctor`, and unit tests.
|
|
299
|
-
- **Manifest (jq parity):** validates [`.gitagent/foreman/MANIFEST.json`](.gitagent/foreman/MANIFEST.json) via [`scripts/validate-gxt.sh`](scripts/validate-gxt.sh) `manifest`.
|
|
300
|
-
- **Changed-code quality (PR only):** ESLint complexity, import layers, line budgets on touched `src/cli/**/*.ts`.
|
|
301
|
-
- **MSN (PR only, path-scoped):** on **pull_request** only, any **non-merge** commit in the PR range that touches `.gitagent/`, repo-root `EXECUTOR_LOG.md`, `.githooks/`, or [`.github/workflows/gxt-validate.yml`](.github/workflows/gxt-validate.yml) must have a subject starting with **`[MSN-NNNN]`** (four digits). Other paths (e.g. root `README.md` only) do not trigger this check.
|
|
302
|
-
- **Mission purity (PR only):** [`scripts/verify-pr-missions.sh`](scripts/verify-pr-missions.sh) requires exactly one `[MSN-NNNN]` in `${base}..${head}` commit subjects before full `gantry verify` on changed missions.
|
|
303
|
-
- **Local (full stack):** [`scripts/dev-validate.sh`](scripts/dev-validate.sh) / `npm run validate` — superset of CI (includes changed-code + MSN vs `origin/main`).
|
|
118
|
+
### 3. Blueprint: negotiate the contract
|
|
304
119
|
|
|
305
120
|
```bash
|
|
306
|
-
|
|
307
|
-
node dist/cli/index.js check
|
|
308
|
-
node dist/cli/index.js doctor
|
|
309
|
-
./scripts/validate-gxt.sh manifest
|
|
310
|
-
./scripts/validate-gxt.sh msn origin/main HEAD # after: git fetch origin
|
|
311
|
-
# or full local stack:
|
|
312
|
-
npm run validate
|
|
121
|
+
gantry blueprint --domain content --yes
|
|
313
122
|
```
|
|
314
123
|
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
High level: **Foreman** routes → **Planner** authors a mission when needed → **Worker** executes inside TMVC and writes **`EXECUTOR_LOG.md`** → **deterministic gate** runs → **Verifier** maps passes to the log → commits follow **`[MSN-XXXX]`** + receipt template.
|
|
124
|
+
Produces three artifacts:
|
|
318
125
|
|
|
319
|
-
|
|
126
|
+
- **`ARCHITECTURE.md`:** human-readable decisions with evidence links
|
|
127
|
+
- **`TARGET_ARCHITECTURE.yaml`:** machine-checkable rules (schema 0.3.0 for content)
|
|
128
|
+
- **`.gitagent/verification_plan.json`:** `gate_commands` and `required_skills` gaps
|
|
320
129
|
|
|
321
|
-
|
|
130
|
+
The executor agent reads `required_skills` and builds missing tooling *before* coding.
|
|
322
131
|
|
|
323
|
-
|
|
132
|
+
### 4. Perimeter enforcement
|
|
324
133
|
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
- Optionally `.cursor/rules/opengantry-gxt-substrate.mdc` if you use Cursor
|
|
134
|
+
```bash
|
|
135
|
+
gantry arch check # code: import/layer rules
|
|
136
|
+
gantry perimeter check # domain-neutral alias (same engine)
|
|
137
|
+
```
|
|
330
138
|
|
|
331
|
-
|
|
139
|
+
For content, rules look like:
|
|
332
140
|
|
|
333
|
-
```
|
|
334
|
-
|
|
335
|
-
|
|
141
|
+
```yaml
|
|
142
|
+
forbid_pattern: "(?i)cures cancer"
|
|
143
|
+
require_pattern: "These statements have not been evaluated by the FDA"
|
|
336
144
|
```
|
|
337
145
|
|
|
338
|
-
|
|
146
|
+
Violations carry `file` and `line` for the failure envelope.
|
|
339
147
|
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
**Primary path (npm):** install or update the CLI package, then apply bundled substrate changes in your repo:
|
|
148
|
+
### 5. Mission + verify
|
|
343
149
|
|
|
344
150
|
```bash
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
|
|
349
|
-
gantry
|
|
151
|
+
gantry legislate "add feature X" --msn MSN-0042 --skill-key gantry
|
|
152
|
+
# Planner commits [MSN-0042] mission YAML
|
|
153
|
+
eval "$(gantry runtime env --mission .gitagent/missions/MSN-0042.yaml)"
|
|
154
|
+
# ... do work, append trace to EXECUTOR_LOG.md ...
|
|
155
|
+
gantry verify --mission .gitagent/missions/MSN-0042.yaml --json
|
|
350
156
|
```
|
|
351
157
|
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
**Alternative — vendor `.gitagent/` without npm** (no Node required in the host repo):
|
|
158
|
+
On failure, external agents ingest `findings[]`:
|
|
355
159
|
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
160
|
+
```json
|
|
161
|
+
{
|
|
162
|
+
"failed_gate": "arch",
|
|
163
|
+
"offending_file": "content/ad-bad.md",
|
|
164
|
+
"line": 3,
|
|
165
|
+
"severity": "error",
|
|
166
|
+
"resolution_hint": "..."
|
|
167
|
+
}
|
|
362
168
|
```
|
|
363
169
|
|
|
364
|
-
|
|
170
|
+
**No terminal vomit:** agents do not scrape unstructured stderr or guess which line failed. The `findings[]` envelope is a **predictable, structured audit API** built for autonomous retry loops: each item names the gate, file, line, severity, and a resolution hint. Same payload on `--json`, SARIF, and MCP `gxt_verify`.
|
|
365
171
|
|
|
366
|
-
|
|
172
|
+
### 6. Content governance example
|
|
367
173
|
|
|
368
|
-
|
|
369
|
-
git clone https://github.com/jeger-ai/opengantry.git /tmp/opengantry && \
|
|
370
|
-
diff -ru .gitagent /tmp/opengantry/.gitagent | less
|
|
371
|
-
# Then selectively copy files you want (e.g. RULES.md) without overwriting your manifest.
|
|
372
|
-
```
|
|
174
|
+
See [`examples/content-governance/`](examples/content-governance/). Ad copy with seeded violations (forbidden claim, missing disclaimer, wrong brand hex). Same loop as code; different adapter.
|
|
373
175
|
|
|
374
|
-
|
|
176
|
+
### 7. IDE integration
|
|
375
177
|
|
|
376
|
-
|
|
178
|
+
- **Cursor MCP:** `gxt_draft_legislation`, `gxt_verify`, `gxt_pin_mission`
|
|
179
|
+
- **Hooks:** session start loads pinned mission; shell guards block unscoped substrate writes
|
|
180
|
+
- Details: [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md)
|
|
377
181
|
|
|
378
|
-
|
|
379
|
-
curl -fsSL -o .gitagent/planner/MISSION.example.yaml \
|
|
380
|
-
https://raw.githubusercontent.com/jeger-ai/opengantry/main/.gitagent/planner/MISSION.example.yaml
|
|
381
|
-
```
|
|
382
|
-
|
|
383
|
-
Always **review the diff** before commit; never bulk-overwrite a customized `MANIFEST.json`.
|
|
182
|
+
---
|
|
384
183
|
|
|
385
|
-
## OpenGantry
|
|
184
|
+
## What OpenGantry is *not*
|
|
386
185
|
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
| Cloud observability / agent dashboards | Hosted UI for metrics, traces, or agent session visibility | Strong for **fleet visibility**; per-repo change authorization and Git-native audit artifacts are typically layered separately |
|
|
391
|
-
| Agent "swarm" / choreography layers | Orchestrates model calls across services; emphasizes throughput and parallelism | Strong on **coverage** of tasks; lineage and per-change evidence depends on tooling above the swarm |
|
|
392
|
-
| Unstructured desktop assistants | Reactive help in-editor or OS-wide; informal plans | Lightweight for exploration; weakest default for **reproducible** production sign-off without additional discipline |
|
|
186
|
+
- **Not an agent:** it does not chat, plan features, or generate PRs by itself
|
|
187
|
+
- **Not Gantry.io:** no hosted observability dashboard; everything runs in your repo
|
|
188
|
+
- **Not an LLM judge** (yet): AI performance judge is deferred to v3.1; gates stay deterministic
|
|
393
189
|
|
|
394
|
-
|
|
190
|
+
---
|
|
395
191
|
|
|
396
|
-
##
|
|
192
|
+
## Mental model for adopters
|
|
397
193
|
|
|
398
|
-
|
|
194
|
+
```
|
|
195
|
+
OpenGantry = contract negotiator + court + audit log
|
|
196
|
+
Executor agent = worker (Cursor, Hermes, human dev)
|
|
197
|
+
```
|
|
399
198
|
|
|
400
|
-
|
|
199
|
+
You adopt OpenGantry when agent velocity is valuable but **unreviewed scope creep, silent governance edits, or unverifiable "it works" claims** are unacceptable.
|
|
401
200
|
|
|
402
|
-
|
|
201
|
+
---
|
|
403
202
|
|
|
404
|
-
##
|
|
203
|
+
## Where to go next
|
|
405
204
|
|
|
406
|
-
|
|
205
|
+
| Goal | Doc |
|
|
206
|
+
|------|-----|
|
|
207
|
+
| 5-minute adoption | [`docs/ADOPTION.md`](docs/ADOPTION.md) |
|
|
208
|
+
| Domain adapters deep dive | [`docs/DOMAINS.md`](docs/DOMAINS.md) |
|
|
209
|
+
| External agent integration | [`docs/AGENT-LOOP.md`](docs/AGENT-LOOP.md) |
|
|
210
|
+
| Contributing / dogfooding this repo | [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) |
|
|
211
|
+
| Content walkthrough | [`examples/content-governance/`](examples/content-governance/) |
|
|
@@ -18,6 +18,7 @@ export interface ArchFetchOptions extends ArchOptions {
|
|
|
18
18
|
export interface ArchCheckOptions extends ArchOptions {
|
|
19
19
|
json?: boolean;
|
|
20
20
|
files?: string[];
|
|
21
|
+
label?: "arch" | "perimeter";
|
|
21
22
|
}
|
|
22
23
|
export declare function runArchPointer(options?: ArchOptions): void;
|
|
23
24
|
export declare function runArchCredSet(options: ArchCredSetOptions): Promise<void>;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"arch.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/arch.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"arch.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/arch.ts"],"names":[],"mappings":"AAmBA,OAAO,EAOL,KAAK,0BAA0B,EAChC,MAAM,mCAAmC,CAAC;AAE3C,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,0BAA0B,CAAC;CAClC;AAED,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACvD,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,qBAAsB,SAAQ,WAAW;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAAC;CAC9B;AAiBD,wBAAgB,cAAc,CAAC,OAAO,GAAE,WAAgB,GAAG,IAAI,CAO9D;AAED,wBAAsB,cAAc,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAU/E;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI,CASpE;AAED,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,qBAA0B,GAAG,IAAI,CAI3E;AAED,wBAAsB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAgBhF;AAED,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,gBAAqB,GAAG,IAAI,CAiCxE"}
|