Packs, bitácora de auditoría y política

Instala los gates/reglas/skills de un equipo como pack, exporta una bitácora de auditoría sin contenido, y lee la política efectiva de guard/review/budget/notify.

Objetivo#

Tres superficies pequeñas y relacionadas:

  • orch pack install|list|update|remove — trae los gates/reglas/skills de otro taller al tuyo, con procedencia y sin pisar lo que ya editaste.
  • orch audit export — una bitácora en JSONL/tabla, sin contenido, de qué selló, su veredicto de guard, y si lucía elegible para promote.
  • orch policy show|diff — lee las secciones efectivas guard/review/budget/ notify de orch.yaml, y las compara contra un ref de git.

Packs#

Un pack es una carpeta (o la raíz de un repo git) con un MANIFEST.yaml:

name: starter-rules
version: 0.1.0
gates: [GATES.md]        # documentos, copiados a .orch/gates/user/
rules: [rules/a.json]    # cada uno un arreglo JSON de reglas (ver your-own-rules.md)
skills: [skills/x/SKILL.md]  # copiadas al directorio de skills de cada CLI, editables
docs: [README.md]        # documentos de referencia, en .orch/packs/<name>/docs/

orch pack install ruta\a\un\pack               # directorio local
orch pack install https://host/org/repo.git --ref main   # git clone --depth 1
orch pack list
orch pack update starter-rules
orch pack remove starter-rules

Cada archivo/regla que un pack escribe queda registrado con un checksum en .orch/packs/<name>.json. update/remove solo tocan un archivo cuyo checksum siga igual al que se escribió la última vez — lo que editaste a mano se deja intacto y se reporta como "kept (edited)". Una regla se mezcla en .orch/gates/user/manifest.json etiquetada source: <pack>@<version>, y el SKILL.md de una skill lleva un comentario marcador diciendo que viene de un pack y que Orchemax no lo va a sobrescribir.

El repo público orchemax-orch trae packs/starter-rules/ (tres reglas de ejemplo — una deny, una require, una cmd) y catalog/GATES.md (todos los verbos por defecto de orch guard: qué revisan, dónde corren, y si son expresables como una regla propia).

Exportar la auditoría#

orch audit export --since 24h
orch audit export --since 2026-09-01 --json

Una línea por sesión sellada desde el corte (una duración como 24h/7d, o una fecha/timestamp RFC3339): agente, estado, veredicto de guard + notas, cantidad de archivos cambiados, una lectura de elegibilidad para promote y uso de tokens. --json cambia de la tabla a JSON Lines. Nunca el contenido de un archivo ni un diff — el mismo contrato sin contenido que orch usage --export jsonl.

"Promote decision" es una lectura de si el veredicto de guard de la sesión pasaría hoy el bloqueo de worktree_promote (eligible / blocked / not_run / n/a) — no es un registro de un promote/reject real, que Orchemax todavía no persiste.

Policy show/diff#

orch policy show
orch policy diff origin/main

show imprime las secciones guard:, review:, budget: y notify: que orch.yaml tenga en este momento — nada más, y nada asumido. diff <git-ref> extrae las mismas cuatro secciones de la copia de orch.yaml en ese ref (vía git show <ref>:orch.yaml) y muestra qué cambió, usando git diff --no-index por debajo.

Relacionado#

  • your-own-rules.md — el manifiesto donde se mezclan las entradas rules: de un pack.
  • hooks-and-guards.md — los guards que los documentos gates: de un pack recomiendan.