Profiles and gates

Profiles choose the semantic shape of a run. Gates decide whether a phase result is good enough to continue or deliver.

If you are new to the concept, start with Profile semantics. This page goes deeper into policy and extension design. When you need the full schema vocabulary, use Profile reference.

Profiles

Use profiles to express workflow depth and risk posture:

• small task;
• feature;
• complex feature;
• review-only;
• planning-only;
• custom team workflow.

Profile selection can also be delegated to the advisor selector: --profile auto-detect. The selector recommends a concrete semantic profile and mode, then Orcho dispatches the resolved profile normally.

Keep the distinction clear:

Surface	Role
concrete profile	executable workflow shape
auto-detect selector	recommendation step before dispatch
operating mode	strictness posture for the selected work kind
topology advice	separate recommendation about mono vs cross-project shape

Isolation policy

Profile policy is not only “which phases run”. It also decides where the worker is allowed to operate.

Isolation answers:

Should this run edit a retained Orcho worktree, or the target repository checkout itself?

Read it as a risk and review policy:

Isolation choice	Worker subject	Review subject	Good fit
per_run worktree	Orcho creates a run-owned checkout under the workspace runspace.	The retained run diff, receipts, and delivery artifacts.	Feature, refactor, migration, and any delivery run where review/repair need a stable subject.
off / direct checkout	{checkout} and {project} are the same folder.	The current project working tree.	Planning/research, current-diff audit, code review, or a small intentional direct edit.

This is why isolation belongs beside profiles and gates. A profile that edits directly in the project checkout has a different operator contract from a profile that edits a retained worktree and delivers back later.

Resolution order:

CLI override
  > profile worktree_isolation
  > workspace/app worktree config

Typical built-in intent:

Profile family	Default isolation posture
feature, complex_feature, refactor, migration	use the global worktree config, normally per_run
planning, research	off, because they produce/read planning artifacts rather than delivery diffs
delivery_audit, code_review	off, because they inspect the operator’s current diff
small_task	off, because it is the light direct-edit path

When a per-run isolated start sees uncommitted changes in the project checkout, pre-run dirty intake is part of the same policy surface:

include  seed the run-owned worktree with the current diff
exclude  start from HEAD and leave local changes untouched
commit   commit first, then start from that commit
halt     stop before the run starts

The practical rule:

If you need…	Prefer…
protected source checkout, retained diff, repeatable review/repair, delivery boundary	per_run worktree
direct inspection of the current dirty tree	off / direct checkout
an audit before committing your own work	off / direct checkout
a large delivery run with many files and receipts	per_run worktree

Read Workspace model for {project} versus {checkout}, and Profile reference for the schema-level setting.

Gates

Use gates to express non-negotiable checks:

• review contract;
• verification receipts;
• final acceptance;
• delivery decision;
• scope or provenance policy.

The profile decides what work happens. The gates decide whether the work is trusted.

Real verification header

In live output, gate policy should be visible before implementation begins:

Verification
  mode      pro
  envs      core-local
  policy    declared in contract (require, suggest, warn)
  effect    require receipts; missing/failed resolved at gate time
  gates     gate               timing           run     policy   kind
            env-provenance     after_implement  auto    warn     cheap
            lint               after_implement  auto    warn     cheap
            run-state-unit     after_implement  auto    require  unknown
            verification-unit  after_implement  auto    require  unknown
            cli-sdk-unit       after_implement  auto    require  unknown
            broad-non-e2e      after_implement  auto    require  unknown
            e2e                operator         manual  suggest  unknown

Read it as policy, not as a test list. policy says whether a missing or failed receipt can block the delivery. kind is the cost hint. A gate can be expensive and still required; cost and blocking tier are separate axes.

Next

• Profile reference lists profile modes, schema keys, step settings, handoffs, quality gates, and cross projection.
• Configuration reference shows how profile settings fit into local config and overrides.