Tus propias reglas

Declara en un solo manifiesto las verificaciones que le importan a tu taller, y Orchemax las corre donde corre las suyas.

Objetivo#

Escribir las reglas que son tuyas — no las que trae Orchemax — en .orch/gates/user/manifest.json, y que se juzguen en los mismos puntos de corte que los guards incorporados, dentro del mismo veredicto.

Antes de esto, .orch/gates/user/ era una carpeta que Orchemax nunca leía. Una regla que escribieras vivía ahí como una nota y no la hacía cumplir nadie.

El manifiesto#

orch init siembra uno vacío:

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

Cada gate es una regla:

{
  "version": 1,
  "gates": [
    {
      "id": "no-todo",
      "on": ["seal", "pre-commit"],
      "files": ["**/*.go"],
      "deny": "TODO",
      "severity": "block",
      "message": "termínalo o abre el ticket"
    },
    {
      "id": "vet",
      "on": ["seal"],
      "files": ["**/*.go"],
      "cmd": ["go", "vet", "./..."],
      "timeout_s": 60,
      "severity": "warn",
      "message": "go vet se quejó"
    }
  ]
}

Campo	Qué significa
`id`	Único. Se reporta como `user:<id>`, así una regla del taller nunca se confunde con una de Orchemax
`on`	Dónde corre: `seal`, `pre-commit`, `pre-push`, `ide-pre`, `ide-post`
`files`	Globs; sirven `*/.go` y `/dir/`. Omítelo para todos los archivos del cambio
`deny`	Regex de Go — cualquier coincidencia en un archivo que aplique reprueba el gate
`require`	Regex de Go — un archivo que aplique sin coincidencia reprueba el gate
`cmd`	argv, con los archivos que aplican añadidos al final. Exactamente uno de `deny`, `require`, `cmd`
`timeout_s`	Solo para `cmd`. Por defecto 10, máximo 120
`severity`	`block` (por defecto) reprueba el veredicto; `warn` deja la nota y pasa
`message`	Lo que dice la nota cuando el gate falla

Dónde corre cada gate#

`on`	Punto de corte	Qué hace un `block`
`seal`	La verificación de cada worker despachado, sea cual sea su CLI	`verify_report.guardrails: fail`, con la nota en `guardrail_notes`
`pre-commit`, `pre-push`	`orch guard hooks run`, invocado por los hooks de git	El commit o el push se detiene
`ide-pre`	`orch guard ide-hook`, en `Write`/`Edit`/`MultiEdit`	La escritura se deniega y el agente recibe el mensaje
`ide-post`	Se acepta y se valida, todavía no se ejecuta	Nada

En ide-pre el gate lee el cuerpo que está por escribirse, no el archivo en disco. En el sellado y en el hook de git lee los archivos tal como están en el árbol.

Qué puede y qué no puede ver un gate `cmd`#

Un gate cmd es un tercero corriendo dentro del árbol de procesos de un worker, así que se le tiene corto:

argv explícito, nunca un shell. Sin SHELL, sin sh -c. Un worker en Windows que heredó SHELL de Git Bash llegó a evaluar cada wrapper de PowerShell con el eval de bash y mató en silencio todos sus hooks; ese camino no existe acá.
El cwd es la raíz del proyecto, y los archivos que aplican se añaden al argv.
El entorno es una lista blanca: PATH, HOME, USERPROFILE, TEMP, TMP, SystemRoot, ComSpec, PATHEXT, más tus propias variables ORCH_*. Se descarta todo lo que tenga KEY, TOKEN, SECRET o PASSWORD en el nombre, así un gate nunca ve las credenciales de proveedor del worker.
Salir con 0 aprueba. Cualquier otro código reprueba, y los primeros 400 bytes de su salida quedan como la nota.
Un timeout es un aviso, no un veredicto. Un gate que nunca respondió deja warn — timed out y el trabajo sigue.
Máximo 50 archivos por gate — el mismo tope que usa el gate de duplicados. Pasado eso el reporte dice cuántos quedaron fuera en vez de fingir que los miró.

Revisar y probar en seco#

orch guard rules                          # lista los gates, valida el manifiesto
orch guard rules run --files a.go,b.go    # los corre sobre una lista explícita
orch guard rules run --files a.go --on ide-pre

orch guard rules sale con 1 si el manifiesto es inválido y nombra la línea y el id del gate. Un manifiesto que Orchemax no puede leer nunca bloquea el trabajo: se reporta como nota y los guards por defecto siguen.

Verificar#

orch guard rules
orch guard rules run --files <un archivo que sepas que rompe una regla>

Instalar reglas desde un pack en vez de escribirlas a mano#

orch pack install <path|git-url> mezcla en este mismo manifiesto reglas ya probadas por otro taller, etiquetadas source: <pack>@<version> para distinguirlas de las que escribiste tú:

orch pack install https://github.com/<org>/<pack-repo>.git --ref main
orch pack list
orch pack update starter-rules     # refresca archivos que nunca editaste a mano
orch pack remove starter-rules     # los quita; lo que editaste se conserva

Una regla que edites después de instalarla nunca se sobrescribe ni se borra en silencio — update y remove la reportan como "kept (edited)" en vez de tocarla. Un pack también puede traer documentos de gate (instalados en .orch/gates/user/<pack>-<nombre>.md) y skills (instaladas como archivos editables bajo el directorio de skills de cada CLI, marcadas para que Orchemax nunca las sobrescriba).

Relacionado#

hooks-and-guards.md — los guards que trae Orchemax y dónde están cableados.
packs-audit-and-policy.md — instalar un pack, exportar la bitácora de auditoría y leer la política efectiva.
../shared-code-law.md — las reglas que no te toca cambiar.