2026-07-18 18:31:51 +00:00
|
|
|
|
# Contributing
|
|
|
|
|
|
|
2026-07-23 13:45:08 +00:00
|
|
|
|
This repository is governed by
|
|
|
|
|
|
[heavy-duty/ceremony](https://github.com/heavy-duty/ceremony). Agents read
|
|
|
|
|
|
[`.ceremony/AGENTS.md`](.ceremony/AGENTS.md) first, then the role file it
|
|
|
|
|
|
selects. The files under `.ceremony/` are machine-managed and must never be
|
|
|
|
|
|
edited in place.
|
2026-07-18 18:31:51 +00:00
|
|
|
|
|
2026-07-23 13:45:08 +00:00
|
|
|
|
Only triage mints issues. Everyone else opens or extends a discussion when
|
|
|
|
|
|
they find work outside an existing issue contract. Only humans merge.
|
2026-07-18 18:31:51 +00:00
|
|
|
|
|
2026-07-23 13:45:08 +00:00
|
|
|
|
## Review panel
|
fix(labels): sweep on `labeled` so the handoff is immediate
A review landing was never a trigger for the labels workflow, so the exact
moment `state:needs-human` became true — the third bot approving — fired
nothing, and the label waited on the `*/15` cron. That cron does not run at
its declared rate: measured across box, rig and cast over a two-hour window
on 2026-07-20, one scheduled run each against the eight `*/15` implies.
The obvious fix does not work. There is no `pull_request_review_target`, and
on fork PRs — all of them here — `pull_request_review` runs with a read-only
token and cannot label anything.
So the handoff wakes the sweep itself:
- `pull_request_target` also fires on `labeled`/`unlabeled`
- the author sets `state:needs-human` at handoff, as the third act after the
round summary and the review request
The author's own label write fires the sweep that validates it — an
optimistic write, not a transfer of ownership. The reconciler confirms or
corrects it seconds later, and the cron falls back to a last resort. It
cannot loop: the reconciler writes with GITHUB_TOKEN, which does not create
workflow runs; agent writes use a PAT, which does.
`labels-reconcile.sh` is unchanged — it already recomputes every open PR
from scratch on every run, which is what makes the optimistic write safe.
The `scope` job is skipped on label events, where no path can have changed.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-20 19:44:07 +00:00
|
|
|
|
|
2026-07-23 13:45:08 +00:00
|
|
|
|
The review panel is:
|
2026-07-18 18:31:51 +00:00
|
|
|
|
|
2026-07-23 13:45:08 +00:00
|
|
|
|
- `claude-bot-andresmgsl`
|
|
|
|
|
|
- `codex-bot-andresmgsl`
|
|
|
|
|
|
- `grok-bot-andresmgsl`
|
|
|
|
|
|
- `kimi-bot-andresmgsl`
|
2026-07-21 13:51:22 +00:00
|
|
|
|
|
2026-07-23 13:45:08 +00:00
|
|
|
|
Every PR needs a current-head verdict from the whole panel minus its author.
|
|
|
|
|
|
`dan-claude-bot` is triage-only and is never a reviewer. Draft PRs remain
|
|
|
|
|
|
invisible to the panel; when ready, request every eligible reviewer.
|
2026-07-21 13:51:22 +00:00
|
|
|
|
|
2026-07-23 13:45:08 +00:00
|
|
|
|
## Code and verification
|
2026-07-21 13:51:22 +00:00
|
|
|
|
|
2026-07-23 13:45:08 +00:00
|
|
|
|
- Bash executables use `set -euo pipefail`; test harnesses use `set -u`
|
|
|
|
|
|
because they assert failing commands.
|
|
|
|
|
|
- Keep shellcheck clean. Run `bash test/cli.sh` and `bash test/release.sh`;
|
|
|
|
|
|
CI also runs the Incus multi-user rehearsal.
|
|
|
|
|
|
- Match whole versions: `0.7.0` must never match `0.7.0-rc1`.
|
|
|
|
|
|
- Comments preserve the incident that bought a rule, including its issue
|
|
|
|
|
|
number.
|
2026-07-21 13:51:22 +00:00
|
|
|
|
|
2026-07-23 13:45:08 +00:00
|
|
|
|
## Changelog
|
2026-07-21 13:51:22 +00:00
|
|
|
|
|
2026-07-23 13:45:08 +00:00
|
|
|
|
Every behavior-changing PR adds one concise line under `## Unreleased`,
|
|
|
|
|
|
above the shipped heading below it. Cite the issue or PR. Never replace or
|
|
|
|
|
|
duplicate a shipped heading; the shared armed and monotonic guards enforce
|
|
|
|
|
|
both halves of this rule.
|
2026-07-21 13:51:22 +00:00
|
|
|
|
|
2026-07-18 20:54:50 +00:00
|
|
|
|
## Releases
|
|
|
|
|
|
|
2026-07-23 13:45:08 +00:00
|
|
|
|
The release ceremony, merge and tag doors, version stamps, guard semantics,
|
|
|
|
|
|
and recovery paths are defined by
|
|
|
|
|
|
[heavy-duty/ceremony](https://github.com/heavy-duty/ceremony/blob/0.1.0/README.md).
|
|
|
|
|
|
Box pins the shared machinery and doctrine at `0.1.0`.
|
|
|
|
|
|
|
|
|
|
|
|
Box uses the `file` version backend and has no artifact hook: for this
|
|
|
|
|
|
pure-Bash tree, GitHub’s source tarball for the tag is the package, and
|
|
|
|
|
|
`install.sh` downloads exactly that. `VERSION`, `CHANGELOG.md`, and
|
|
|
|
|
|
`drills/<version>.md` remain box-owned release inputs.
|
|
|
|
|
|
|
|
|
|
|
|
### What a box drill proves
|
|
|
|
|
|
|
|
|
|
|
|
The box drill is the 85-probe VM isolation contract: it exercises the trust
|
|
|
|
|
|
boundary on real hardware. The lighter Incus container rehearsal in CI proves
|
|
|
|
|
|
the tier mechanics but cannot substitute for that boundary measurement. The
|
|
|
|
|
|
record format and operating procedure live in [drills/README.md](drills/README.md).
|
|
|
|
|
|
|
|
|
|
|
|
`drills/<version>.md` and [`drill/RUNS.md`](drill/RUNS.md) are deliberately
|
|
|
|
|
|
different artifacts. The former is per-release evidence read by the release
|
|
|
|
|
|
guard; the latter is the harness’s ongoing run log and lore. Updating one
|
|
|
|
|
|
never satisfies the purpose of the other.
|
|
|
|
|
|
|
|
|
|
|
|
The family drills are independent and may run in any order. Each pins the
|
|
|
|
|
|
same fixed candidate refs: rig’s drill uses the candidate box ref, while
|
|
|
|
|
|
box’s drill mints with the candidate rig ref. Static refs dissolve the
|
|
|
|
|
|
box↔rig runtime recursion; no repository needs to release first.
|
|
|
|
|
|
|
|
|
|
|
|
A known gap remains from box#81: released box templates still default
|
|
|
|
|
|
`RIG_REF` to `main`, so a later mint may consume a rig revision other than
|
|
|
|
|
|
the one drilled. This conversion does not change that behavior or claim the
|
|
|
|
|
|
gap is closed.
|
|
|
|
|
|
|
|
|
|
|
|
## Scope labels
|
|
|
|
|
|
|
|
|
|
|
|
- `scope:cli` — `bin/box`, the command surface
|
|
|
|
|
|
- `scope:installer` — `install.sh`, versioned installs, upgrade/uninstall
|
|
|
|
|
|
- `scope:host` — host setup, teardown, firewall, and isolation stack
|
|
|
|
|
|
- `scope:tiers` — grant/revoke and multi-user boundaries
|
|
|
|
|
|
- `scope:templates` — template and profile seeds
|
|
|
|
|
|
- `scope:drill` — rehearsals, doctor, and run evidence
|