Decide which policy constrains which step.
Guardrails, policies, ADRs, guidelines, runbooks and architecture notes are documents your team writes and reviews in Git. You choose where each one applies — the whole pipeline, one step, or a single task — and the model reasons inside the set you attached to that decision, not inside whatever it inferred from the prompt.
Knowledge and context, end to end.
The flow stays explicit enough for operators to inspect, secure, automate and improve.
Write the document
A guardrail, policy, ADR, runbook or architecture note is Markdown in a config repository, reviewed through the same pull request as any other change.
Bind it where it applies
Declare knowledge_context on the pipeline, on a step or on a single task. You are choosing the scope of the constraint, not handing the platform a corpus to search.
Resolve before dispatch
Every reference is authorized for the effective subject and resolved. A required document that cannot resolve stops the run before anything executes.
Snapshot with the run
The resolved text is stored on the run, so editing a guardrail next month never rewrites what last month's decision was bounded by.
What teams can standardize.
These are current NopsAI platform primitives, not a future-state feature list.
Eight document kinds
Architecture, guardrail, policy, ADR, guideline, runbook, reference and example — each a first-class governed resource with its own access model.
Two kinds that block
Guardrails and policies are checked against the goal, the generated command, direct scripts, file writes and MCP arguments. The other six inform the work without gating it.
Team defaults, additively
A team can set a default document per kind. A pipeline adds its own on top and cannot replace, weaken or remove what the team owner set.
Your wiki, Git-owned
Notion and Confluence pages mirror into governed documents through a Git-defined connection. Git owns which page is attached; the mirrored body stays runtime state, so an upstream edit is never reported as drift.
Declared once, reviewed like code.
The example is declarative and Git-reviewable. Runtime behavior still passes through live AAA, credential, compatibility, execution and monitoring boundaries.
---
name: rollback-safety
kind: guardrail
description: What a rollback may and may not do in production.
access:
visibility: restricted
teams:
- platform
content: |
# Rollback safety
- Never roll back across a schema migration. Propose a
forward fix and stop.
- Never widen an IAM binding as part of a rollback.
- State the blast radius before proposing any action.
---The same document, bound at the level you choose.
Pipeline, step and task bindings merge rather than replace each other. A pipeline-wide policy stays in force while a step adds the architecture note only that step needs, and a narrower binding can never subtract from the broader one.
name: release-readiness
version: "1.0.0"
governance_level: strict
# In force for every step and task below.
knowledge_context:
- kind: policy
ref: platform/deployment-approval
required: true
- kind: guardrail
ref: platform/rollback-safety
required: truePipeline level — in force for every step in the run.
steps:
- name: assess-rollback
# Added on top of the pipeline binding, not instead of it.
knowledge_context:
- kind: architecture
ref: platform/payments-topology
required: true
tasks:
- name: propose
goal: Propose a rollback or a forward fix, with blast radius.
knowledge_context:
- kind: runbook
path: .nopsai/runbooks/payments-rollback.md
required: trueStep and task level — added for the decision that needs it.
What lands on the run record.
The run does not only record that a model was consulted. It records which documents were in scope for the decision, so “what bounded this?” is answered by opening the run rather than by reasoning about which version of a policy was current that week.
The documents in scope
The resolved text of every document that applied, stored with the run — which documents were in scope for this decision, and what each of them said at the time it was taken.
Knowledge and policy revisions
One deterministic revision across all selected knowledge, and a separate one covering only the blocking guardrails and policies, so a change to a reference document is distinguishable from a change to a constraint.
The governance level that applied
Whether the decision was made under strict or advisory, resolved at the pipeline, step or task where it was taken.
The conflict, when there was one
Where a guardrail or policy ruled an action out, the run keeps the conflict the model named instead of the action it would otherwise have returned.
Configuration stays inside the governance model.
Authorized per document
knowledge_context.use is checked for the effective subject before dispatch, so a run cannot read a document its caller was never granted.
Fails closed by default
Under the default strict governance level only a clear allow proceeds. A review that could not be completed at all fails the task at every level, advisory included — an unevaluated constraint is not a satisfied one.
Reviewed before it lands
Documents, team defaults and wiki connections are configuration. Changing a guardrail is a pull request with an author and a reviewer, not a console edit.
Recorded, not inferred
Run detail keeps the resolved documents, the knowledge and policy revisions and the governance level that applied, so the constraint is a field rather than a reconstruction.
Continue through the operating model.
06 · Runtime and execution
Dispatch per-run agents to Docker or Kubernetes runners using scope, capacity, affinity, routing and runtime pools.
07 · Evidence and monitoring
Connect run history, system logs, outputs, AI usage, reliability, security, cost, alerts and recommendations.
01 · Workflow orchestration
Combine scripts, LLM goals, approvals, reusable steps and child pipelines without splitting the operating model.
Bring a real knowledge and context workflow.
We can map the configuration, authorization, runtime and evidence boundaries against your current platform model.