Contract → gate → CI
Define once. Guide writes. Protect main.
ArkGate turns architecture into an executable repository contract. Supported agents hit a write gate; every host meets a required merge check. Doctor tells you what is real.
Four beats
The enforcement path.
Define the contract
ark.config.json declares layers, import rules,
placement, purity, isolation, and scope. Optional ArkRules
add intra-layer sensors and invariant catalogs as data.
Guide writes
On hard hosts, PreToolUse blocks listed write ops that break the contract. Elsewhere, MCP and repository guidance are advisory—the agent must use them.
Validate the proposal
Related creates, edits, and deletes can be checked as one atomic change—so a valid multi-file move is not rejected file by file.
Require CI status
arkgate-check --strict-merge as a
required status is the hard merge boundary
for every host. Local speed is optional; merge correctness is
not.
Dual plane
Layers always. ArkRules only if you opt in.
Never blur an import-edge violation with an invariant. Label residual
[Layer] vs [ArkRules].
| Plane | Meaning | Config | Enforces |
|---|---|---|---|
| Layers | Who may talk to whom | layers[] + rules[] |
Import direction, placement, purity, forbidden globals, capabilities, peer isolation |
| ArkRules (opt-in) | Habits inside a layer + named policies |
arkRules + arkrules/<Layer>.json
|
Structure heuristics; invariant catalog + coverage evidence—not full business proof |
Absence of ArkRules is valid. Start always gives you layers. ArkRules
templates may ship advisory until you promote them.
rulesUnderContract is a catalog, never a score.
Write gate
Earliest honest boundary each host offers.
Hard write vs advisory write is a deliberate trade-off—not marketing gloss. See the full matrix on Hosts.
Hard write
Claude Code, Grok Build, Google Antigravity: installed + trusted PreToolUse can deny listed write operations and emit a repair payload the host must re-inject.
Advisory write
Cursor, Codex, OpenCode: MCP and rules coach the agent. There is no fake hard claim at write time.
Atomic multi-file
A new service may only be valid with its port and adapter. Preflight evaluates the whole proposal so partial states do not thrash the agent.
Fail-closed
Incomplete analysis, unobserved hooks, and soft MCP never paint as hard green. Incomplete analysis cannot satisfy strict merge.
Doctor
Control plane: light + primary next action.
Status lights are evidence, not settings. You do not “turn on” Enforce.
Thin / new
Finish start → re-run doctor.
Gaps remain
Doctor action #1 until protected.
Edges honest
Keep write path + required CI.
Shape residual
Not done—open the shape door.
productHonesty stays unfinished when design-weak, weak coverage, residual debt, dual-truth pin, or related sensors fire. Honesty clear is not a vanity green graph.
CI
Merge gate owns the hard guarantee.
Any local boundary can be routed around—another tool, a direct
filesystem write, a human edit. The only guarantee ArkGate claims for
every path is the required
arkgate-check --strict-merge check, and only when the
repository makes that status required.
Local checks optimize feedback speed. The merge gate owns correctness. Recurring violations on one edge are a pressure sensor for deliberate reshape—not a reason to weaken the gate.
Shape residual
Never silent plan B.
Green edges prove checked boundaries hold. They do not prove elegant design. When doctor reports design-weak:
- Confirm design-weak on doctor
-
Guided map / dual plan (skill pack:
/ark-explorethen/ark-autopilotwith your OK)—optional expert path - One pilot at a time · re-run doctor
Pattern bets are never mechanical-safe by default. Empty remediation plan is not “architecture finished” if design residual remains.