Roles

Definition

A Role is a bounded authority definition that specifies what an AI agent may act on within a governed session. It defines the operational perimeter of the agent’s authority: what it may propose, what it may execute, and — crucially — what it may not do without explicit human approval.

A Role is not a persona, a prompt instruction, or a personality configuration. It is a governance artifact — an append-only record in the Yanzi corpus that defines the formal authority boundary for a specific class of engineering sessions.

The Proposal/Execution Boundary

Every Role defines two authority scopes:

Proposal scope: what the agent may generate for human review. Proposal scope can be wide — the agent may reason about and propose changes to any area within the project’s domain.

Execution scope: what the agent may act on without further human review. This is always narrower than the proposal scope. Execution scope is what the agent has authority to commit, push, deploy, or otherwise act on.

This separation is the core governance mechanism of a Role. It ensures that consequential decisions are reviewed by a human before action is taken.

Role Examples

Draft-only role: proposal scope covers any file in the repository; execution scope is empty — the agent may not commit, push, or deploy anything.

Implementation role: proposal scope covers files within a defined service boundary; execution scope allows creating and modifying files in that service, but not running migrations, modifying configuration, or deploying.

Read-only analysis role: proposal scope covers any project resource; execution scope is empty — the agent may read and analyze but not modify anything.

Release engineer role: proposal scope covers the full release pipeline; execution scope allows creating release branches and draft PRs, but not merging or deploying without human approval.

Difference from Rules

Rules define unconditional constraints — what the agent may never do in a governed session. Roles define bounded authority — what the agent may do within a specific session type.

Rules limit Roles. An agent with a wide execution scope cannot bypass an active Rule. Rules represent the governance floor; Roles operate above it.

In Yanzi

Roles are defined as context artifacts in the Yanzi corpus and applied at session initialization. The active Role is composed into the session context and recorded in the operational lineage. Role violations — actions outside the defined execution scope — are flagged in the governance trace.