Configuration
How the typed YAML under .numinance/ works, the shared envelope, every configuration kind with its scope and owning page, and how scopes layer.
The kinds, their JSON Schemas and the open numi validate --files check are public. Profile resolution, floors and runtime enforcement belong to the proprietary engine, which is not generally available.
How .numinance/ works
Numinance reads its configuration from a .numinance/ directory in each repository, and from an organization policy repository for the org scope. Every file is one YAML document of one kind, and every kind is a protobuf message in numinance.kinds.v1. The JSON Schema used to validate the YAML is generated from those messages, so the proto, the schema and the loader cannot drift apart silently.
Configuration is code. It goes through pull requests, branch protection and CODEOWNERS. The directory .numinance/policy/ is the protected location: a policy-bearing document carries authority only when it is read from the protected branch of the repository or from a signed policy bundle. See Layout and scopes.
The envelope
All kinds share one envelope.
apiVersion: numinance.dev/v1
kind: AutonomyPolicy
metadata: {name: org-ladder, scope: SCOPE_ORG}
spec:
defaults: {level: AUTONOMY_LEVEL_PR}Prop
Type
Three spelling rules are worth memorising. The envelope key is apiVersion; every other key is snake_case. Enum values are written with their full proto name (AUTONOMY_LEVEL_PR, not PR). Durations use the protobuf JSON form (7200s). Unknown fields are errors everywhere except under extensions.
Kinds
The proto directory defines sixteen kinds and the shared meta file. Fifteen kinds are authored (one of them, EvalSet, is alpha); ContextBundle is produced by Numinance and never loaded as configuration.
| Kind | Scope | Purpose | Page |
|---|---|---|---|
SDLCProfile | org, repo, component | Binds a component to stages, playbooks, packs, toolchains, adapters, autonomy, residency and budgets. | SDLCProfile |
StageRegistry | any; selected only by the org profile | Maps your stage names onto the fixed Change state machine. | StageRegistry |
Playbook | any | The procedure for one change type: steps, bounded repair, qualification. | Playbooks |
AutonomyPolicy | any; floors only at org | Autonomy level per playbook, risk class and environment, under floors. | AutonomyPolicy |
LanguageToolchain | any | Language version and the deterministic verifiers for one language. | Toolchains and packs |
ArchitecturePack | any | Conventions bound to checks; a rule without a check fails validation. | Toolchains and packs |
AdapterSelector | any | Which provider and instance implements each port for a scope. | Adapters and environments |
EnvironmentProvider | any | How disposable environments are created. | Adapters and environments |
IndexerPlugin | any | How the code graph is built. | Adapters and environments |
ExecutorManifest | org only | Declares an author executor: adapter, capabilities, models, cost class. | Adapters and environments |
KnowledgeConnection | org only | An approved, read-only knowledge source the context resolver may search. | KnowledgeConnection |
ControlPack | org only | Controls of one compliance framework, required evidence and approvals, and added floors. | Governance kinds |
ResidencyPolicy | any; floors only at org | Where execution and inference may happen, and data-handling limits. | Governance kinds |
BudgetPolicy | any | Per-Change and per-run limits; exhaustion pauses and escalates. | Governance kinds |
EvalSet | alpha, v1alpha1 | Versioned, reference-only replay cases. Not part of profile resolution. | Evals and ContextBundle |
ContextBundle | produced | The knowledge selected for one stage of one work unit. Never authored. | Evals and ContextBundle |
meta (Metadata, Scope, MergeDirective) | not a kind | The envelope, the scope enum and the merge directives every kind uses. | this page |
The scope column reads the proto and loader: KnowledgeConnection, ControlPack and ExecutorManifest are org-scoped only (the loader refuses another metadata.scope). A field marked with the FORBID merge directive can be set only by a document whose metadata.scope is SCOPE_ORG, or by a control pack.
Scopes, layering and precedence
Three scopes exist: SCOPE_ORG applies to every repository of the organization, SCOPE_REPO to one repository, SCOPE_COMPONENT to one component of a repository. Resolution loads org, then repo, then component, a maximum depth of three. Each field of a kind declares how it merges.
| Directive | Meaning |
|---|---|
| (none) | A singular message merges field by field. A scalar, enum, list, map or well-known type is replaced by the narrower scope. A oneof is replaced as a unit. |
MERGE_DIRECTIVE_REPLACE | The narrower scope's value replaces the whole value, a message included. Adapter bindings use it so one scope's provider is never paired with another scope's instance. |
MERGE_DIRECTIVE_APPEND | Keeps the wider scope's names, then adds the narrower scope's names not already present. Only on repeated string fields. A repository can add a playbook but cannot remove a control pack the org applies. |
MERGE_DIRECTIVE_FORBID | A floor. Only a kind loaded from the org scope, or a control pack, may set it. A narrower scope fails validation. |
Two consequences define the trust model. A floor cannot be lowered by the scope it constrains. And a repository that asks for a playbook, toolchain or adapter name the org did not grant gets that name recorded as ignored (outside the org-granted set) and not applied; only the org scope selects the stage registry and grants names.
What the open tools check
numi validate --files PATH runs the generated strict schema and the loader checks on each document. It does not resolve profiles, check floors across files or confirm that a named provider is installed. Every kind in schemas/examples passes it. See Validation and errors for the full catalogue of what is and is not caught, and numi validate for flags and exit codes.
Next steps
Release and incident response
A designed walkthrough of a governed release with a canary window and rollback, event-driven incident response, the four breaker positions, and human-only break-glass.
Layout and scopes
Where .numinance/ files live, which path is protected, how the strict schema and the extensions escape hatch work, and the size and symlink limits the loader enforces.