Operations
The operator's mental model for running Numinance day to day - who approves, who can stop it, how autonomy is earned, and how a bad change is undone.
numi build.- proto/numinance/types/v1/types.proto
- proto/numinance/kinds/v1/autonomy_policy.proto
- proto/numinance/kinds/v1/playbook.proto
- proto/numinance/kinds/v1/eval_set.proto
Operating Numinance is not watching an agent. It is owning four dials: how much authority exists, who can approve, who can stop everything, and what counts as proof.
Day two is about authority, not prompts
Once a repository is onboarded, an operator rarely touches a prompt. The work moves to a small set of controls that sit outside the model:
| Control | What it answers | Page |
|---|---|---|
| Where it runs | Whose infrastructure holds code, credentials and evidence | Installation modes |
| Risk and approval | What is allowed, what needs a human, who that human may be | Risk and approval |
| Circuit breaker | How to cap or halt all autonomous work immediately | Circuit breaker |
| Evaluations | When a playbook has earned more autonomy | Evaluations |
| Rollback and recovery | What happens when a change or a run goes wrong | Rollback and recovery |
Each control is enforced by the runtime, not requested of the agent. That is the point of "Your policy decides. Not the model."
The operator's mental model
Think of the system as four layers, from the most permanent to the most immediate.
- Floors. Organization-level limits that no narrower scope can raise. A floor says, for example, that high-risk work never exceeds suggestion. Lower scopes may only tighten.
- Policy. The AutonomyPolicy assigns a ladder level per scope, risk class and environment. Policy is evaluated before every privileged action, outside the model.
- Grants. For each work unit, the runtime derives a short-lived, narrow grant from profile, playbook step, risk and level. The agent can ask for less, never more.
- Breaker. A customer-local switch with four positions that caps effective autonomy over everything above it, and needs no outside service to work.
Operations is mostly about the edges of these layers: tuning floors, reviewing approvals, watching for anomalies, tripping the breaker, and deciding when evidence justifies a promotion.
Autonomy policy explorer
Given defaults, rules and floors, what is the highest level this change may reach?
- OPERATEoperations against production
- RELEASEdeploys to production
- STAGEdeploys to pre-production
- MERGEmerges when policy allowsrequestedeffective
- PRopens pull requests
- IMPLEMENTwrites in a sandbox
- SUGGESTproposes, writes nothing
- OBSERVEreads only
The dependency-upgrade rule matches and requests MERGE. No floor matches, so nothing lowers it.
- 1 · Defaultdefaults.level = PR (overridden by the matching rule)
- 2 · Rule: dependency-upgrade, LOW → MERGEmatchedplaybook (resolver context): dependency-upgrade ✓ · risk (exact): LOW ✓
- 3a · Floor: risk HIGH or higher → max SUGGESTnot matchedrisk (resolver context): LOW; a floor matches that class and every higher one.
- 3b · Floor: environment production → max MERGEnot matchedenvironment (resolver context): a different environment.
- 4 · Resultmin(requested MERGE, lowest matching floor none) = MERGE
apiVersion: numinance.dev/v1kind: AutonomyPolicymetadata: {name: org-ladder, scope: SCOPE_ORG}spec:defaults: {level: AUTONOMY_LEVEL_PR}rules:- {match: {playbook: dependency-upgrade, risk: RISK_CLASS_LOW}, level: AUTONOMY_LEVEL_MERGE}(matched)floors:rules:- {match: {risk: RISK_CLASS_HIGH}, max_level: AUTONOMY_LEVEL_SUGGEST}- {match: {environment: production}, max_level: AUTONOMY_LEVEL_MERGE}
- Kernel floors are always on. They sit under every policy and no rule or default removes them.
- The highest configured level never bypasses a matching floor. Floors cap; they are not suggestions.
- Promotion is proposed, then accepted. Evaluation may propose a higher level; a human accepts it. An agent never grants itself a rung.
Text description
The ladder is the AutonomyLevel enum, lowest to highest: OBSERVE (reads only), SUGGEST (proposes, writes nothing), IMPLEMENT (writes in a sandbox), PR (opens pull requests), MERGE (merges when policy allows), STAGE (deploys to pre-production), RELEASE (deploys to production), OPERATE (operations against production).
Resolution follows AutonomyPolicySpec: the level is the lowest level among matching rules, else defaults.level; then no level above the lowest max_level among the matching floors. The example policy is org-ladder: default PR; one rule (playbook dependency-upgrade and risk LOW sets MERGE); two floors (risk HIGH or higher caps at SUGGEST; environment production caps at MERGE).
- In a rule, risk matches exactly and a key the change has no value for does not match.
- In a floor, risk matches that class and every higher one, and a key the change has no value for counts as a match, which is why the toggle
nonefor environment still matches the production floor. - The playbook, risk and environment values are the resolver context of the change. They are not extra fields on a rule. The what-if rule level only changes the simulation; the YAML shown is the real example text.
- Kernel floors are always on. Promotion to a higher level is proposed by evaluation and accepted by a human, and is never self-granted.
- An org with no floors gets the shipped floor (SUGGEST for HIGH and PRIVILEGED, PR for the rest); control-pack floors can only add caps.
Everything here is simulated in the browser from the example policy. Nothing is connected to a running engine.
What a human is still for
Full autonomy here is configurable, governed and human-accepted. It is never unrestricted. Humans keep four jobs that no agent identity can take over:
- Approve changes that policy routes to approval. The approver is a distinct, attributable human, never the author agent.
- Accept promotions. Evaluations can propose that a playbook has qualified for a higher level. A human accepts. Nothing promotes itself.
- Trip and reset the breaker. Reset requires a human and a reason.
- Use break-glass. A named human, time-boxed, separately logged. See Circuit breaker.
A typical week, in design terms
- Review the approvals queue, with each request showing the plan, the evidence so far and the policy reasons that routed it to a human.
- Skim denied intents and budget exhaustions. A denial is a signal that policy worked, or that a playbook asks for more than it should.
- Check qualification per playbook. If a playbook has enough clean runs and no severe event, consider accepting a promotion. If it had a severe event, qualification starts over.
- Confirm the breaker is where you expect it, and that the runtime reports the position you set.
Failure modes operators should expect
- Approval fatigue. If everything routes to a human, humans stop reading. Tighten playbooks and raise floors deliberately instead of approving by habit.
- Silent policy drift. A policy change is itself a change under protected paths. Review it as code, and treat a widened permission as needing re-approval.
- Over-trusting evidence. Evidence proves provenance and chain integrity under keys you pin. It does not prove the code is correct. See Evidence and trust.
- Treating the open CLI as the runtime.
numivalidates configuration and verifies evidence. It does not run changes. See Status.
Commands and exit codes
The stable exit-code table of the open numi build, and the designed command surface that is not in the open build.
Installation modes
Where the Numinance runtime is designed to run - managed with a customer data plane, sovereign, and the later air-gapped milestone - and what you provision in each.