Core concepts

• 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 — 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.

• 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 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.

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.