# Recipes
Fourteen executable, state-aware journeys generated from schema-validated fixtures and the live MCP operation registry.
Start with [Quickstart](https://docs.semel.ai/quickstart), then choose a recipe. Each recipe starts from a natural-language request and names its prerequisites and human boundary. The structured block is generated from a fixture whose tool names, complete inputs, representative outputs, output bindings, state transitions, terminal conditions, errors, and recovery paths are validated against the live registry.
## Discover tools and prove read access
Use this at the beginning of every session. Live `tools/list` establishes capability; `project_list` and `brief_list` establish authentication and project reach. Configuration output alone is not readiness.
Prove that the configured MCP endpoint is authenticated, protocol-compatible, and exposes the capabilities needed for the task.
**Requests you can make**
- “Connect Semel to this agent.”
- “Check whether this Semel connection can run a local review.”
**Prerequisites**
- Scopes: none
- State: MCP client configured or ready to configure
- Human: Choose the intended Semel environment and authentication method.
**Ordered steps**
1. **connect** — Protocol action (connect): Connect to the configured Semel MCP URL.
Next: Classify connection failures separately from authentication failures.
2. **authenticate** — Protocol action (authenticate): Complete the harness-supported bearer-token or delegated OAuth flow.
Next: Request the live tools list only after authentication succeeds.
3. **tools-list** — Protocol action (tools_list): Read the actual MCP tools/list response.
Next: Compare the required capability names for the intended recipe.
4. **compare-capabilities** — Protocol action (compare_capabilities): Check names and protocol compatibility; never require an eternal tool count.
Next: Continue only when every required tool name is present.
**Done when:** The live server is authenticated and every capability required by the selected recipe is present.
**Allowed transitions**
- configured → connected
- connected → authenticated
- authenticated → capabilities_verified
**Errors and recovery**
- `MCP_CLIENT_CONNECTION_FAILED` — Transport setup cannot reach the configured endpoint. Verify the environment URL and network, then reconnect; do not relabel this as a login failure.
- `MCP_CLIENT_CAPABILITY_MISSING` — A required tool name is absent from tools/list. Stop, report the exact missing names, and refresh or upgrade the integration.
- Repeat tools/list after reconnect or session reload.
- Negotiate protocol support separately from credential repair.
**Never assume**
- A successful login proves the MCP server is usable.
- The tool count is permanently fixed.
- A missing capability is an authentication failure.
## Create a project for a new effort
First inspect existing projects for considerable overlap. A net-new effort normally gets one new project. Confirm the exact name before creation; an allowlisted principal cannot widen its own reach by creating a project.
Reuse an exact existing project or create one fresh project, then carry its structured project id.
**Requests you can make**
- “Create a project for checkout reliability.”
- “Find the checkout project and rename it to Payments reliability.”
**Prerequisites**
- Scopes: `brief:read`, `brief:write`
- State: Authenticated agent with all-project creation access
- Human: Resolve ambiguous project matches and explicitly confirm project creation, rename, and repository scope.
**Ordered steps**
1. **project_list** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{}
```
```json
{
"projects": []
}
```
Expected result variant: **project-list**. Bind projects from structuredContent.projects.
Next: Reuse one exact match, ask about ambiguity, or prepare project_create.
2. **project_create** — Only when no considerably overlapping project exists and the human explicitly confirms creation.
```json
{
"name": "{{projectName}}",
"reviewMode": "direct",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
```
Expected result variant: **project-created**. Bind projectId from structuredContent.project.id.
Next: Carry project.id into every project-scoped call.
3. **project_get** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"projectId": "{{projectId}}"
}
```
```json
{
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
```
Expected result variant: **project**. Bind project from structuredContent.project.
Next: Confirm the resolved project details before mutation.
4. **project_rename** — Only when the human requested and explicitly confirmed the rename.
```json
{
"projectId": "{{projectId}}",
"name": "Payments reliability",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Payments reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
```
Expected result variant: **project-renamed**. Bind renamedProject from structuredContent.project.
Next: Keep the same project id after the rename.
5. **project_codebases_list** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"projectId": "{{projectId}}",
"limit": 50
}
```
```json
{
"projectId": "prj_fixture_checkout",
"codebases": [
{
"repositoryId": "repo_fixture_throughline",
"owner": "throughline",
"name": "throughlineos",
"trackingBranch": "main",
"selected": false,
"selectionStatus": "available"
}
],
"nextCursor": null
}
```
Expected result variant: **codebase-inventory**. Bind codebases from structuredContent.codebases.
Next: Follow nextCursor until null before proposing repository scope.
6. **project_codebase_link** — Only after a human confirms one already-connected repository from the complete inventory.
```json
{
"projectId": "{{projectId}}",
"repositoryId": "{{repositoryId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"projectCodebase": {
"projectId": "prj_fixture_checkout",
"repositoryId": "repo_fixture_throughline",
"linked": true,
"newlyLinked": true
}
}
```
Expected result variant: **codebase-linked**. Bind linked from structuredContent.projectCodebase.linked.
Next: Proceed with the confirmed repository in project scope.
**Done when:** One unambiguous project id is carried forward and any requested rename or repository link is reflected in the structured result.
**Allowed transitions**
- project absent → project created
- project resolved → inspected
- project inspected → renamed
- repository inventory complete → existing codebase linked
**Errors and recovery**
- `PROJECT_ACCESS_DENIED` — The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.
- `VALIDATION_FAILED` — A project name, review mode, cursor, or repository id is invalid. Correct the field from live schema or inventory data and use a new mutation key for changed arguments.
- Repeat project_list before creating after an ambiguous or interrupted attempt.
- Use project_get to recover the canonical project after an idempotent replay.
**Never assume**
- A similar name is the intended project.
- Renaming requires creating another project.
- An unlisted or unconnected repository may be linked.
## Create a brief from Linear issue content
Paste the issue content, or let a separately authorized harness fetch it. Semel does not expose a Linear-fetch tool. Confirm a brief-less project, then create one complete canonical brief without guessing an ID.
Turn user-supplied or connector-authorized issue text into a complete canonical brief in a resolved project.
**Requests you can make**
- “Create a brief from this pasted Linear issue.”
- “Use my authorized Linear connector to draft a brief for ENG-42.”
**Prerequisites**
- Scopes: `brief:read`, `brief:write`
- State: Project id resolved
- State: Issue text pasted or fetched by a separate authorized connector
- Human: Provide issue text or authorize the external Linear connector; Semel has no Linear-fetch tool.
- Human: Explicitly confirm brief creation.
**Ordered steps**
1. **supply-linear-text** — Human action: Provide self-contained issue text or authorize a separate Linear connector to read it.
Next: Map the source into canonical brief sections without inventing missing requirements.
2. **brief_create** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"projectId": "{{projectId}}",
"title": "{{briefTitle}}",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"versionNum": 1
}
}
```
Expected result variant: **brief-created**. Bind briefId from structuredContent.brief.id.
Next: Load the complete persisted aggregate by the returned brief id.
3. **brief_get_full** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"briefId": "{{briefId}}"
}
```
```json
{
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"versionNum": 1
},
"collections": {
"versions": {
"items": [],
"nextCursor": null
},
"decisionHistory": {
"items": [],
"nextCursor": null
},
"findings": {
"items": [],
"nextCursor": null
},
"proposals": {
"items": [],
"nextCursor": null
},
"approvals": {
"items": [],
"nextCursor": null
},
"comments": {
"items": [],
"nextCursor": null
},
"artifacts": {
"items": [],
"nextCursor": null
},
"workOrders": {
"items": [],
"nextCursor": null
},
"reviewSessions": {
"items": [],
"nextCursor": null
},
"shares": {
"items": [],
"nextCursor": null
}
},
"gateNotificationStatus": null
}
```
Expected result variant: **full-brief**. Bind brief from structuredContent.brief.
Next: Show the created brief and call out any source gaps for the human.
**Done when:** The structured result supplies a brief id and brief_get_full confirms the canonical persisted content.
**Allowed transitions**
- source supplied → draft mapped
- draft confirmed → brief created
- brief created → aggregate inspected
**Errors and recovery**
- `PROJECT_ACCESS_DENIED` — The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.
- `VALIDATION_FAILED` — The canonical brief payload rejects a field or value. Use only canonical section keys, preserve the supplied source facts, and validate the complete payload again.
- Retry an identical create with the same key.
- Use a new key only after materially changing the brief payload.
**Never assume**
- Semel can fetch a Linear URL itself.
- Missing issue details may be fabricated.
- Free-form pseudo-sections are canonical brief keys.
## Inspect a brief and its collections
`brief_get_full` returns the canonical content plus the first page of each collection. Continue paginating the needed collection instead of treating the first page as exhaustive.
Find a reachable brief, inspect its aggregate, and page one supported durable collection without inventing response fields.
**Requests you can make**
- “Show me the checkout brief.”
- “Inspect the decision history for this brief.”
**Prerequisites**
- Scopes: `brief:read`
- State: Authenticated principal with project access
- Human: Resolve ambiguous brief matches.
**Ordered steps**
1. **brief_list** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"limit": 50
}
```
```json
{
"briefs": [
{
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"versionNum": 3,
"updatedAt": "2026-09-07T16:00:00.000Z"
}
],
"nextCursor": null
}
```
Expected result variant: **brief-list**. Bind briefId from structuredContent.briefs[0].id.
Next: Select an exact brief or ask the human to disambiguate.
2. **brief_get_full** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"briefId": "{{briefId}}"
}
```
```json
{
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"versionNum": 3
},
"collections": {
"versions": {
"items": [],
"nextCursor": null
},
"decisionHistory": {
"items": [],
"nextCursor": null
},
"findings": {
"items": [],
"nextCursor": null
},
"proposals": {
"items": [],
"nextCursor": null
},
"approvals": {
"items": [],
"nextCursor": null
},
"comments": {
"items": [],
"nextCursor": null
},
"artifacts": {
"items": [],
"nextCursor": null
},
"workOrders": {
"items": [],
"nextCursor": null
},
"reviewSessions": {
"items": [],
"nextCursor": null
},
"shares": {
"items": [],
"nextCursor": null
}
},
"gateNotificationStatus": null
}
```
Expected result variant: **full-brief**. Bind collections from structuredContent.collections.
Next: Read collection summaries/pages from collections rather than invented top-level arrays.
3. **brief_collection_list** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"briefId": "{{briefId}}",
"collection": "decisionHistory",
"limit": 50
}
```
```json
{
"collection": "decisionHistory",
"items": [],
"nextCursor": null
}
```
Expected result variant: **collection-page**. Bind nextCursor from structuredContent.nextCursor.
Next: Repeat with the returned cursor until nextCursor is null.
**Done when:** The requested aggregate is shown and every requested collection page has nextCursor equal to null.
**Allowed transitions**
- brief located → aggregate loaded
- collection page → next page or complete
**Errors and recovery**
- `PROJECT_ACCESS_DENIED` — The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.
- `VALIDATION_FAILED` — The collection name or pagination arguments are invalid. Choose an advertised collection enum and reuse only the opaque returned cursor.
- Restart pagination from no cursor if a cursor is rejected after data changes.
**Never assume**
- Collections are top-level arrays on brief_get_full.
- A single page is the complete collection when nextCursor is non-null.
- Cursors may be constructed locally.
## Add a version by updating a brief
Read the current full content and carry forward every section you want to retain. `brief_update` is full replacement, including arrays, and creates a new immutable version. Resolve `BRIEF_VERSION_CONFLICT` by rereading before proposing a new replacement.
Replace complete brief content with a guarded new version or toggle one checklist row atomically.
**Requests you can make**
- “Add the retry acceptance criterion to this brief.”
- “Check off the API contract QA item.”
**Prerequisites**
- Scopes: `brief:read`, `brief:write`
- State: Current full brief and version number loaded
- Human: Explicitly confirm the complete-content replacement.
**Ordered steps**
1. **brief_get_full** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"briefId": "{{briefId}}"
}
```
```json
{
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
],
"checklist": [
{
"text": "API contract reviewed",
"checked": false
}
]
},
"versionNum": 3
},
"collections": {
"versions": {
"items": [],
"nextCursor": null
},
"decisionHistory": {
"items": [],
"nextCursor": null
},
"findings": {
"items": [],
"nextCursor": null
},
"proposals": {
"items": [],
"nextCursor": null
},
"approvals": {
"items": [],
"nextCursor": null
},
"comments": {
"items": [],
"nextCursor": null
},
"artifacts": {
"items": [],
"nextCursor": null
},
"workOrders": {
"items": [],
"nextCursor": null
},
"reviewSessions": {
"items": [],
"nextCursor": null
},
"shares": {
"items": [],
"nextCursor": null
}
},
"gateNotificationStatus": null
}
```
Expected result variant: **full-brief**. Bind currentContent from structuredContent.brief.content.
Next: Apply the requested edit locally while preserving every untouched key.
2. **brief_update** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"briefId": "{{briefId}}",
"title": "{{briefTitle}}",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
},
{
"id": "AC-02",
"text": "The response identifies the original payment intent."
}
],
"checklist": [
{
"text": "API contract reviewed",
"checked": false
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"ifVersionNum": 3,
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
},
{
"id": "AC-02",
"text": "The response identifies the original payment intent."
}
],
"checklist": [
{
"text": "API contract reviewed",
"checked": false
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"versionNum": 4,
"createdNewVersion": true,
"staledApprovals": 0
}
}
```
Expected result variant: **brief-updated**. Bind versionNum from structuredContent.brief.versionNum.
Next: Inspect createdNewVersion and the returned current version.
3. **brief_checklist_update** — Only when the user requested a single checklist toggle and the exact row text/version are known.
```json
{
"briefId": "{{briefId}}",
"index": 0,
"expectedText": "API contract reviewed",
"checked": true,
"ifVersionNum": 4,
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
},
{
"id": "AC-02",
"text": "The response identifies the original payment intent."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
],
"checklist": [
{
"text": "API contract reviewed",
"checked": true
}
]
},
"versionNum": 5,
"createdNewVersion": true,
"staledApprovals": 0
}
}
```
Expected result variant: **checklist-toggled**. Bind checklistVersionCreated from structuredContent.brief.createdNewVersion.
Next: Use this atomic result instead of replacing the full checklist.
**Done when:** The returned brief reports the intended version/content state and the requested checklist row is correct.
**Allowed transitions**
- current version → replacement prepared
- replacement confirmed → new version or no-change
- known checklist row → atomic toggle
**Errors and recovery**
- `BRIEF_VERSION_CONFLICT` — ifVersionNum is no longer current. Re-read the full brief, reconcile the human change, and submit materially updated arguments with a new mutation key.
- `PROJECT_ACCESS_DENIED` — The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.
- Replay an identical mutation with the same idempotency key.
- Never reuse a key after changing content or version guards.
**Never assume**
- brief_update is a partial patch.
- A checklist tick should overwrite the whole checklist.
- A stale version can be forced through.
## Export a verified brief package
Use the package export for a durable implementation handoff. It is a billable write requiring `brief:write`; bind to the exact current version and consume only the returned artifact resource link.
Create and retrieve the canonical verified package, using Markdown only as an explicitly legacy compatibility export.
**Requests you can make**
- “Export this brief for implementation.”
- “Give me the legacy Markdown export for compatibility.”
**Prerequisites**
- Scopes: `brief:read`, `brief:write`
- State: Brief is ready for implementation handoff
- Human: Explicitly confirm minting the immutable package.
**Ordered steps**
1. **brief_export_package** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"briefId": "{{briefId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"exportId": "example",
"status": "ready",
"filename": "retry-safe-checkout.zip",
"downloadUrl": "https://mcp.semel.ai/brief-exports/exp_fixture_checkout",
"manifestSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"implementationReady": true,
"expiresAt": "2026-09-07T16:00:00.000Z",
"snapshotId": "example",
"contractVersionId": "example"
}
```
Expected result variant: **ready**. Bind downloadUrl from structuredContent.downloadUrl.
Next: Fetch the bearer-authenticated resource before expiresAt and verify the manifest/hash.
2. **download-package** — Protocol action (download_resource): Download the returned resource_link with the same authorized agent context.
Next: Verify content and record expiry rather than treating a URL as permanent.
3. **brief_export_markdown** — Only when the human explicitly needs the legacy Markdown compatibility format.
```json
{
"briefId": "{{briefId}}"
}
```
```json
{
"filename": "retry-safe-checkout.zip",
"resource": {
"uri": "https://mcp.semel.ai/brief-exports/brf_fixture_checkout.md",
"name": "retry-safe-checkout.md",
"mimeType": "text/markdown"
},
"downloadUrl": "example",
"markdown": "example"
}
```
Expected result variant: **legacy-markdown**. Bind legacyResource from structuredContent.resource.
Next: Label the result deprecated and do not treat it as a verified handoff.
**Done when:** A ready, implementationReady package is verified and downloaded, or the explicitly requested legacy export is clearly labelled.
**Allowed transitions**
- brief ready → package ready
- package ready → authenticated download
- legacy request → Markdown compatibility export
**Errors and recovery**
- `PAYLOAD_REJECTED` — The package cannot be verified or is blocked. Stop; resolve the reported brief/package defect and mint a new package rather than falling back silently.
- `PROJECT_ACCESS_DENIED` — The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.
- Repeat an identical package mutation with the same key.
- Mint a new package only after the brief or export request changes.
**Never assume**
- A failed package can be replaced by Markdown without disclosure.
- A download URL never expires.
- Receiving a URL proves its bytes passed verification.
## Originate and observe a review
Choose hosted or local dispatch intent when starting the review. This originates work against a pinned brief; it does not reconfigure the cascade, approve a gate, or grant local execution.
Start the first or a later review pass with an explicit execution choice, observe live dispatch, and cancel only an agent-originated run when requested.
**Requests you can make**
- “Run a hosted review of this brief.”
- “Start another local review pass from the last completed run.”
- “Cancel the review you just started.”
**Prerequisites**
- Scopes: `brief:read`, `review:run`, `review:execute`
- State: Project reviewer configuration completed in the portal
- State: Brief id resolved
- Human: Configure reviewer/provider/model in the portal.
- Human: Confirm the target, execution mode, and spend-bearing start or cancellation.
**Ordered steps**
1. **configure-reviewers** — Human action: Configure the project reviewer cascade and provider/model choices in the Semel portal.
Next: Return to the agent after the portal confirms configuration.
2. **review_start** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"briefId": "{{briefId}}",
"execution": "hosted",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"run": {
"id": "run_fixture_review",
"status": "queued",
"position": 0
},
"cascade": {
"projectId": "prj_fixture_checkout",
"phase": "reviewing"
},
"dispatch": {
"status": "invoking",
"admitted": true,
"softCapWarning": false
}
}
```
Expected result variant: **hosted-start**. Bind runId from structuredContent.run.id.
Next: Poll review_status and respect configless, cap, evidence-wait, or in-flight outcomes.
3. **review_status** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"briefId": "{{briefId}}"
}
```
```json
{
"projectId": "prj_fixture_checkout",
"phase": "complete",
"inFlight": false,
"execution": "hosted",
"awaitingLocalClaim": false,
"steps": [],
"latestRunId": "run_fixture_review",
"latestTerminalRunId": "run_fixture_review",
"blocked": null
}
```
Expected result variant: **review-status**. Bind latestRunId from structuredContent.latestRunId; anchorRunId from structuredContent.latestTerminalRunId.
Next: Use latestTerminalRunId as the anchor for a later pass only when the user asks.
4. **review_new_pass** — Only for a requested later pass anchored to a real terminal run; local execution additionally requires review:execute.
```json
{
"briefId": "{{briefId}}",
"anchorRunId": "{{anchorRunId}}",
"execution": "local",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"run": {
"id": "run_fixture_followup",
"status": "queued",
"position": 0
},
"cascade": {
"projectId": "prj_fixture_checkout",
"phase": "reviewing"
},
"dispatch": {
"status": "awaiting_local_claim",
"admitted": true,
"softCapWarning": false
}
}
```
Expected result variant: **local-start**. Bind newRunId from structuredContent.run.id.
Next: Request the returned local session grant; do not claim without approval.
5. **review_cancel** — Only after explicit confirmation and only for a run this agent originated.
```json
{
"runId": "{{newRunId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"runId": "run_fixture_followup",
"outcome": "cancel_requested",
"status": "queued"
}
```
Expected result variant: **cancel-requested**. Bind cancelOutcome from structuredContent.outcome.
Next: Stop local work and follow the authoritative returned status.
**Done when:** The requested pass has a returned run id and observable status, or cancellation reaches the authoritative returned outcome.
**Allowed transitions**
- configured brief → first pass started
- terminal prior run → later pass started
- agent-originated live run → cancel requested
**Errors and recovery**
- `RUN_ALREADY_TERMINAL` — Cancellation targets a run that already settled. Accept the terminal status and do not retry cancellation.
- `VALIDATION_FAILED` — Review configuration, anchor, or execution request is invalid. Inspect review_status and have the human repair portal configuration or select a valid terminal anchor.
- Use review_status after any ambiguous transport outcome.
- Replay identical start/cancel requests with their original mutation key.
**Never assume**
- Checkpoints or heartbeat configure reviewers.
- A later pass needs no terminal anchor.
- The agent may cancel a human- or other-agent-originated run.
## Select the next review pass or cancel safely
Inspect status before choosing a legal agent action such as a new pass or cancellation. Cascade configuration, destructive clear/restart, and human gate decisions remain in the Semel UI.
Inspect review state and direct the human to the actual portal configuration surface without inventing an MCP configuration API.
**Requests you can make**
- “Change the engineering reviewer model.”
- “Configure this project for a security review.”
**Prerequisites**
- Scopes: `brief:read`, `review:run`
- State: Project and brief resolved
- Human: Select reviewer, provider, model, and configuration in the portal.
**Ordered steps**
1. **review_status** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"briefId": "{{briefId}}"
}
```
```json
{
"projectId": "prj_fixture_checkout",
"phase": "reviewing",
"inFlight": false,
"execution": "hosted",
"awaitingLocalClaim": false,
"steps": [],
"latestRunId": "example",
"latestTerminalRunId": "example",
"blocked": null
}
```
Expected result variant: **review-status**. Bind phase from structuredContent.phase.
Next: Explain the current state and the exact human portal action.
2. **portal-review-configuration** — Human action: Open project review settings and select/update the reviewer, provider, model, and supported configuration.
Next: Wait for the portal to report a saved configuration before starting a review.
**Done when:** The human confirms the actual portal configuration is saved and a fresh review_status reflects an eligible state.
**Allowed transitions**
- unconfigured → human configuration required
- human configuration saved → eligible for review start
**Errors and recovery**
- `AUTHORIZATION_SCOPE_MISSING` — The current principal cannot inspect review state. Have an operator grant the minimum read/run scope or inspect the state directly in the portal.
- Re-read review_status after the human changes settings.
**Never assume**
- Heartbeat, sync, or checkpoints update reviewer configuration.
- A nonexistent reviewer configuration tool may be called.
- The agent may choose provider consent or BYOK secrets for the human.
## Drive one local execution session
Tell the human up front that each cascade step needs its own approved execution grant. Request a grant, wait for human approval, claim one eligible step, fetch its exact pinned skill, heartbeat and checkpoint under the current fence, then submit or release.
Follow a human-approved local execution grant through pinned artifact retrieval, fenced progress, sync/heartbeat, submit, or an explicit pre-submit handoff.
**Requests you can make**
- “Run this eligible review session in my local harness.”
- “Hand this local review session to another harness.”
- “Complete and submit the current local engineering review.”
**Prerequisites**
- Scopes: `brief:read`, `review:execute`
- State: Eligible local review session exists
- State: No local execution is currently assumed
- Human: Approve the execution grant returned by Semel.
- Human: Choose completion versus pre-submit handoff.
**Ordered steps**
1. **review_execution_grant_request** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"reviewSessionId": "{{reviewSessionId}}"
}
```
```json
{
"status": "approval_required",
"approvalUri": "https://mcp.semel.ai/review-execution/approve/xgr_fixture_engineering",
"pollHandle": "poll_fixture_engineering",
"controlBlock": {
"state": {
"sessionState": "awaiting_executor",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_claim",
"preconditions": [
"An operator-issued grant already exists; any authorized claimant may claim it."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": true,
"uri": "https://mcp.semel.ai/review-execution/approve/xgr_fixture_engineering"
}
}
}
```
Expected result variant: **approval-required**. Bind approvalUri from structuredContent.approvalUri.
Next: Show approvalUri to the human and poll only as instructed.
2. **approve-execution-grant** — Human action: A verified human opens the returned approval URI and approves the exact session/harness intent.
Next: Resume only after grant_request returns ready with a real grant id.
3. **review_execution_claim** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"grantId": "{{grantId}}",
"reviewSessionId": "{{reviewSessionId}}",
"supportedProtocolVersions": [
"{{protocolVersion}}"
],
"harnessDescriptor": {
"harness": "codex",
"harnessVersion": "1",
"agent": "codex",
"model": "gpt-5"
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"bundle": {
"protocolVersion": "1.1",
"instructions": "Semel external-execution protocol v1: after review_execution_claim pins this bundle, the active skill is exactly one at a time (see the frozen skill order). Fetch the active reviewer lens and its matching shared framing with review_execution_skill_get. Use review_execution_checkpoint_append for bounded semantic milestones, review_question_open/review_question_answer for durable questions, review_execution_sync to discover recorded answers/cancellation/handoff without a persistent session, review_execution_heartbeat to renew the current fenced epoch, and review_execution_submit to finalize against this exact pinned brief base. review_execution_status is always callable and is the documented fail-safe whenever local context is lost. Raw chain-of-thought, source dumps, and hidden reasoning are never accepted fields.",
"schemaHashes": {
"review_execution_grant_request": "e52e7b64d1f1249e1e92c230fe31d7ac8aa504b9e00b154669269ee819d0ce08",
"review_execution_claim": "a124f54e50215258b0b669806e5278f5fcf4a9a1dd9c5501f2cff7ac99345ed7",
"review_execution_skill_get": "fbc91868b45920f159c6e65eccc70fe8d2a5bd107dbece3cceb4f8bf7edaf12c",
"review_execution_checkpoint_append": "023d0a5c99799ffd1734b9ff5c37da0391ab3a80beba895522ee824a171058ad",
"review_question_open": "2304a9fc9feed0e54f96202864f313485028d63f11d9c5bea41bbd8af6ceac2b",
"review_question_answer": "cd82c71b9090d96c9b972b89d22baac83167073503cf06d0efd0eada62e2ba8b",
"review_question_answer_supersede": "8ca9bcface0a212deb4c6595d162fffb06089c278177234ea995228e85277904",
"review_execution_sync": "e3228cdf437c31d501474f2d688e25968a40bce0f1a620000cb8bb0840003907",
"review_execution_heartbeat": "b9ed5d743c1a9f668eb4ba3a4cc57552fc625fe115175906b4999fb3afbab4f3",
"review_execution_release": "c22b0fc25aa734487b075da1d665b75c9b645dbfbaca7b673863d942fbb58fe5",
"review_execution_submit": "80e9035b5dd37421bbdb6535042b7c2501bdcfd17e42070beb7a83ff1af3235f",
"review_execution_status": "1b27dee7128f1cec0c9c3bab65ea2368b58427a60728a156a0260e84f0c5edc4",
"project_context_sources_list": "662b917601c66ad54d599da31eba19a3bfa149f4b9ae36d0761a8e920206af35",
"project_context_search": "463c91ced23d7d9578b00661eed0e9bc14648f3c42fe70bee3a700ab4faeb0f3",
"project_context_evidence_get": "7c491de307d0624711916c3ba22c3a98635554e4b3654fba07700dce2d5965a0"
},
"session": {
"reviewSessionId": "rs_fixture_engineering",
"runId": "run_fixture_review",
"projectId": "prj_fixture_checkout",
"briefId": "brf_fixture_checkout",
"reviewMode": "direct",
"reviewerSet": [
"engineering"
],
"cascadeStepId": "step_fixture_engineering"
},
"briefBase": {
"versionId": "bv_fixture_checkout_v3",
"versionNum": 3,
"sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc"
},
"skills": [
{
"role": "engineering",
"version": "1",
"sha256": "182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7",
"framingHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
},
{
"role": "reviewer-protocol-framing",
"version": "1",
"sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"framingHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
}
],
"evidencePolicy": {},
"requiredCheckpoints": [
"skill_start",
"evidence_readiness_change",
"question_wait_enter",
"question_wait_exit",
"validation_start",
"validation_result",
"submit"
],
"limits": {
"checkpointMaxBytes": 65536,
"summaryMaxBytes": 8192,
"sessionEventBudgetBytes": 10485760
}
},
"canonicalBundleSha256": "c45cacf945339d19f0d3f1f4a7e7977071f9555780cdd79b0ce1768decdfbd90",
"envelope": {
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"heartbeatRecommendedSeconds": 30,
"harnessDescriptor": {
"harness": "codex",
"harnessVersion": "1",
"agent": "codex",
"model": "gpt-5"
}
},
"activeSkill": {
"role": "engineering",
"cursor": "sync_fixture_next"
},
"controlBlock": {
"state": {
"sessionState": "claimed",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **claimed**. Bind executionId from structuredContent.envelope.executionId; canonicalBundleSha256 from structuredContent.canonicalBundleSha256.
Next: Persist executionId, fenceGeneration, bundle hash, lease guidance, and activeSkill from structuredContent.
4. **review_execution_skill_get** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"role": "engineering"
}
```
```json
{
"artifact": {
"role": "engineering",
"version": "1",
"sha256": "182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7",
"framingHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"contentType": "text/markdown",
"bytes": "# Engineering review\n\nValidate the brief against the repository evidence."
}
}
```
Expected result variant: **active-skill**. Bind skillSha256 from structuredContent.artifact.sha256.
Next: Verify exact pinned hash/framing and execute only the active skill bytes.
5. **review_execution_checkpoint_append** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"seq": 1,
"activeSkillId": "engineering",
"milestoneName": "skill_start",
"safeSummary": "Started the pinned engineering skill.",
"receipt": {
"skillRole": "engineering",
"skillSha256": "{{skillSha256}}"
},
"clientObservedAt": "2026-09-07T16:00:00.000Z",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"accepted": true,
"seq": 1,
"highWaterMark": 1,
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"coalesce": false,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 1,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **checkpoint-accepted**. Bind checkpoint1HighWaterMark from structuredContent.highWaterMark.
Next: Inspect evidence readiness before drawing conclusions.
6. **review_execution_checkpoint_append** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"seq": 2,
"activeSkillId": "engineering",
"milestoneName": "evidence_readiness_change",
"safeSummary": "Required repository evidence is ready.",
"receipt": {
"evidenceReady": true
},
"clientObservedAt": "2026-09-07T16:00:00.000Z",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"accepted": true,
"seq": 2,
"highWaterMark": 2,
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"coalesce": false,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 2,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **checkpoint-accepted**. Bind checkpoint2HighWaterMark from structuredContent.highWaterMark.
Next: Begin validation against the pinned brief and evidence.
7. **review_execution_checkpoint_append** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"seq": 3,
"activeSkillId": "engineering",
"milestoneName": "validation_start",
"safeSummary": "Running the bounded validation pass.",
"receipt": {
"validationStarted": true
},
"clientObservedAt": "2026-09-07T16:00:00.000Z",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"accepted": true,
"seq": 3,
"highWaterMark": 3,
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"coalesce": false,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 3,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **checkpoint-accepted**. Bind checkpoint3HighWaterMark from structuredContent.highWaterMark.
Next: Run the reviewer checks and retain only bounded result facts.
8. **review_execution_checkpoint_append** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"seq": 4,
"activeSkillId": "engineering",
"milestoneName": "validation_result",
"safeSummary": "Validation completed with no blocking findings.",
"receipt": {
"validationPassed": true,
"findingCount": 0
},
"clientObservedAt": "2026-09-07T16:00:00.000Z",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"accepted": true,
"seq": 4,
"highWaterMark": 4,
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"coalesce": false,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 4,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **checkpoint-accepted**. Bind checkpoint4HighWaterMark from structuredContent.highWaterMark.
Next: Prepare the schema-valid final result.
9. **review_execution_checkpoint_append** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"seq": 5,
"activeSkillId": "engineering",
"milestoneName": "submit",
"safeSummary": "Final result is ready for submission.",
"receipt": {
"submissionRevision": 1
},
"clientObservedAt": "2026-09-07T16:00:00.000Z",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"accepted": true,
"seq": 5,
"highWaterMark": 5,
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"coalesce": false,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **checkpoint-accepted**. Bind checkpoint5HighWaterMark from structuredContent.highWaterMark.
Next: Sync once more, then submit only if the control block permits it.
10. **review_execution_heartbeat** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"heartbeatRecommendedSeconds": 30,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **lease-renewed**. Bind leaseExpiresAt from structuredContent.leaseExpiresAt.
Next: Schedule the next heartbeat from heartbeatRecommendedSeconds.
11. **review_execution_sync** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"cursor": "{{syncCursor}}",
"fenceGeneration": 1
}
```
```json
{
"answers": [],
"cancellationRequested": false,
"serverCommands": [],
"handoff": {
"occurred": false,
"currentFenceGeneration": 1
},
"lease": {
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"current": true
},
"nextCursor": "sync_fixture_after_checkpoint",
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **sync**. Bind nextCursor from structuredContent.nextCursor.
Next: Apply answers, cancellation, handoff, lease, and server commands before more work.
12. **review_execution_status** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}"
}
```
```json
{
"execution": {
"executionId": "xex_fixture_engineering",
"reviewSessionId": "rs_fixture_engineering",
"state": "running",
"currentFenceGeneration": 1,
"activeSkillCursor": null
},
"epoch": {
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"heartbeatAt": "2026-09-07T16:00:30.000Z",
"claimedByPrincipal": "example",
"startedAt": "2026-09-07T16:00:00.000Z",
"endedAt": null
},
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"certificateReference": null,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **execution-status**. Bind controlBlock from structuredContent.controlBlock.
Next: Follow allowedNextOperations and the authoritative fence/lease/question counts.
13. **review_execution_release** — Alternative terminal branch only: invoke before submit when the human chooses relinquish/handoff; skip submit after release.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"reason": "handoff",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"released": true,
"controlBlock": {
"state": {
"sessionState": "handed_off",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_claim",
"preconditions": [
"Explicitly released for handoff — claimable by the next authorized harness."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **released**. Bind released from structuredContent.released.
Next: Stop; the next harness must claim a fresh epoch and repeat local evidence confirmation.
14. **review_execution_submit** — Completion branch only: invoke when controlBlock permits submit, no question is open, and release was not chosen.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"submissionRevision": 1,
"canonicalBundleSha256": "{{canonicalBundleSha256}}",
"result": {
"reviewer": "engineering",
"findings": [],
"questions": [],
"summaryOfChanges": "Validated retry-safe payment intent reuse."
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"status": "completed",
"outcome": "no_change",
"briefVersionId": null,
"briefVersionNum": null,
"certificateReference": {
"certificateId": "example",
"state": "pending"
},
"controlBlock": {
"state": {
"sessionState": "completed",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": true,
"unmetRequirements": [],
"certificateState": "pending"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
},
"cascade": {
"status": "awaiting_local_claim",
"runId": "run_fixture_review",
"reviewSessionId": "rs_fixture_engineering",
"cascadeStepId": "example",
"controlBlock": {
"state": {
"sessionState": "awaiting_local_claim",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_grant_request",
"preconditions": [
"A human must approve the execution grant before a harness can claim this run."
]
},
{
"operation": "review_execution_claim",
"preconditions": [
"A human must approve the execution grant before a harness can claim this run."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Expected result variant: **completed**. Bind cascade from structuredContent.cascade.
Next: Follow cascade.status; request the next grant only for awaiting_local_claim and never wait for certificate signing.
**Done when:** The session is either explicitly released before submit or returns a completed submit response whose cascade instruction has been followed.
**Allowed transitions**
- eligible session → approval required or ready
- ready grant → claimed epoch
- claimed → running/checkpointed
- running → released handoff or terminal submission
- completed → cascade-directed next action
**Errors and recovery**
- `STALE_FENCE` — The supplied fence generation is no longer current. Stop writes, call status/sync, and accept the authoritative handoff or recovery state.
- `QUESTION_OPEN` — Submit is blocked by a durable unanswered question. Sync and wait for a real attributed answer; never delete or fabricate the question.
- `PROTOCOL_VERSION_UNSUPPORTED` — No claimed protocol version is supported. Stop and update the harness integration before requesting a new claim.
- Call review_execution_status whenever local context is lost.
- Replay identical mutations with the original key; changed payloads require new keys.
- Do not upload buffered receipts if another principal took over or the session was cancelled.
**Never assume**
- The agent can approve or mint its own grant.
- Fence generations may be incremented locally.
- Release is required after terminal submit.
- Certificate signing must finish before exit.
- Upcoming skill bytes may be fetched early.
## Open, answer, and supersede a durable question
Open a question only for a real build-shaping fork. A human supplies the accepted answer; the agent records that answer or an explicit superseding answer. Notification failure never erases the canonical inbox record.
Persist an owner decision before displaying it, accept only a real human answer, and recover correctly from conflict or operator supersession.
**Requests you can make**
- “Ask me which database migration strategy to use.”
- “Record my answer and resume the review.”
- “Correct my earlier answer to use an online migration.”
**Prerequisites**
- Scopes: `brief:read`, `review:execute`
- State: Claimed execution is running or waiting_input
- State: Current fence is known
- Human: Provide the answer; only a verified operator may supersede an accepted answer.
**Ordered steps**
1. **review_execution_checkpoint_append** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"seq": 6,
"activeSkillId": "engineering",
"milestoneName": "question_wait_enter",
"safeSummary": "Preparing to wait for the owner on a durable migration question.",
"receipt": {
"clientQuestionId": "recipe-question-open-v1"
},
"clientObservedAt": "2026-09-07T16:00:00.000Z",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"accepted": true,
"seq": 6,
"highWaterMark": 6,
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"coalesce": false,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 6,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **checkpoint-accepted**. Bind checkpoint6HighWaterMark from structuredContent.highWaterMark.
Next: Open the durable question before displaying it.
2. **review_question_open** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"clientQuestionId": "{{clientQuestionId}}",
"text": "Which migration strategy should implementation use?",
"reviewerRole": "engineering",
"section": "technicalSolution",
"options": [
"Online expand/contract",
"Scheduled maintenance"
],
"responseDeadlineHint": "2026-09-08T16:00:00.000Z",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"questionId": "q_fixture_database",
"deduped": false,
"responseDeadline": "2026-09-08T16:00:00.000Z",
"deliveryState": [],
"controlBlock": {
"state": {
"sessionState": "waiting_input",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_question_answer",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 6,
"openQuestionCount": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **question-opened**. Bind questionId from structuredContent.questionId.
Next: Display the durable question and its options only after this call succeeds.
3. **answer-question** — Human action: The human chooses or writes the answer; preserve attribution and do not infer it.
Next: Submit exactly the answer the human provided.
4. **review_question_answer** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"questionId": "{{questionId}}",
"answerText": "Use online expand/contract.",
"transmittingAgent": "codex",
"humanAttribution": {
"claimedName": "Repository owner"
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"outcome": "accepted",
"answerId": "example",
"questionId": "q_fixture_database",
"activeAnswer": {
"answerId": "example",
"channel": "local_harness",
"answerText": "Use online expand/contract.",
"answeredAt": "2026-09-07T16:03:00.000Z"
},
"roundResumed": true,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 6,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **accepted-answer**. Bind activeAnswer from structuredContent.activeAnswer.
Next: Resume dependent work only when this answer is accepted or matches the existing winner.
5. **review_execution_checkpoint_append** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"seq": 7,
"activeSkillId": "engineering",
"milestoneName": "question_wait_exit",
"safeSummary": "The owner answer was accepted and dependent work may resume.",
"receipt": {
"questionId": "{{questionId}}",
"answerAccepted": true
},
"clientObservedAt": "2026-09-07T16:00:00.000Z",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"accepted": true,
"seq": 7,
"highWaterMark": 7,
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"coalesce": false,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 7,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **checkpoint-accepted**. Bind checkpoint7HighWaterMark from structuredContent.highWaterMark.
Next: Resume work from the accepted answer or follow an operator correction.
6. **review_question_answer_supersede** — Only a verified human operator may invoke this correction path after an accepted answer.
```json
{
"executionId": "{{executionId}}",
"questionId": "{{questionId}}",
"correctedAnswerText": "Use an online expand/contract migration with a compatibility window.",
"reason": "Owner clarified rollback requirements.",
"idempotencyKey": "{{idempotencyKey}}"
}
```
```json
{
"outcome": "accepted",
"newAnswerId": "ans_fixture_corrected",
"supersededAnswerId": "ans_fixture_original",
"recoveryCursor": {
"invalidatedFromSeq": 1,
"activeSkillCursor": null
},
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 7,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **superseded**. Bind recoveryCursor from structuredContent.recoveryCursor.
Next: Rework from recoveryCursor before final submission.
7. **review_execution_sync** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}",
"cursor": "{{syncCursor}}",
"fenceGeneration": 1
}
```
```json
{
"answers": [],
"cancellationRequested": false,
"serverCommands": [],
"handoff": {
"occurred": false,
"currentFenceGeneration": 1
},
"lease": {
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"current": false
},
"nextCursor": null,
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 7,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **sync**. Bind answers from structuredContent.answers.
Next: Apply the winning answer and any recovery cursor before continuing.
**Done when:** Every opened question has an accepted human answer and any supersession recovery work is complete.
**Allowed transitions**
- running → waiting_input
- waiting_input → running after final answer
- accepted answer → superseded answer with recovery cursor
**Errors and recovery**
- `QUESTION_OPEN` — A terminal submit is attempted while a question remains unanswered. Wait, sync, and submit the actual human answer before retrying finalization.
- `CONFLICTING_IDEMPOTENCY_REPLAY` — The same mutation key is reused with changed answer text. Keep the old key only for identical replay; use a new key for the changed human answer.
- On answer conflict, use activeAnswer as the winner and ask the operator whether correction is needed.
- After supersede, discard dependent local conclusions from recoveryCursor onward.
**Never assume**
- The agent may answer its own owner question.
- Displaying a question locally makes it durable.
- A second ordinary answer silently replaces the winner.
## Use bounded local evidence
List permitted sources, search within the project boundary, then fetch only the exact cited evidence. Keep raw repository dumps, secrets, and chain-of-thought out of checkpoints and submissions.
Inventory indexed sources, search selected opaque source ids, and redeem one opaque citation handle for bounded evidence.
**Requests you can make**
- “Find where retry idempotency is implemented.”
- “Show the evidence behind that repository citation.”
**Prerequisites**
- Scopes: `brief:read`, `review:execute`
- State: Project id resolved
- State: Project context access granted
- Human: Confirm any later local-worktree binding separately.
**Ordered steps**
1. **project_context_sources_list** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"projectId": "{{projectId}}",
"limit": 50
}
```
```json
{
"sources": [
{
"sourceId": "src_fixture_repository",
"kind": "repository",
"label": "throughlineos repository",
"scope": {
"kind": "project",
"id": "prj_fixture_checkout"
},
"status": "ready",
"freshness": {
"asOf": "2026-09-07T16:00:00.000Z",
"coverage": "full"
},
"provenance": "semel_indexed"
}
],
"nextCursor": null
}
```
Expected result variant: **source-list**. Bind sourceId from structuredContent.sources[0].sourceId.
Next: Follow nextCursor to completion and distinguish ready, stale, degraded, and unavailable sources.
2. **project_context_search** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"projectId": "{{projectId}}",
"sourceIds": [
"{{sourceId}}"
],
"query": "payment retry idempotency",
"limit": 20
}
```
```json
{
"results": [
{
"citation": {
"citationHandle": "ctx1.repository.fixture",
"sourceId": "src_fixture_repository",
"provenance": "semel_indexed",
"route": "exact",
"score": 0.93,
"kind": "repository",
"repository": {
"owner": "throughline",
"name": "throughlineos"
},
"revision": {
"commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"revisionId": "rev_fixture_checkout"
},
"path": "services/api/src/checkout.ts",
"startLine": 42,
"endLine": 58
}
}
],
"searchedSources": [
{
"sourceId": "src_fixture_repository",
"route": "exact",
"resultCount": 1,
"abstained": false
}
]
}
```
Expected result variant: **search-results**. Bind citationHandle from structuredContent.results[0].citation.citationHandle.
Next: Preserve the returned citationHandle exactly; inspect abstention metadata when no result exists.
3. **project_context_evidence_get** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"projectId": "{{projectId}}",
"citationHandle": "{{citationHandle}}"
}
```
```json
{
"citation": {
"citationHandle": "ctx1.repository.fixture",
"sourceId": "src_fixture_repository",
"provenance": "semel_indexed",
"route": "exact",
"score": 0,
"kind": "repository",
"repository": {
"owner": "throughline",
"name": "throughlineos"
},
"revision": {
"commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"revisionId": "rev_fixture_checkout"
},
"path": "services/api/src/checkout.ts",
"startLine": 42,
"endLine": 58
},
"excerpt": "The checkout handler reuses the payment intent for a repeated idempotency key.",
"truncated": false
}
```
Expected result variant: **bounded-evidence**. Bind excerpt from structuredContent.excerpt.
Next: Cite the returned provenance/revision/path and disclose truncated when true.
**Done when:** The answer cites a server-resolved handle with provenance and truncation disclosed, or accurately reports no indexed match/abstention.
**Allowed transitions**
- source inventory → selected sources
- selected sources → metadata search results
- citation handle → bounded excerpt
**Errors and recovery**
- `CONTEXT_UNAVAILABLE` — A selected source or citation cannot currently be resolved. Report its freshness/status and ask whether to wait or begin separately confirmed local evidence discovery.
- `PROJECT_ACCESS_DENIED` — The principal cannot reach the resolved project. Stop and have an operator correct the project allowlist; never select another project silently.
- Refresh source inventory after stale handles or index changes.
- Treat no match and an abstaining retrieval route as different outcomes.
**Never assume**
- Repository citations may be fabricated.
- A no-result response proves absence when a source abstained.
- Opaque source ids or citation handles may be edited.
## Connect an unattended agent
A workspace owner creates the scoped, show-once named token and places it in an environment or native secret reference. The agent proves read access without printing the value and cannot mint, widen, or rotate its own credential.
Have a human create and store a least-privilege named token, then prove it with a permitted read while preserving all human gates.
**Requests you can make**
- “Set up this agent to read Semel unattended.”
- “Verify the service token can list its allowed projects.”
**Prerequisites**
- Scopes: `brief:read`
- State: Human can access Agent access settings
- State: Harness supports protected secret configuration
- Human: Create the named token and place it in the harness secret store.
**Ordered steps**
1. **create-named-token** — Human action: Create a least-privilege named token in Agent access; never paste it into chat, docs URLs, or example files.
Next: Store it using the harness-supported secret or environment mechanism.
2. **configure-named-token** — Protocol action (configure_credential): Configure the token in protected harness storage.
Next: Reconnect and authenticate without printing the credential.
3. **project_list** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{}
```
```json
{
"projects": []
}
```
Expected result variant: **project-list**. Bind projects from structuredContent.projects.
Next: Confirm only expected projects are visible and retain human gates for mutations.
**Done when:** A live permitted read succeeds with the intended project visibility and the token never appears in generated content.
**Allowed transitions**
- human token creation → protected configuration
- configured credential → authenticated permitted read
**Errors and recovery**
- `AUTHENTICATION_REQUIRED` — The live MCP request has no valid bearer credential. Reauthenticate through the configured harness and retry the read or mutation.
- `AUTHORIZATION_SCOPE_MISSING` — The credential lacks a scope required by the selected operation. Stop and ask the human to issue a least-privilege grant containing the named scope.
- Have the human rotate a leaked or unusable token in the portal.
- Re-run tools/list and the permitted read after credential replacement.
**Never assume**
- A named token is delegated browser OAuth.
- Unattended execution bypasses explicit confirmation or human judgment gates.
- Secrets may be persisted in recipe/example files.
## Revoke and rotate access
A human mints and installs a replacement credential, verifies it, and revokes the old grant or token. The agent can observe the resulting failure and resume after reauthorization; it cannot perform credential administration.
Keep credential administration human-owned, observe revocation as authentication failure, and restore access through protected harness configuration.
**Requests you can make**
- “Revoke this agent connection.”
- “Rotate the named token and reconnect the harness.”
**Prerequisites**
- Scopes: none
- State: Existing agent credential or Connected apps entry
- Human: Revoke or rotate in Connected apps or Agent access.
**Ordered steps**
1. **revoke-in-portal** — Human action: Revoke the Connected apps entry or rotate the named token in the Semel portal.
Next: Expect the old credential to fail authentication.
2. **observe-revocation** — Protocol action (authenticate): Attempt a fresh authenticated initialization with the old credential and classify its terminal auth failure.
Next: Do not retry a terminal revoked credential indefinitely.
3. **supply-rotated-credential** — Human action: Create the replacement credential and place it directly in protected harness configuration.
Next: Never send the credential through the conversation.
4. **configure-rotated-credential** — Protocol action (configure_credential): Replace the harness credential without writing it into docs or repository files.
Next: Reconnect, authenticate, and verify live capabilities.
5. **verify-rotated-tools** — Protocol action (tools_list): Read tools/list with the replacement credential.
Next: Confirm the required capability names and expected least-privilege scope.
**Done when:** The old credential is rejected and the human-controlled replacement authenticates with the expected capabilities.
**Allowed transitions**
- active credential → revoked
- revoked → authentication failure
- replacement configured → authenticated
**Errors and recovery**
- `AUTHENTICATION_REQUIRED` — The old credential is revoked or expired. Stop retrying it and wait for the human-managed replacement.
- Distinguish a transient provider/network failure from terminal credential rejection before asking for rotation.
**Never assume**
- Credential revocation is an MCP admin tool.
- The agent may rotate or revoke its own authority.
- A transient outage requires deleting credentials.
## Recover a stale or interrupted session
Read `review_execution_status`, then synchronize before any mutation. Never recreate the session. An expired lease or stale fence requires a new legal claim path; a sequence gap requires the exact next sequence; a terminal or cancelled run accepts no further mutation.
Discard stale local assumptions, recover the authoritative execution/epoch state, and follow only an allowed next operation.
**Requests you can make**
- “Resume this local review after the agent restarted.”
- “Recover the session after its lease expired.”
**Prerequisites**
- Scopes: `brief:read`, `review:execute`
- State: A reviewSessionId or executionId is known
- State: Local execution state may be stale
- Human: Approve a new recovery grant when the server requires one.
- Human: Confirm local evidence again after cross-harness handoff.
**Ordered steps**
1. **clear-stale-local-state** — Protocol action (clear_stale_state): Mark cached fence, lease, question, and allowed-operation assumptions untrusted.
Next: Call status with one real accepted identifier variant.
2. **review_execution_status** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"reviewSessionId": "{{reviewSessionId}}"
}
```
```json
{
"execution": {
"executionId": "xex_fixture_engineering",
"reviewSessionId": "rs_fixture_engineering",
"state": "running",
"currentFenceGeneration": 1,
"activeSkillCursor": null
},
"epoch": {
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"heartbeatAt": "2026-09-07T16:00:30.000Z",
"claimedByPrincipal": "example",
"startedAt": "2026-09-07T16:00:00.000Z",
"endedAt": null
},
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"certificateReference": null,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **execution-status**. Bind epoch from structuredContent.epoch; executionId from structuredContent.execution.executionId.
Next: Inspect controlBlock, current epoch/lease, pending questions, and allowedNextOperations.
3. **review_execution_sync** — When the preceding step succeeds and this call is allowed by the current server state.
```json
{
"executionId": "{{executionId}}"
}
```
```json
{
"answers": [],
"cancellationRequested": false,
"serverCommands": [],
"handoff": {
"occurred": false,
"currentFenceGeneration": 1
},
"lease": {
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"current": true
},
"nextCursor": null,
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Expected result variant: **sync**. Bind handoff from structuredContent.handoff.
Next: Accept cancellation/takeover, or follow the server-provided recovery/grant path.
**Done when:** The harness either resumes under the server-confirmed current epoch or stops with the exact operator/recovery action returned by controlBlock.
**Allowed transitions**
- unknown local state → authoritative status
- current epoch → sync/resume
- expired or superseded epoch → operator recovery or stop
**Errors and recovery**
- `LEASE_EXPIRED` — The cached epoch no longer holds a live lease. Request the server-directed same-principal recovery path; never extend or reclaim it locally.
- `CANCELLED` — The server reports the session was cancelled. Stop and discard buffered writes; do not submit or reclaim.
- `STALE_FENCE` — Another epoch superseded the cached fence. Accept takeover/handoff and require a fresh authorized claim before any write.
- Use reviewSessionId-only status when executionId was lost.
- Repeat local evidence confirmation after every cross-harness handoff.
**Never assume**
- Fence generations may be self-incremented.
- A stale session should create another review run.
- A cancelled or taken-over session may still accept buffered submit.
- A blind reclaim is safe.
Canonical page: https://docs.semel.ai/recipes