Skip to content
ContractSpec
Start here

Core guide · Guides · 3 min read

Build interfaces around roles and intent

Resolve appropriate surfaces for people and agents while keeping authority on the execution side.

Source context

Source-guided · d58fa5b7

Repository links may require access. Source inspection is separate from a clean public-package installation.

AN INTERACTIVE READING MAP

Get the shape of this guide.

Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.

READING SEQUENCE

Understand how the ideas connect

01 / READING POINT

Start with the task, actor and context

A reviewer, an operator and an agent may work on the same workflow while needing different information and actions. Model that difference explicitly instead of copying the entire workflow into unrelated screens.

RoleMorph resolves a contract-authored surface from supplied context. The resolver validates the context and registry bindings, removes invalid components and returns actions with their resolved boundaries.

1 / 4

0 points in your packet

Start with the task, actor and context

A reviewer, an operator and an agent may work on the same workflow while needing different information and actions. Model that difference explicitly instead of copying the entire workflow into unrelated screens.

RoleMorph resolves a contract-authored surface from supplied context. The resolver validates the context and registry bindings, removes invalid components and returns actions with their resolved boundaries.

Make action states understandable

The resulting actions distinguish allowed, requires_approval and blocked states. For an AI agent, the resolver also builds a plan that separates those action lists and reports missing information from diagnostics.

Use these states to explain what a caller can attempt next. A reviewer may need an approval action; an agent may need a structured reason it cannot proceed. Avoid turning a hidden button into the sole enforcement mechanism.

Surface behaviorGood useBoundary
Different data depthShow the information needed for a roleFetch and redact through trusted server rules
Review-required actionExplain the next approval stepRequire evidence again at execution
Blocked actionProvide a useful reason or alternativeDo not execute through another unguarded route
Agent planExpose allowed and missing-information pathsThe plan itself grants no authority

Design the unresolved state

An unknown or ambiguous surface match is a real product state. The resolver can return an unresolved result with diagnostics and no actionable components. Design a clear explanation and recovery path for that case.

A fallback screen should help the person choose a valid context or seek access. It should not silently replace missing policy context with a more permissive role.

Test a small role matrix

Choose one workflow and compare the intended surfaces for two human roles and one agent actor. Verify the components, action states and explanations each receives. Include an invalid binding and an unknown role.

Then call the backend directly for an action hidden or blocked by the UI. The server must still enforce its policy and approval requirements. Surface resolution and execution authorization are complementary checks.

See what a personal choice should change.

The same work can be shown in a quiet sequence, a dense overview or a detailed review. Inspect the boundary behind each choice.

What would help in this moment?

A CONCRETE SITUATION

Reduce the presentation load.

A person wants to focus on the current task without losing the rest of the workflow.

What changes

A focused surface can show one section, a clear next step and optional supporting context.

What stays explicit

The complete underlying work and the person’s actual permissions do not change.

Follow the consequence

Give a visible route back to the full picture. This site’s Focus and Step by step controls demonstrate a reversible reading projection.

Source-informed presentation examples. The local website applies its own authored projections; the V9 source review inspected preference precedence, role independence, shell boundaries and reversible adaptation in ContractSpec.