# Core concepts

The vocabulary Semel uses — workspace, project, Build Brief, versions, the reviewer cascade, questions, human approval, execution grants, and certificates.

These terms describe the durable state an agent reads and advances. Tool responses return them in `structuredContent`, often with a control block naming the legal next action.

## Workspace & project
<a id="workspace-project"></a>

- **Workspace** — the top-level tenancy and authorization boundary. Every request resolves exactly one workspace.
- **Project** — one independent effort inside a workspace. The normal shape is one project per effort and one brief per project. A project-allowlisted principal cannot create a new project because that would widen its own reach.
- **Codebase link** — a project reference to a repository a person has already connected. `project_codebase_link` cannot create provider credentials or connect a new GitHub account.

## Build Brief & immutable version
<a id="brief-version"></a>

- **Build Brief** — the versioned source of truth for a project. Its canonical sections, in contract order, are: Goal, Users and context, Scope, Out of scope, Requirements, Edge cases, Acceptance criteria, Roles and permissions, States and edge states, Product solution, Technical solution, Data-model implications, Architecture assumptions, Design (UI/UX), Testing / QA checklist, Unit test plan, Integration test plan, UI/UX test plan, Open questions, Work orders, Required evidence, Decisions, Source artifacts and transcripts.
- **Replacement update** — `brief_update` supplies the complete replacement content for the next version; omitted arrays become empty by contract. Read the current full brief before editing and carry forward every section you intend to preserve.
- **Immutable version** — each content change creates a version with a content hash. History remains readable; an export binds to exact version and artifact identities.

## Reviewer cascade, question round & human approval
<a id="review"></a>

- **Review origination** — `review_start` or `review_new_pass` creates work in `hosted` or `local` execution mode. Origination chooses dispatch intent; it does not configure the cascade or grant execution.
- **Reviewer cascade** — an ordered set of reviewer lenses. A local driver fetches the exact pinned lens with `review_execution_skill_get`; it does not invent or substitute reviewer instructions.
- **Question round** — a reviewer opens a durable question only for a true build-shaping fork. The accepted answer is attributed and can be superseded through the explicit operation. Notification delivery may degrade while the canonical question remains available.
- **Human approval** — a person owns the gate and proposal decisions. Agent authentication, scope, or an execution grant never substitutes for that decision.

## Execution grant, epoch/fence/lease & certificate
<a id="execution"></a>

- **Execution-grant request** — an agent may create a request with `review_execution_grant_request`; a human still mints or approves the grant. Grants are separate from OAuth scopes, time-limited, and consumed per eligible step.
- **Epoch / fence / lease / sequence** — a claim opens an epoch; a fence rejects an obsolete claimant; a lease bounds claim ownership; monotonically ordered sequence numbers make checkpoint replay detectable. Heartbeat extends only the current lease.
- **Checkpoint** — a bounded, durable progress event. It records results and safe evidence references, never raw secrets, arbitrary repository dumps, or chain-of-thought.
- **Release and submit** — release hands back an incomplete epoch; submit finalizes a completed one after validation. Status and sync are the recovery reads.
- **Certificate** — the signed attestation created for a completed execution. It binds identities and hashes without embedding brief text, questions, checkpoint prose, secrets, or reasoning.

## Receipts, bindings & control blocks
<a id="receipts-and-control"></a>

Every mutation carries an `idempotencyKey`. Replaying the same key and same arguments returns the prior receipt; reusing it with different arguments fails with `CONFLICTING_IDEMPOTENCY_REPLAY`. Recipes bind later arguments only from the returned `structuredContent`, never from prose or guessed IDs. When a call cannot advance, its control block reports a stable code, retryability, current state, permitted next operations, safe text, and an operator URI only where a person can act.

Canonical page: https://docs.semel.ai/concepts