Contener · Guiar · Ordenar
Contain the write. Guide the next step. Order leftover mess.
The rules file holds the write. Status shows the next step. Required CI owns the merge.
The product
Contain. Guide. Order.
Agents take the shortest path. A linter that only runs after the agent finished is too late.
The write doesn’t land
The same check fails the pull request.
One next step
Status shows what to do first. A non-expert is not stuck.
Name leftover mess
Then one small refactor at a time. Extras stay off until you ask.
Four beats
The path that holds.
Write the rules file
ark.config.json is the rules file: layers,
import rules, placement, purity, isolation, and scope.
Optional ArkRules, ArkRun,
and ArkOrder extras are off unless you turn
them on.
Reject the write
On hosts that support it, the hook rejects listed edits that break the rules. Elsewhere you get a warning, not a block. The agent must listen. CI still has to be required.
Validate the proposal
Related creates, edits, and deletes can be checked as one atomic change—so a valid multi-file move is not rejected one file at a time.
Require CI status
arkgate-check --strict-merge as a
required status is the hard merge line for
every host. Local speed is optional. Merge correctness is not.
Layers and extras
Layers always. Extras only when you opt in.
Never confuse a broken import rule with an extra miss. Label leftover
work [Layer], [ArkRules],
[ArkRun], or [ArkOrder].
| Kind | 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 |
| ArkRun (opt-in) | How the app talks | arkRun · import arkgate/runtime |
Kernel usage and complete declarations. The loopback inspector and terminal dashboard expose bounded, payload-free facts. In-memory. Not durable. |
| ArkOrder (opt-in) | The few slow product decisions the agent must not CRUD | arkOrder · import arkgate/order |
Plan stays frozen. Invoices and seats still flow. A
generic update of the plan does not land.
Proof:
billing gallery ↗
(GitHub, not in the npm tarball).
|
No extras is valid. Start always gives you layers. Compact
starters leave ArkRun and ArkOrder off. Templates may ship
advisory until you promote them.
rulesUnderContract is a catalog—never a score.
Reject the write
The earliest honest boundary each host offers.
The hook rejects the write versus a warning only (not blocked) is a deliberate trade—not marketing gloss. Full matrix on Hosts.
Hook rejects the write
Cursor, Grok, and Claude can deny listed writes when hooks are installed and trusted. Antigravity can too. The host must re-inject the repair payload.
Operation-scoped truth
Codex can block a complete local apply_patch when
that exact hook is trusted and observed. OpenCode remains
advisory. Cursor blocks Write/StrReplace when hooks are trusted.
No block claim extends beyond those paths.
Atomic multi-file
A new service may only be valid with its port and adapter. Preflight sees the whole proposal so partial states do not thrash the agent.
Fail-closed
Incomplete analysis, unobserved hooks, and soft MCP never read as hard green. Incomplete analysis cannot pass strict merge.
Doctor
One light. One next move.
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.
Import rules hold
Keep write path + required CI.
Still messy
Not done—map leftover work, then one small refactor.
Doctor stays unfinished when leftover design work remains, coverage is thin, or honesty sensors fire. A green import check is not finished design.
Ordenar
Name leftover work. Never invent a score.
After import rules check out, leftover mess is still leftover mess. Status names it. It never becomes a score.
Not a score
Leftover-work notes never flip the check. Green imports are not elegant design.
One next move
Status and the HTML report share one next action — so the agent stops shopping skills.
Honest out-of-scope
Missing APM or a security scanner does not invent leftover work. Those tools stay out of scope.
One small refactor
Map the mess. Change one thing. Run status again. That is Ordenar.
Run npx arkgate-check --doctor. Green imports plus
empty leftover notes still do not mean elegant design.
CI
Required CI owns the hard line.
Any local boundary can be walked around—another tool, a direct
filesystem write, a human edit. The only guarantee ArkGate claims for
every path is required
arkgate-check --strict-merge—and only when the repository
makes that status required.
Local checks buy speed. Required CI owns correctness. Recurring violations on one edge are pressure to reshape—not a reason to weaken the check.
Leftover design work
Never silent plan B.
Green imports prove checked rules hold. They do not prove elegant design.
Confirm
Doctor names leftover design work. That is not a score.
Map, if you want
Optional skill pack: /ark-explore then
/ark-autopilot with your OK.
One small refactor
Change one thing. Re-run doctor. Never auto-applied.