Your own rules

Declare the checks your workshop cares about in one manifest, and Orchemax runs them wherever it runs its own.

Goal#

Write the rules that are yours — not the ones Orchemax ships — in .orch/gates/user/manifest.json, and have them judged at the same cut points as the built-in guards, in the same verdict.

Before this existed, .orch/gates/user/ was a folder Orchemax never read. A rule you wrote lived there as a note and was enforced by nobody.

The manifest#

orch init seeds an empty one:

{ "version": 1, "gates": [] }

Each gate is one rule:

{
  "version": 1,
  "gates": [
    {
      "id": "no-todo",
      "on": ["seal", "pre-commit"],
      "files": ["**/*.go"],
      "deny": "TODO",
      "severity": "block",
      "message": "ship it or file it"
    },
    {
      "id": "vet",
      "on": ["seal"],
      "files": ["**/*.go"],
      "cmd": ["go", "vet", "./..."],
      "timeout_s": 60,
      "severity": "warn",
      "message": "go vet complained"
    }
  ]
}
Field Meaning
id Unique. Reported as user:<id> so a workshop rule is never mistaken for one of Orchemax's
on Where it runs: seal, pre-commit, pre-push, ide-pre, ide-post
files Globs; **/*.go and **/dir/** work. Omit for every file in the change set
deny Go regex — any match in a matching file fails the gate
require Go regex — a matching file with no match fails the gate
cmd argv, with the matching files appended. Exactly one of deny, require, cmd
timeout_s cmd only. Default 10, maximum 120
severity block (default) fails the verdict; warn leaves a note and passes
message What the note says when the gate fails

Where each gate runs#

on Cut point What a block does
seal Every dispatched worker's verification, whatever its CLI verify_report.guardrails: fail, with the note in guardrail_notes
pre-commit, pre-push orch guard hooks run, called by the git hooks The commit or push stops
ide-pre orch guard ide-hook, on Write/Edit/MultiEdit The write is denied and the agent gets the message
ide-post Accepted and validated, not executed yet Nothing

At ide-pre the gate reads the body about to be written, not the file on disk. At the seal and at the git hook it reads the files as they are in the tree.

What a cmd gate can and cannot see#

A cmd gate is a third party running inside a worker's process tree, so it is kept on a short leash:

  • Explicit argv, never a shell. No SHELL, no sh -c. A Windows worker that inherited SHELL from Git Bash once evaluated every PowerShell wrapper with bash eval and silently killed all of its hooks; that path does not exist here.
  • cwd is the project root, and the matching files are appended to the argv.
  • The environment is a whitelist: PATH, HOME, USERPROFILE, TEMP, TMP, SystemRoot, ComSpec, PATHEXT, plus your own ORCH_* variables. Anything whose name contains KEY, TOKEN, SECRET or PASSWORD is dropped, so a gate never sees the worker's provider credentials.
  • Exit 0 passes. Any other exit fails, and the first 400 bytes of its output become the note.
  • A timeout is a warning, not a verdict. A gate that never answered leaves warn — timed out and the work goes through.
  • At most 50 files per gate — the same ceiling the duplicate gate uses. Past it the report says how many were skipped rather than pretending it looked.

Check and dry-run#

orch guard rules                          # list the gates, validate the manifest
orch guard rules run --files a.go,b.go    # run them over an explicit list
orch guard rules run --files a.go --on ide-pre

orch guard rules exits 1 on an invalid manifest and names the line and the gate id. A manifest Orchemax cannot read never blocks work: it reports itself as a note and the defaults carry on.

Verify#

orch guard rules
orch guard rules run --files <a file you know breaks a rule>

Install rules from a pack instead of writing them by hand#

orch pack install <path|git-url> merges someone else's already-proven gates into this same manifest, tagged source: <pack>@<version> so you can tell them apart from the ones you wrote yourself:

orch pack install https://github.com/<org>/<pack-repo>.git --ref main
orch pack list
orch pack update starter-rules     # refresh files you never hand-edited
orch pack remove starter-rules     # drop them; anything you edited is kept

A rule you edit after installing is never silently overwritten or deleted — update and remove report it as "kept (edited)" instead of touching it. A pack can also carry gate docs (installed under .orch/gates/user/<pack>-<name>.md) and skills (installed as editable files under every vendor's skill dir, marked so Orchemax never overwrites them).

  • hooks-and-guards.md — the guards Orchemax ships and where they are wired.
  • packs-audit-and-policy.md — installing a pack, exporting the audit trail, and reading the effective policy.
  • ../shared-code-law.md — the rules that are not yours to change.