Contributing

regulator is an agent harness with a cybernetic control plane. Contributions that fit are mechanisms, evidence and documentation; the prime directive applies to every one of them:

Prompts advise. Types describe. Gates enforce.

A rule is implemented at the strongest level that can carry it — a type, then a deterministic gate, then a typed tool, then a model's judgment, then a prompt — and a pull request that solves a mechanically enforceable rule with prompt text alone will be asked to move it down the hierarchy.

Where to start

• ROADMAP.md maps the open work to issues, and its threads table lists work that is designed but not yet scheduled, each with its next step. Issues labelled good first issue are bounded and self-contained. How work moves from an idea to an issue is its last section, "How this page is kept".
• docs/research/ holds the design notes behind the threads, including a running list of open questions.
• docs/DEBT.md is what the build knows it has not yet absorbed, one row each, with the registry card that records it.
• AGENTS.md is the project's own operating rules — the architectural boundaries, the repository conventions, what to confirm before finishing. It is written for coding agents and applies to people.
• The documentation site (https://docs.regulator.metacoding.io/) explains the control plane, the definition files and the CLI.

Setting up

Node 22.19 or later and pnpm 10.12.1 (pinned in packageManager).

pnpm install
pnpm check          # build, typecheck, every package's tests, the registry and definition checks
pnpm --filter regulator-docs dev   # the docs site locally

pnpm check must pass on both Node versions CI runs (22.19 and 24). Tests use Node's built-in runner and run without a live model; anything that needs one is a drill or an eval, not a test.

What a change carries

1. A registry record, when it is a regulator. Every mechanism that absorbs a class of failure has a card under packages/regulator/registry/regulators/: purpose, the failure absorbed, the mechanism level, where it is enforced, the tests that evidence it, at least one limitation, an owner and a review date, the eval arm that switches it off, and the condition under which it may be retired. regulator check refuses a card without a limitation. introducedIn says unreleased on a new card: the release commit rewrites it to the version being tagged, and the release workflow refuses to publish while any card still says so (see Releasing). Regenerate the rendered documents:

   pnpm --filter @metacoding.io/regulator registry:docs

2. A debt row, when a limitation names later work. A new limitation that says "not yet", names a milestone or points at another issue gets a row in docs/DEBT.md in the same change. A change that pays a row strikes it and updates the card.

3. Tests for the mechanical behaviour, beside the code, without a model.

4. Evidence in the pull request: the exact commands run and their result. A check that was not run is reported as not run.

5. Provenance preserved: who or what emitted a finding, which revision it refers to, and what authority acted on it. Nothing infers a unit's progress from the repository.

Boundaries a change may not cross

• The orchestrator is the only execution authority. Regulators observe, verify, route and veto; they do not schedule or dispatch.
• vsm/ is S5. The project's identity, architecture and invariants change by a proposal and a person's decision, never as a side effect of a code change. A pull request that touches vsm/ says so in its title and why in its body.
• packages/regulator never imports a host. Pi integration lives in packages/regulator-pi behind the host seam.
• The definition is declared, not assembled. Profiles, policies, workloads and the identity seed are files validated by regulator check; a change to them is a policy change and is reviewed as one.
• No new prompt-only enforcement where a typed or mechanical mechanism was reasonable.

Pull requests

• Small and reviewable; one concern per pull request. Do not widen a change because an adjacent improvement is attractive.
• If a change reveals an architectural conflict, record it (an ADR under docs/decisions/, or an issue) rather than fitting the architecture to the code.
• The description states what changed, what it pays (debt rows, cards) and the verification commands with their result.
• CI runs pnpm check on both Node versions and builds the docs site; all three must be green.

Releasing

A release is one commit and one tag, and the workflow (.github/workflows/release.yml) publishes every package when the tag is pushed. The commit:

1. bumps every workspace package to the version (the tag must equal v<version>);
2. turns the changelog's [Unreleased] heading into [<version>] — <date> and opens a new empty [Unreleased];
3. rewrites "introducedIn": "unreleased" to the version on every registry record added since the last release, and regenerates the rendered documents;
4. passes pnpm check.

The workflow re-checks 1 and 3 and refuses the publish otherwise, so the recovery from a partial publish is a re-run at the same tag, never a new version.

Reporting

• A bug — the bug template: what you ran, what the instance recorded (regulator unit show, unit evidence, doctor --json), what you expected.
• A gap a regulator does not cover — the debt template: the card, the route around it, and whether it is the deployment's or the build's.
• A proposal — the proposal template: the failure class, the mechanism level you think can hold it, and what it would cost. Proposals that would change vsm/ are discussed there first.

Licence

Contributions are accepted under the repository's Apache-2.0 licence. The course, Viable Agents, is separate and not open to contribution here.