@jeger-ai/opengantry 2.7.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.
Files changed (100) hide show
  1. package/README.md +132 -328
  2. package/dist/cli/commands/arch.d.ts +1 -0
  3. package/dist/cli/commands/arch.d.ts.map +1 -1
  4. package/dist/cli/commands/arch.js +17 -6
  5. package/dist/cli/commands/arch.js.map +1 -1
  6. package/dist/cli/commands/blueprint.d.ts +7 -0
  7. package/dist/cli/commands/blueprint.d.ts.map +1 -0
  8. package/dist/cli/commands/blueprint.js +69 -0
  9. package/dist/cli/commands/blueprint.js.map +1 -0
  10. package/dist/cli/commands/init.d.ts +3 -0
  11. package/dist/cli/commands/init.d.ts.map +1 -1
  12. package/dist/cli/commands/init.js +12 -0
  13. package/dist/cli/commands/init.js.map +1 -1
  14. package/dist/cli/lib/architecture-drift-doctor.d.ts +4 -0
  15. package/dist/cli/lib/architecture-drift-doctor.d.ts.map +1 -0
  16. package/dist/cli/lib/architecture-drift-doctor.js +58 -0
  17. package/dist/cli/lib/architecture-drift-doctor.js.map +1 -0
  18. package/dist/cli/lib/blueprint-engine.d.ts +22 -0
  19. package/dist/cli/lib/blueprint-engine.d.ts.map +1 -0
  20. package/dist/cli/lib/blueprint-engine.js +127 -0
  21. package/dist/cli/lib/blueprint-engine.js.map +1 -0
  22. package/dist/cli/lib/discovery-proposal.d.ts +19 -0
  23. package/dist/cli/lib/discovery-proposal.d.ts.map +1 -0
  24. package/dist/cli/lib/discovery-proposal.js +110 -0
  25. package/dist/cli/lib/discovery-proposal.js.map +1 -0
  26. package/dist/cli/lib/discovery-scanner.d.ts +47 -0
  27. package/dist/cli/lib/discovery-scanner.d.ts.map +1 -0
  28. package/dist/cli/lib/discovery-scanner.js +81 -0
  29. package/dist/cli/lib/discovery-scanner.js.map +1 -0
  30. package/dist/cli/lib/doctor-core.d.ts.map +1 -1
  31. package/dist/cli/lib/doctor-core.js +2 -0
  32. package/dist/cli/lib/doctor-core.js.map +1 -1
  33. package/dist/cli/lib/domains/domain-adapter.d.ts +38 -0
  34. package/dist/cli/lib/domains/domain-adapter.d.ts.map +1 -0
  35. package/dist/cli/lib/domains/domain-adapter.js +20 -0
  36. package/dist/cli/lib/domains/domain-adapter.js.map +1 -0
  37. package/dist/cli/lib/domains/domain-code.d.ts +3 -0
  38. package/dist/cli/lib/domains/domain-code.d.ts.map +1 -0
  39. package/dist/cli/lib/domains/domain-code.js +171 -0
  40. package/dist/cli/lib/domains/domain-code.js.map +1 -0
  41. package/dist/cli/lib/domains/domain-content.d.ts +3 -0
  42. package/dist/cli/lib/domains/domain-content.d.ts.map +1 -0
  43. package/dist/cli/lib/domains/domain-content.js +190 -0
  44. package/dist/cli/lib/domains/domain-content.js.map +1 -0
  45. package/dist/cli/lib/domains/index.d.ts +5 -0
  46. package/dist/cli/lib/domains/index.d.ts.map +1 -0
  47. package/dist/cli/lib/domains/index.js +5 -0
  48. package/dist/cli/lib/domains/index.js.map +1 -0
  49. package/dist/cli/lib/errors.d.ts +0 -6
  50. package/dist/cli/lib/errors.d.ts.map +1 -1
  51. package/dist/cli/lib/errors.js +0 -4
  52. package/dist/cli/lib/errors.js.map +1 -1
  53. package/dist/cli/lib/gxt-error-codes.d.ts +0 -2
  54. package/dist/cli/lib/gxt-error-codes.d.ts.map +1 -1
  55. package/dist/cli/lib/gxt-error-codes.js +0 -2
  56. package/dist/cli/lib/gxt-error-codes.js.map +1 -1
  57. package/dist/cli/lib/init-discover.d.ts +14 -0
  58. package/dist/cli/lib/init-discover.d.ts.map +1 -0
  59. package/dist/cli/lib/init-discover.js +45 -0
  60. package/dist/cli/lib/init-discover.js.map +1 -0
  61. package/dist/cli/lib/target-architecture.d.ts +12 -3
  62. package/dist/cli/lib/target-architecture.d.ts.map +1 -1
  63. package/dist/cli/lib/target-architecture.js +108 -8
  64. package/dist/cli/lib/target-architecture.js.map +1 -1
  65. package/dist/cli/lib/verification-plan.d.ts +22 -0
  66. package/dist/cli/lib/verification-plan.d.ts.map +1 -0
  67. package/dist/cli/lib/verification-plan.js +26 -0
  68. package/dist/cli/lib/verification-plan.js.map +1 -0
  69. package/dist/cli/lib/verify-export.d.ts.map +1 -1
  70. package/dist/cli/lib/verify-export.js +27 -17
  71. package/dist/cli/lib/verify-export.js.map +1 -1
  72. package/dist/cli/lib/verify-failure-normalize.d.ts +2 -1
  73. package/dist/cli/lib/verify-failure-normalize.d.ts.map +1 -1
  74. package/dist/cli/lib/verify-failure-normalize.js +37 -1
  75. package/dist/cli/lib/verify-failure-normalize.js.map +1 -1
  76. package/dist/cli/lib/verify-finding.d.ts +16 -0
  77. package/dist/cli/lib/verify-finding.d.ts.map +1 -0
  78. package/dist/cli/lib/verify-finding.js +11 -0
  79. package/dist/cli/lib/verify-finding.js.map +1 -0
  80. package/dist/cli/lib/verify-payload.d.ts +4 -0
  81. package/dist/cli/lib/verify-payload.d.ts.map +1 -1
  82. package/dist/cli/lib/verify-payload.js +1 -1
  83. package/dist/cli/lib/verify-payload.js.map +1 -1
  84. package/dist/cli/lib/version.gen.d.ts +1 -1
  85. package/dist/cli/lib/version.gen.js +1 -1
  86. package/dist/cli/program-blueprint.d.ts +3 -0
  87. package/dist/cli/program-blueprint.d.ts.map +1 -0
  88. package/dist/cli/program-blueprint.js +12 -0
  89. package/dist/cli/program-blueprint.js.map +1 -0
  90. package/dist/cli/program-core.d.ts.map +1 -1
  91. package/dist/cli/program-core.js +5 -1
  92. package/dist/cli/program-core.js.map +1 -1
  93. package/dist/cli/program-workflow.d.ts.map +1 -1
  94. package/dist/cli/program-workflow.js +19 -1
  95. package/dist/cli/program-workflow.js.map +1 -1
  96. package/dist/cli/program.d.ts.map +1 -1
  97. package/dist/cli/program.js +2 -0
  98. package/dist/cli/program.js.map +1 -1
  99. package/package.json +1 -1
  100. package/templates/.gitagent/foreman/SUBSTRATE.version.json +1 -1
package/README.md CHANGED
@@ -1,407 +1,211 @@
1
- # OpenGantry
1
+ # OpenGantry: What It Is, Why It Exists, and How to Use It
2
2
 
3
- **OpenGantry is a platform for Autonomous Repository Engineering** — AI-assisted product delivery where every material agent change is scoped before execution, verified by deterministic gates, and traceable in Git before merge.
3
+ ## The one-line pitch
4
4
 
5
- It is **not** a real-time conversational agent wrapper. Use OpenGantry when you need auditable, mission-scoped repository work with explicit Planner approval and forensic trace.
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
- > **Not [Gantry.io](https://gantry.io)?** **Open Source Gantry** is the **`gantry` CLI** for **local-first**, **vendor-neutral**, **git-native governance** in your repository not a hosted observability dashboard. If you are looking for infrastructure monitoring, see [Gantry.io](https://gantry.io).
7
+ Think of it as a **court of law** for agentic work: binary rules, reproducible checks, audit trail in Git.
8
8
 
9
- Use OpenGantry when you need:
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
- - **Agent-assisted product delivery without silent scope creep:** keep velocity while forcing explicit mission scope and path boundaries.
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
- ### What you get in production
13
+ ## Vision
16
14
 
17
- - **Review before run:** executors do not complete the loop until a human-approved mission defines scope, gates, and trace rows.
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
- **Protocol (implementers):** under the hood, **GXT (Git-native eXecution and Trace)** binds law, Foreman routing, deterministic gates, and trace mapping to `EXECUTOR_LOG.md`. This repository is both the **specimen** and the **template**. Run **`gantry init`** (or **`gantry init --tutorial`**) in your repo and adapt it.
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
- ## Gantry CLI local-first governance
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
- **Open Source Gantry** ships as the **Gantry CLI** (`npm install -g @jeger-ai/opengantry`). Governance runs **in your repo** — missions, deterministic gates, and **Gantry Git hook** enforcement (`.githooks/`, IDE hooks) — without routing agent work through a vendor cloud dashboard.
24
+ ---
26
25
 
27
- | Goal | Read first |
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
- ## Install
28
+ Without governance glue, agent-assisted repos tend toward:
35
29
 
36
- Requires **Node.js 24+**.
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
- ```bash
39
- npm install -g @jeger-ai/opengantry
40
- gantry init --tutorial
41
- ```
42
-
43
- Or without a global install:
38
+ ---
44
39
 
45
- ```bash
46
- npx @jeger-ai/opengantry init --tutorial
47
- ```
40
+ ## The core loop (GXT)
48
41
 
49
- Developing this repository from source: `npm ci && npm run build` — see [gantry CLI](#gantry-cli) and [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md).
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.7.0** — unified CLI naming (`gantry` primary; legacy `gapman` alias, deprecated). Current npm publish: **v2.7.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.7.0**. Use [`docs/ADOPTION.md`](docs/ADOPTION.md) for the ordered runbook.
82
-
83
- | Release | Highlights |
84
- |---------|------------|
85
- | **v2.7.0** | Quality & governance consolidation — audit-severity net_loc verify bugfix, discriminated `VerifyPhaseFailure` union, typed trace failure kinds, verify pipeline collapse (−3 modules), shared command error boundary, `GantryUserError` naming, MSN-0098 governance backfill, test-gap closure (435 tests) |
86
- | **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)) |
87
- | **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)) |
88
- | **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)) |
89
- | **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)) |
90
- | **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 |
91
- | **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)) |
92
- | **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)) |
93
- | **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)) |
94
- | **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)) |
95
- | **v2.2.1** | Thermo remediation — unified `NormalizedVerifyFailure` contract across JSON/human/context-feed; race-safe remediation snapshot writes; canonical `verify-presentation` entrypoint |
96
- | **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)) |
97
- | **v2.1.0** | Import-layer Code Surgeon (`check-import-layers.mjs --json`, AST quarantine, `GXT_IMPORT_LAYER_VIOLATION`); workspace-resolved optional TypeScript for surgeons |
98
- | **v2.0.0** | `gantry scan` + KPI gate, `register`, `check-imports`, `perimeter`; BYO `llm_verifiers`; KPI stale binding on `--pre-push`/`--ci` |
99
- | **v1.1.2** | Verify pipeline close-out (MSN-0034–0035); typed verify phases, trace status at parse boundary |
100
- | **v1.1.1** | Lib/command boundary, unified `runVerifyCore`, typed remediation, CommandReporter, mission YAML emitter |
101
- | **v1.1.0** | Stale trace evidence, mission purity PR lock, CI target lock, `verify --json`, doctor substrate drift warn |
102
- | **v1.0.0** | `gantry init --tutorial`, global `--audience` / `GXT_AUDIENCE`, adoption-first README + runbook |
103
- | **v0.9.0** | `gantry start`, `verify --fix`, `status --json`, `onboarding`, GXT error codes |
104
-
105
- ## What you get
106
-
107
- | Idea | Where it lives |
108
- |------|----------------|
109
- | **Law** (SOD, trace mapping, risk tiers, TMVC, manifest sync) | [`.gitagent/planner/RULES.md`](.gitagent/planner/RULES.md) |
110
- | **Routing map** (skills, roots, forbidden zones, path risks) | [`.gitagent/foreman/MANIFEST.json`](.gitagent/foreman/MANIFEST.json) |
111
- | **Foreman** (cheap, manifest-only triage) | [`.gitagent/foreman/SOUL.md`](.gitagent/foreman/SOUL.md) |
112
- | **Executor Runtime Contract** (env exports for IDE agents / scripts) | [`.gitagent/planner/RUNTIME.md`](.gitagent/planner/RUNTIME.md) |
113
- | **Bootstrap** (zero-friction substrate install) | `gantry init` + packaged [`templates/`](templates/) |
114
- | **Architecture pointer** (where agents find code layout) | [`.gitagent/ARCHITECTURE.pointer.json`](.gitagent/ARCHITECTURE.pointer.json), [ARCHITECTURE-DISCOVERY.md](.gitagent/planner/ARCHITECTURE-DISCOVERY.md) |
115
- | **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) |
116
- | **gantry CLI** | `npm install -g @jeger-ai/opengantry` or `npx @jeger-ai/opengantry` — see [gantry](#gantry-cli) |
117
- | **Full orientation + workflow diagram** | [`.gitagent/README.md`](.gitagent/README.md) |
118
-
119
- Core behaviors in plain language:
120
-
121
- - **Git-native missions:** commit subjects use **`[MSN-XXXX]`** so history is greppable (`git log --grep='MSN-0042'`).
122
- - **Auditable execution log:** verifier PASS requires quotes from **`EXECUTOR_LOG.md`** (process control paired with SOD and deterministic gates).
123
- - **Risk tiers:** cheap automation where safe; stricter human paths for sensitive areas.
124
- - **Approved edit paths:** work under declared **tmvc_roots**; **forbidden zones** are hard stops; out-of-scope access needs a logged **context request**.
125
- - **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)).
126
-
127
- ## Start here (5 minutes)
42
+ Everything revolves around a **mission**:
128
43
 
129
- ```bash
130
- gantry init --tutorial # or: gantry init && gantry onboarding
131
- gantry planner set "$(git config user.email)"
132
- gantry start "Your first change" --msn MSN-0001 --skill-key <manifest-key>
133
- # Planner: review mission scope/gates, then commit [MSN-0001] including the mission file
134
- git log --grep='MSN-' --oneline
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]
135
51
  ```
136
52
 
137
- ### Human handbrake
53
+ **Roles:**
138
54
 
139
- If you do **not** review the **mission** under `.gitagent/missions/` **before** the executor runs, the trace records **what you allowed to happen**—not a substitute for intent checks. You still sign off on scope, TMVC roots, and the deterministic gate.
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
140
58
 
141
- ## Using this outside the OpenGantry repo
59
+ **Key artifacts in your repo:**
142
60
 
143
- Treat the following as a **portable kit** you can drop into any Git repository (app, library, or monorepo).
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) |
144
68
 
145
- ### Enforcement boundary
69
+ ---
146
70
 
147
- **Prevents unreviewed edits where it matters.** IDE Agent Write/Edit is advisory TMVC; hard boundaries live in `runtime exec`, `gantry verify`, and hooks.
71
+ ## v3.0.0: Three phases, any domain
148
72
 
149
- | Tier | Mechanism | Enterprise control |
150
- |------|-----------|-------------------|
151
- | **Process-boundary** | `gantry runtime exec` | Agent cannot touch forbidden paths during orchestrated runs |
152
- | **Deterministic hook** | Cursor `beforeShellExecution`, pre-push verify | Shell/hook writes to governance files require mission + verify |
153
- | **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:
154
74
 
155
- Per-tool recipes: [`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md) (see **Enforcement boundary**).
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 |
156
80
 
157
- ### 1. Bootstrap with `gantry init` (recommended)
81
+ ### Built-in domain adapters
158
82
 
159
- From a built OpenGantry tree (or after copying the `gantry` CLI + `templates/` into your toolchain):
83
+ | Domain | Corpus | Enforcement |
84
+ |--------|--------|-------------|
85
+ | `code` | `.ts`, `.js`, … | Import layers, forbidden specifiers |
86
+ | `content` | `.md`, `.html`, `.txt`, … | `forbid_pattern`, `require_pattern` regex |
160
87
 
161
- ```bash
162
- npm ci && npm run build # in the OpenGantry repo, or use a globally linked gantry
163
- gantry init --tutorial # recommended first run; or gantry init (wizard / --yes)
164
- gantry planner set "$(git config user.email)" # repo-local (recommended)
165
- gantry doctor
166
- git config core.hooksPath .githooks
167
- ```
88
+ List them: `gantry domains`
168
89
 
169
- `gantry init` bootstraps a target git repository from packaged templates:
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.
170
91
 
171
- - **TTY:** interactive wizard (`@clack/prompts`) select IDE/agent integrations, doc path, skills preset, hooks, CI, architecture pointer.
172
- - **Non-TTY / CI:** auto-applies default profile (core + Cursor + hooks + CI) — no hang.
173
- - **`--yes`:** default profile without prompts. **`--dry-run`:** print planned writes.
174
- - **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.
175
93
 
176
- Asset lifecycles:
94
+ ---
177
95
 
178
- - `scaffold_only` files (for example `MANIFEST.json`, `RULES.md`, `skills/*.md`, IDE pointer files) are created when missing and preserved when customized.
179
- - `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
180
97
 
181
- Init also composes **`docs/INTEGRATIONS.md`** (or your chosen path) from `templates/integrations/compatibility.json`, scaffolds **`.gitagent/ARCHITECTURE.pointer.json`**, and installs runtime scripts (`gxt-runtime-env.sh`, `gxt-pin-mission.sh`, …). Store local tokens for protected architecture sources with **`gantry arch cred set`** (stdin only; git-ignored under `.gitagent/history/credentials/`).
182
-
183
- After `init`, customize your manifest and skills, then legislate. See [`docs/ADOPTION.md`](docs/ADOPTION.md) for the exact ordered runbook.
184
-
185
- ### 2. Customize for your project
186
-
187
- - Edit **[`.gitagent/foreman/MANIFEST.json`](.gitagent/foreman/MANIFEST.json)**
188
- Set `path_risks`, `risk_keywords`, and each skill's `tmvc_roots`, `forbidden_zones`, and `trust_threshold` to match **your** directories and risk appetite.
189
- - Align **[`.gitagent/planner/RULES.md`](.gitagent/planner/RULES.md)** with your review policy (tiers, who counts as "human audit", merge gates).
190
- - Point **deterministic gates** in missions at **your** stack (`npm test`, `pytest`, `cargo test`, etc.).
191
- - 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`).
192
-
193
- **Concrete gate example** (YAML fields in a mission file; adjust paths and commands):
194
-
195
- ```yaml
196
- gate_command: "npm test -- src/components/Button.test.tsx"
197
- gate_success_substring: "Tests: 1 passed"
198
- ```
199
-
200
- 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.
201
-
202
- ### gantry CLI
203
-
204
- The **Gantry CLI** (`gantry`) is the primary interface for **Open Source Gantry** — local, vendor-neutral, git-native governance in your repository.
205
-
206
- 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 (**deprecated** — will be removed in a future major release). Config namespaces: `GANTRY_*` env vars and `git config gantry.*` (legacy `GAPMAN_*` / `gapman.*` values are still read silently, also deprecated). From source: `npm ci && npm run build` → `dist/cli/index.js`.
207
-
208
- **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).
209
-
210
- **Adoption path:**
211
-
212
- | Step | Command | Outcome |
213
- |------|---------|---------|
214
- | Onboard | `gantry init --tutorial` or `gantry onboarding` | Feel Planner stamp + verify loop (~3 min) |
215
- | Scope + approve | `gantry start` → Planner `[MSN-…]` commit | Unreviewed stub cannot pass full verify |
216
- | Prove work | `gantry verify` | Gate + log quotes + greppable history |
217
-
218
- **Global output:** `gantry --audience executor\|planner\|verifier\|platform <cmd>` (or `GXT_AUDIENCE=verifier` in CI — silence unless `[GXT_*]` errors).
219
-
220
- | Command | Purpose |
221
- |--------|---------|
222
- | `gantry init` | Bootstrap substrate + IDE packs + hooks + CI. `--tutorial` runs guided first loop after scaffold. |
223
- | `gantry upgrade` | Plan substrate updates (`gantry upgrade plan` / `--dry-run` for preview JSON). Stage with `gantry upgrade`; `gantry upgrade apply --mission …` after Planner commit. |
224
- | `gantry check` | Validate `MANIFEST.json` shape + **Rule 4.4** sync: every `manifest.skills` key must have `skills/<key>.md`, with no orphan skill files. |
225
- | `gantry status` | GXT readiness dashboard (`--json`, `--verbose`, `--audience executor\|planner\|verifier\|platform`). |
226
- | `gantry start "<intent>"` | Goal-first orchestration: triage → legislate stub → runtime next steps (`--msn`, `--skill-key`, `--json`). |
227
- | `gantry onboarding` | Interactive walkthrough of the strict mission loop. Blocks on corrupt configured integration state; allows pristine uninitialized repos. |
228
- | `gantry doctor` | Active readiness check (manifest, Planner email, bypass secret match, hooks, architecture pointer, integration staleness). Warnings exit 0. `--audience` tailors next steps. |
229
- | `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. |
230
- | `gantry planner show\|set` | Repo-local Planner git-proof allowlist (`.gitagent/foreman/PLANNER.allowlist.local`; avoids global `GANTRY_PLANNER_EMAILS` leaking across projects). |
231
- | `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. |
232
- | `gantry mission validate --file <path>` | Validate a mission `.md` or `.yaml` (YAML checked against [`.gitagent/planner/MISSION.schema.yaml`](.gitagent/planner/MISSION.schema.yaml)). |
233
- | `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`). |
234
- | `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). |
235
- | `gantry runtime exec --mission <path> -- <cmd…>` | Run executor command with mission env, telemetry capture, and forbidden-zone scan (strongest TMVC trap). |
236
- | `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. |
237
- | `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. |
238
- | `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`. |
239
- | `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. |
240
- | `gantry scan --mission <path>` | Run mission `llm_verifiers` (BYO commands) and write namespaced KPI report JSON for `kpi_gate`. |
241
- | `gantry register <dir>` | AST discovery: propose skill scope from folder imports/exports (does not mutate `MANIFEST.json`). |
242
- | `gantry check-imports <dir> --ban <spec…>` | Deterministic banned-import scan (usable as `gate_command`; no LLM). |
243
- | `gantry perimeter [--base-ref <ref>] [--ci]` | Protected governance paths: local advisory; **`--ci`** requires verified commit signatures. |
244
- | `gantry arch pointer` | Print architecture pointer summary for agents (`.gitagent/ARCHITECTURE.pointer.json`). |
245
- | `gantry arch fetch` | Fetch `kind=external` architecture docs into a local cache (doctor stays offline). |
246
- | `gantry arch check` | Evaluate `TARGET_ARCHITECTURE.yaml` import/layer rules for TypeScript paths under configured roots. |
247
- | `gantry arch cred status\|set\|unset` | Git-ignored credential slots for authenticated external architecture sources (secrets via stdin only). |
248
- | `gantry metrics [--json] [--ref main]` | Git-native governance rollup (`--json` includes `gxt_extension_metadata`). See [`docs/ADOPTION.md`](docs/ADOPTION.md). |
249
- | `gantry context-feed [--json] [--clear]` | Read or atomically clear the latest verify remediation snapshot (`.gitagent/tmp/NEXT_REMEDIATION.json`) for IDE repair loops. |
250
- | `gantry audit-rigor [--json] [--strict]` | Meta-governance audit: TypeScript strictness, coverage artifacts, MANIFEST wildcard hygiene. |
251
-
252
- **Who can approve missions (Planner allowlist):** only allowlisted identities can legislate missions that verify accepts. Precedence:
253
-
254
- 1. `.gitagent/foreman/PLANNER.allowlist` (+ optional gitignored `.local` merge)
255
- 2. `git config gantry.plannerEmails "a@x.com,b@y.com"`
256
- 3. `GANTRY_PLANNER_EMAILS` env (CI escape hatch only)
257
- 4. implicit `git config user.email` when nothing else is set
258
-
259
- Use **`gantry planner set "$(git config user.email)"`** after clone — do not rely on a global shell export when you work across multiple projects.
260
-
261
- ### Executor Runtime quickstart
262
-
263
- Agents (Cursor, Junie, local scripts) should not guess TMVC roots — read them from **`gantry runtime env`**.
264
-
265
- 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
266
99
 
267
100
  ```bash
268
- npm ci && npm run build
269
-
270
- # Existing mission (tracked example — swap for yours after Planner legislates it):
271
- eval "$(node dist/cli/index.js runtime env --mission .gitagent/missions/example.verify.yaml)"
272
-
273
- # Or machine-readable JSON for a wrapper script:
274
- node dist/cli/index.js runtime env --mission .gitagent/missions/example.verify.yaml --json
275
-
276
- # Headless / CI — strongest TMVC trap:
277
- 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
278
103
  ```
279
104
 
280
- Inspect `GXT_TMVC_ROOTS`, `GXT_FORBIDDEN_ZONES`, and `GXT_EXECUTOR_LOG`; write forensic trace quotes to **`EXECUTOR_LOG.md`** (or `--executor-log` at verify time), then **`gantry verify`** as usual.
105
+ Scaffolds `.gitagent/`, hooks, manifest, and walks you through the first mission loop.
281
106
 
282
- **Legislate a stub mission (Planner edits + commits — then wire `runtime env` to that file path):**
107
+ ### 2. Fast-path discovery
283
108
 
284
109
  ```bash
285
- node dist/cli/index.js legislate "Fix login spinner on checkout — ui" --msn MSN-0007 --skill-key ui
286
- # Planner: tune gate/trace rows; git commit -m "[MSN-0007] legislate …" including the mission file
287
- # 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
288
112
  ```
289
113
 
290
- Details and variable semantics: [.gitagent/planner/RUNTIME.md](.gitagent/planner/RUNTIME.md).
114
+ Emits a proposal with evidence-anchored conventions and anomalies (`file:line` snippets). Nothing becomes law until a human confirms or runs blueprint.
291
115
 
292
- ### 3. Wire agents (and optionally CI)
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.
293
117
 
294
- - **[`docs/INTEGRATIONS.md`](docs/INTEGRATIONS.md)** closed-loop agent integrations (enforcement boundary, remote handoff, per-tool recipes for Cursor, Claude Code, OpenAI Codex CLI, OpenCode, Junie, Antigravity, Cline, Aider, OpenHands). Installed by `gantry init`.
295
- - **[`AGENTS.md`](AGENTS.md)** tells agents to read **RULES** + **MANIFEST** before acting.
296
- - **[`.cursor/rules/opengantry-gxt-substrate.mdc`](.cursor/rules/opengantry-gxt-substrate.mdc)** does the same for Cursor with `alwaysApply: true`.
297
- - **CI:** this repo includes **[`.github/workflows/gxt-validate.yml`](.github/workflows/gxt-validate.yml)**:
298
- - **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.
299
- - **gantry:** `npm ci` / `npm run build`, then `gantry check`, `gantry doctor`, and unit tests.
300
- - **Manifest (jq parity):** validates [`.gitagent/foreman/MANIFEST.json`](.gitagent/foreman/MANIFEST.json) via [`scripts/validate-gxt.sh`](scripts/validate-gxt.sh) `manifest`.
301
- - **Changed-code quality (PR only):** ESLint complexity, import layers, line budgets on touched `src/cli/**/*.ts`.
302
- - **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.
303
- - **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.
304
- - **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
305
119
 
306
120
  ```bash
307
- npm ci && npm run build
308
- node dist/cli/index.js check
309
- node dist/cli/index.js doctor
310
- ./scripts/validate-gxt.sh manifest
311
- ./scripts/validate-gxt.sh msn origin/main HEAD # after: git fetch origin
312
- # or full local stack:
313
- npm run validate
121
+ gantry blueprint --domain content --yes
314
122
  ```
315
123
 
316
- ### 4. Run the loop (human + models)
317
-
318
- 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:
319
125
 
320
- Details and the workflow diagram: **[`.gitagent/README.md`](.gitagent/README.md)**.
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
321
129
 
322
- ### Advanced: manual vendoring
130
+ The executor agent reads `required_skills` and builds missing tooling *before* coding.
323
131
 
324
- If you cannot run `gantry init`, copy at least:
132
+ ### 4. Perimeter enforcement
325
133
 
326
- - `.gitagent/` (entire tree)
327
- - `skills/` (optional in minimal vendoring, but **required** for Rule 4.4: one `skills/<skill-key>.md` per manifest skill — enforced by `gantry check`)
328
- - `.githooks/` (optional: creates an empty repo-root `EXECUTOR_LOG.md` when you check out a feature branch)
329
- - `AGENTS.md` (or merge its bullets into your existing agent instructions)
330
- - 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
+ ```
331
138
 
332
- Add to your **`.gitignore`** (if not already present):
139
+ For content, rules look like:
333
140
 
334
- ```gitignore
335
- # OpenGantry local forensic bulk (optional)
336
- .gitagent/history/
141
+ ```yaml
142
+ forbid_pattern: "(?i)cures cancer"
143
+ require_pattern: "These statements have not been evaluated by the FDA"
337
144
  ```
338
145
 
339
- **Empty `EXECUTOR_LOG.md` on branch checkout:** after copying, point Git at the vendored hooks once per clone (`git config core.hooksPath .githooks`). On branch checkouts **other than** `main` or `master`, if `EXECUTOR_LOG.md` is missing at the repo root, [`.githooks/post-checkout`](.githooks/post-checkout) copies [`.gitagent/planner/EXECUTOR_LOG.template.md`](.gitagent/planner/EXECUTOR_LOG.template.md) into place. It **never overwrites** an existing file. Keep formatters off `EXECUTOR_LOG.md` — see [docs/ADOPTION.md](docs/ADOPTION.md) (formatter guard under stale trace evidence).
146
+ Violations carry `file` and `line` for the failure envelope.
340
147
 
341
- ## Staying in sync
342
-
343
- **Primary path (npm):** install or update the CLI package, then apply bundled substrate changes in your repo:
148
+ ### 5. Mission + verify
344
149
 
345
150
  ```bash
346
- npm install @jeger-ai/opengantry@latest
347
- gantry upgrade
348
- # Review .gitagent/.upgrade-tmp/; Planner-commit the upgrade mission YAML
349
- gantry upgrade apply --mission .gitagent/missions/MSN-9001.upgrade-vX.Y.Z.yaml
350
- gantry doctor
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
351
156
  ```
352
157
 
353
- See [`docs/ADOPTION.md`](docs/ADOPTION.md) and [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md#substrate-upgrade-loop-adopters--dogfood).
354
-
355
- **Alternative — vendor `.gitagent/` without npm** (no Node required in the host repo):
158
+ On failure, external agents ingest `findings[]`:
356
159
 
357
- **Option A — `git subtree` (good if you vendored `.gitagent/` with subtree in the first place)**
358
-
359
- ```bash
360
- git remote add opengantry-upstream https://github.com/jeger-ai/opengantry.git # once
361
- git fetch opengantry-upstream
362
- git subtree pull --prefix=.gitagent opengantry-upstream main --squash
160
+ ```json
161
+ {
162
+ "failed_gate": "arch",
163
+ "offending_file": "content/ad-bad.md",
164
+ "line": 3,
165
+ "severity": "error",
166
+ "resolution_hint": "..."
167
+ }
363
168
  ```
364
169
 
365
- Resolve conflicts carefully: **keep your** `MANIFEST.json` edits; **merge in** upstream changes to shared files like `RULES.md` or templates.
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`.
366
171
 
367
- **Option B side-by-side clone + copy**
172
+ ### 6. Content governance example
368
173
 
369
- ```bash
370
- git clone https://github.com/jeger-ai/opengantry.git /tmp/opengantry && \
371
- diff -ru .gitagent /tmp/opengantry/.gitagent | less
372
- # Then selectively copy files you want (e.g. RULES.md) without overwriting your manifest.
373
- ```
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.
374
175
 
375
- **Option C `curl` / raw URLs (surgical, fragile)**
176
+ ### 7. IDE integration
376
177
 
377
- Fetch a single file from `main` when you only want the latest template text:
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)
378
181
 
379
- ```bash
380
- curl -fsSL -o .gitagent/planner/MISSION.example.yaml \
381
- https://raw.githubusercontent.com/jeger-ai/opengantry/main/.gitagent/planner/MISSION.example.yaml
382
- ```
383
-
384
- Always **review the diff** before commit; never bulk-overwrite a customized `MANIFEST.json`.
182
+ ---
385
183
 
386
- ## OpenGantry Ledger — how GXT fits the landscape
184
+ ## What OpenGantry is *not*
387
185
 
388
- | Pattern | Typical shape | Audit / production readiness |
389
- |---------|----------------|------------------------------|
390
- | **GXT / OpenGantry** | Git-native missions, manifest routing, deterministic gates, auditable log mapped to **`EXECUTOR_LOG.md`**, human `[MSN-XXXX]` approval + SOD ([`RULES.md`](.gitagent/planner/RULES.md)) | **Autonomous Repository Engineering** scoped missions, not always-on chat. Greppable missions + gate output + log quotes. **Local-first**, **vendor-neutral** governance engine in your repo. |
391
- | 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 |
392
- | 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 |
393
- | 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
394
189
 
395
- GXT deliberately trades "always-on improvisation" for a **narrow, inspectable envelope**: Foreman chooses a skill footprint, Teachers legislate commits, Executors stay inside TMVC (or Context Request → accept/reject), and Verifiers bind PASS claims to log quotes.
190
+ ---
396
191
 
397
- ## Relationship to this repository
192
+ ## Mental model for adopters
398
193
 
399
- **jeger-ai/opengantry** is the **canonical reference tree** for **GXT** (manifest `schema_version` **v0.5.0** law + **`gantry` v2.7.0** CLI). Install the CLI with `npm install -g @jeger-ai/opengantry`, or fork this repo and run `gantry init` in your project.
194
+ ```
195
+ OpenGantry = contract negotiator + court + audit log
196
+ Executor agent = worker (Cursor, Hermes, human dev)
197
+ ```
400
198
 
401
- ## Security
199
+ You adopt OpenGantry when agent velocity is valuable but **unreviewed scope creep, silent governance edits, or unverifiable "it works" claims** are unacceptable.
402
200
 
403
- Supported versions and how to report vulnerabilities: [`SECURITY.md`](SECURITY.md).
201
+ ---
404
202
 
405
- ## License
203
+ ## Where to go next
406
204
 
407
- OpenGantry is licensed under the **Apache License, Version 2.0**. See [`LICENSE`](LICENSE). Attribution and copyright notice: [`NOTICE`](NOTICE).
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":"AAiBA,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;CAClB;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,CAuBxE"}
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"}