Playbooks

Purpose and scopesCopy Anchor Link

A Playbook is the procedure for one change type, for example bugfix or dependency-upgrade. It can be written at any scope, and an SDLCProfile lists the playbook names a component may run (an append-only list). A change's risk class is the maximum over its steps.

Field referenceCopy Anchor Link

Rates are basis points: 10000 is every run, 1000 is ten percent, 50 is half a percent.

Example: a bounded bugfixCopy Anchor Link

This is the playbook numi init writes for a Python repository.

apiVersion: numinance.dev/v1
kind: Playbook
metadata: {name: bugfix-bounded, scope: SCOPE_REPO}
spec:
  change_type: bugfix
  steps:
    - {name: fix, capability_set: implement, risk: RISK_CLASS_MEDIUM, evidence: [diff, pr-ref], verifiers: [unit-tests, lint, typecheck]}
    - {name: review, capability_set: review, risk: RISK_CLASS_LOW}
    - {name: pr-status, capability_set: release, risk: RISK_CLASS_LOW}
  max_repair_attempts: 2
  qualification: {min_runs: 20, max_rework_rate: 1000, max_regression_rate: 0, max_rollback_rate: 50, zero_security_escapes: true}

One step per identity kind: implement is the author-agent (branch push and pull request), review is the reviewer-agent (verifier.run), release is the release pipeline (read-only status of the pull request). No step merges: with this playbook Numinance opens pull requests only. The verifier names must be those of the LanguageToolchain the repository uses.

Example: dependency upgradeCopy Anchor Link

apiVersion: numinance.dev/v1
kind: Playbook
metadata: {name: dependency-upgrade, scope: SCOPE_ORG}
spec:
  change_type: dependency-upgrade
  steps:
    - {name: bump, capability_set: scm-write, risk: RISK_CLASS_LOW, evidence: [diff, lockfile-digest], verifiers: [unit-tests, lint]}
    - {name: open-pr, capability_set: scm-pr, risk: RISK_CLASS_MEDIUM, evidence: [pr-ref], rehearse: false}
  max_repair_attempts: 2
  qualification: {min_runs: 20, max_rework_rate: 1000, max_regression_rate: 0, max_rollback_rate: 50, zero_security_escapes: true}

$ numi validate --files schemas/examples/Playbook
revision: "files"
ok       file "dependency-upgrade.yaml" Playbook "dependency-upgrade"

Bounded repair loopCopy Anchor Link

When verification fails the engine enters the repair loop at most max_repair_attempts times. The bound is finite by schema (0 to 10; absent means 2), each attempt is checked by independent verifiers, and exhausting it escalates to a human instead of retrying. Setting 0 disables repair. See Verification and recovery.

Merge and resolution semanticsCopy Anchor Link

A playbook is referenced by name from SDLCProfile.playbooks, which only appends. Its qualification merges field by field, and a narrower scope may only tighten a threshold: min_runs up, a max rate down, zero_security_escapes never from true or absent to false. The reference implementation refuses a loosening. Qualification is what a human reads before accepting a promotion; see Qualify autonomy.

Security implicationsCopy Anchor Link

• capability_set names a set of capabilities; it does not carry credentials. Policy evaluates every call, and a playbook cannot grant more than the profile and floors allow.
• risk can only raise. Declaring a step LOW does not lower the resolved risk of the RPCs it can call.
• Declared evidence that is missing downgrades success to PARTIAL, so a step cannot silently skip its own evidence.

Common misconfigurationsCopy Anchor Link

$ numi validate --files bad-steps.yaml
revision: "files"
invalid  file "bad-steps.yaml": kind: does not match the kind schema: schema: value does not match (violations: 1): \"/spec/step\": additionalProperties

Others: a short enum for risk (write RISK_CLASS_LOW), a verifier name that the toolchain does not define, and a capability_set name the deployment does not define. The last two are not caught by the open build.

What validation checks, and what it does notCopy Anchor Link

Checked by numi validate --files: keys, enums, non-empty steps, required step fields. Not checked: a max_repair_attempts above 10 passes the open loader (a copy with 11 returned exit 0); the 0 to 10 range and the 0 to 10000 basis-point range are enforced by the profile context in the engine build. Also not checked: that capability sets, verifiers and evidence names exist.

Next stepsCopy Anchor Link