Packs, audit trail and policy

Install a team's gates/rules/skills as a pack, export a content-free audit trail, and read the effective guard/review/budget/notify policy.

Goal#

Three small, related surfaces:

  • orch pack install|list|update|remove — pull another workshop's gates/rules/skills into yours, with provenance and no clobbering of your own edits.
  • orch audit export — a content-free JSONL/table paper trail of what sealed, its guard verdict, and whether it looked promote-eligible.
  • orch policy show|diff — read orch.yaml's effective guard/review/budget/ notify sections, and diff them against a git ref.

Packs#

A pack is a folder (or the root of a git repo) with a MANIFEST.yaml:

name: starter-rules
version: 0.1.0
gates: [GATES.md]        # doc files, copied into .orch/gates/user/
rules: [rules/a.json]    # each a JSON array of gate rules (see your-own-rules.md)
skills: [skills/x/SKILL.md]  # copied into every vendor's skill dir, editable
docs: [README.md]        # reference docs, kept under .orch/packs/<name>/docs/

orch pack install path\to\a\pack               # local directory
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

Every file/rule a pack writes is recorded with a checksum in .orch/packs/<name>.json. update/remove only ever touch a file whose checksum still matches what was last written — anything you edited by hand is left alone and reported as "kept (edited)". A rule merges into .orch/gates/user/manifest.json tagged source: <pack>@<version>, and a skill's SKILL.md gets a marker comment saying it came from a pack and Orchemax will not overwrite it.

The public orchemax-orch repo ships packs/starter-rules/ (three example rules — one deny, one require, one cmd) and catalog/GATES.md (every default orch guard verb: what it checks, where it runs, and whether it's expressible as a rule of your own).

Audit export#

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

One line per session sealed since the cutoff (a duration like 24h/7d, or a date/RFC3339 timestamp): agent, status, guard verdict + notes, files-changed count, a best-effort promote-eligibility read, and token usage. --json switches from the table to JSON Lines. Never a file body or a diff — the same content-free contract as orch usage --export jsonl.

"Promote decision" is a read of whether the session's guard verdict would clear worktree_promote's block today (eligible / blocked / not_run / n/a) — not a record of an actual promote/reject, which Orchemax does not persist yet.

Policy show/diff#

orch policy show
orch policy diff origin/main

show prints whatever guard:, review:, budget: and notify: sections orch.yaml currently has — nothing else, and nothing assumed present. diff <git-ref> extracts the same four sections from that ref's copy of orch.yaml (via git show <ref>:orch.yaml) and shows what changed, using git diff --no-index under the hood.

  • your-own-rules.md — the manifest a pack's rules: entries merge into.
  • hooks-and-guards.md — the guards a pack's gates: docs recommend.