# Tool reference
Every customer-visible Semel MCP tool — purpose, required scopes, idempotency, common errors, and related tools — generated from the live operation registry.
This reference is generated from the server’s operation registry. Treat the live MCP `tools/list` result as the authority for the current session; the page explains the same inputs, outputs, scopes, state assumptions, idempotency rules, risks, errors, and related operations in a browsable form.
## MCP tools
### brief_checklist_update
Toggle a single QA-checklist row on a brief on or off, without rewriting the rest of the brief. Use to tick off or clear one acceptance check as work is verified.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `brief:write`
- Confirmation: implicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `index` — integer; required; minimum 0. Zero-based QA checklist item position, guarded by expectedText against reorder races. Minimum accepted length or value is 0. The value must be an integer.
- `expectedText` — string; required; minimum length 1; maximum length 262144. Expected current checklist text at index; a mismatch fails instead of updating the wrong row. Accepted length or value is 1 through 262144, inclusive.
- `checked` — boolean; required. Whether this QA checklist item is currently complete.
- `ifVersionNum` — integer; optional. Optional optimistic precondition using the current brief contract version number. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"description": "Zero-based QA checklist item position, guarded by expectedText against reorder races. Minimum accepted length or value is 0. The value must be an integer."
},
"expectedText": {
"type": "string",
"minLength": 1,
"maxLength": 262144,
"description": "Expected current checklist text at index; a mismatch fails instead of updating the wrong row. Accepted length or value is 1 through 262144, inclusive."
},
"checked": {
"type": "boolean",
"description": "Whether this QA checklist item is currently complete."
},
"ifVersionNum": {
"type": "integer",
"description": "Optional optimistic precondition using the current brief contract version number. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"index",
"expectedText",
"checked",
"briefId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"index": 0,
"expectedText": "API contract reviewed",
"checked": true,
"ifVersionNum": 4,
"idempotencyKey": "recipe-brief-checklist-update-v1"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"index": 0,
"expectedText": "API contract reviewed",
"checked": true,
"ifVersionNum": 4,
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `brief` — object; required. Current brief record returned by the operation.
- `brief.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `brief.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `brief.title` — string; required. Human-readable title displayed in Semel.
- `brief.state` — "drafting" | "in_review" | "baselined" | "in_development" | "checked" | "superseded" | "closed"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "drafting", "in_review", "baselined", "in_development", "checked", "superseded", "closed".
- `brief.currentVersionHash` — string | null; required. Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available.
- `brief.content` — object; required. Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
- `brief.content{key}` — JSON value; optional.
- `brief.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `brief.createdNewVersion` — boolean; required. Whether the write changed canonical content and minted a new immutable brief version.
- `brief.staledApprovals` — integer; required. Number of prior approval rows made stale by this content change. The value must be an integer.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"brief": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"state": {
"type": "string",
"enum": [
"drafting",
"in_review",
"baselined",
"in_development",
"checked",
"superseded",
"closed"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"drafting\", \"in_review\", \"baselined\", \"in_development\", \"checked\", \"superseded\", \"closed\"."
},
"currentVersionHash": {
"type": [
"string",
"null"
],
"description": "Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available."
},
"content": {
"type": "object",
"additionalProperties": {},
"description": "Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
},
"createdNewVersion": {
"type": "boolean",
"description": "Whether the write changed canonical content and minted a new immutable brief version."
},
"staledApprovals": {
"type": "integer",
"description": "Number of prior approval rows made stale by this content change. The value must be an integer."
}
},
"required": [
"id",
"projectId",
"title",
"state",
"currentVersionHash",
"content",
"versionNum",
"createdNewVersion",
"staledApprovals"
],
"additionalProperties": false,
"description": "Current brief record returned by the operation."
}
},
"required": [
"brief"
],
"additionalProperties": false
}
```
**Example structured result (checklist-toggled)**
```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
}
}
```
Bindings: checklistVersionCreated from structuredContent.brief.createdNewVersion.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}"
}
],
"structuredContent": {
"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
}
}
}
```
Next permitted action: Use this atomic result instead of replacing the full checklist.
**Example requests**
- “/semel check off the third QA item on the checkout brief”
- “/semel mark the login QA check as done”
Errors: `PROJECT_ACCESS_DENIED`, `BRIEF_VERSION_CONFLICT`.
Related operations: `brief_update`, `brief_get_full`.
---
### brief_collection_list
Page through one durable brief collection (versions, decisionHistory, proposals, …) by keyset cursor. Use to walk a collection beyond the first page that brief_get_full returns.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
- `collection` — "versions" | "decisionHistory" | "findings" | "proposals" | "approvals" | "comments" | "artifacts" | "workOrders" | "reviewSessions" | "shares"; required. Durable collection to page within this brief. Use one of the advertised collection keys; the result contains only that collection.
- `cursor` — string; optional; minimum length 1. Opaque keyset cursor returned as nextCursor by the preceding page for this same brief and collection. Omit to read the first page.
- `limit` — integer; optional; minimum 1; maximum 200. Maximum records to return, as an integer from 1 through 200. Omit to use the server default.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
},
"collection": {
"type": "string",
"enum": [
"versions",
"decisionHistory",
"findings",
"proposals",
"approvals",
"comments",
"artifacts",
"workOrders",
"reviewSessions",
"shares"
],
"description": "Durable collection to page within this brief. Use one of the advertised collection keys; the result contains only that collection."
},
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque keyset cursor returned as nextCursor by the preceding page for this same brief and collection. Omit to read the first page."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Maximum records to return, as an integer from 1 through 200. Omit to use the server default."
}
},
"required": [
"briefId",
"collection"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"collection": "decisionHistory",
"limit": 50
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"collection": "decisionHistory",
"limit": 50
}
```
**Returns**
- `collection` — "versions" | "decisionHistory" | "findings" | "proposals" | "approvals" | "comments" | "artifacts" | "workOrders" | "reviewSessions" | "shares"; required. Named durable brief collection to page; use one of the documented enum values. Allowed values: "versions", "decisionHistory", "findings", "proposals", "approvals", "comments", "artifacts", "workOrders", "reviewSessions", "shares".
- `items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `items[]` — object; required.
- `items[]{key}` — JSON value; optional.
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"enum": [
"versions",
"decisionHistory",
"findings",
"proposals",
"approvals",
"comments",
"artifacts",
"workOrders",
"reviewSessions",
"shares"
],
"description": "Named durable brief collection to page; use one of the documented enum values. Allowed values: \"versions\", \"decisionHistory\", \"findings\", \"proposals\", \"approvals\", \"comments\", \"artifacts\", \"workOrders\", \"reviewSessions\", \"shares\"."
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"collection",
"items",
"nextCursor"
],
"additionalProperties": false
}
```
**Example structured result (collection-page)**
```json
{
"collection": "decisionHistory",
"items": [],
"nextCursor": null
}
```
Bindings: nextCursor from structuredContent.nextCursor.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"collection\":\"decisionHistory\",\"items\":[],\"nextCursor\":null}"
}
],
"structuredContent": {
"collection": "decisionHistory",
"items": [],
"nextCursor": null
}
}
```
Next permitted action: Repeat with the returned cursor until nextCursor is null.
**Example requests**
- “/semel list the version history for this brief”
- “/semel show the decision history of the checkout brief”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `brief_list`, `brief_get_full`.
---
### brief_create
Create a new brief inside a project — its title and first contract version — as the starting artifact for an effort's requirements. Use once the project exists to begin capturing what will be built.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `title` — string; required; minimum length 1; maximum length 500. Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
- `content` — object; optional. Complete replacement brief document for agent writes, limited to 262144 serialized bytes. Known sections use the canonical nested shapes; unknown metadata and _draft remain round-trippable.
- `content.goal` — string; optional; maximum length 4000. Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.userPersonaContext` — string; optional; maximum length 4000. User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.scope` — string; optional; maximum length 4000. Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.outOfScope` — string; optional; maximum length 4000. Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.requirements` — array; optional; maximum items 50. Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.requirements[]` — string; required; minimum length 1; maximum length 1000.
- `content.edgeCases` — array; optional; maximum items 50. Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.edgeCases[]` — string; required; minimum length 1; maximum length 1000.
- `content.acceptanceCriteria` — array; optional; maximum items 50. Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.acceptanceCriteria[]` — object; required.
- `content.acceptanceCriteria[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.acceptanceCriteria[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.acceptanceCriteria[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.acceptanceCriteria[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.acceptanceCriteria[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `content.acceptanceCriteria[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `content.rolesPermissions` — array; optional; maximum items 50. Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.rolesPermissions[]` — string; required; minimum length 1; maximum length 1000.
- `content.states` — array; optional; maximum items 50. User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.states[]` — string; required; minimum length 1; maximum length 1000.
- `content.productSolution` — string; optional; maximum length 4000. Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.technicalSolution` — string; optional; maximum length 4000. Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.dataModelImplications` — string; optional; maximum length 4000. Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.architectureAssumptions` — string; optional; maximum length 4000. Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.design` — string; optional; maximum length 4000. Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.testingQaChecklist` — array; optional; maximum items 50. Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testingQaChecklist[]` — object; required.
- `content.testingQaChecklist[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.testingQaChecklist[].checked` — boolean; required. Whether this QA checklist item is currently complete.
- `content.testingQaChecklist[].addedBy` — string; optional; maximum length 200. Actor label that added the QA item; omission means legacy or unavailable attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.testingQaChecklist[].checkedBy` — string; optional; maximum length 200. Actor label that last checked the item; omission means it has no check attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.testingQaChecklist[].checkedAt` — string; optional; format date-time. RFC 3339 timestamp when the item was checked; omission means it is unchecked or legacy data. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string.
- `content.testPlanUnit` — array; optional; maximum items 50. Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanUnit[]` — string; required; minimum length 1; maximum length 1000.
- `content.testPlanIntegration` — array; optional; maximum items 50. Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanIntegration[]` — string; required; minimum length 1; maximum length 1000.
- `content.testPlanUiUx` — array; optional; maximum items 50. Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanUiUx[]` — string; required; minimum length 1; maximum length 1000.
- `content.openQuestions` — array; optional; maximum items 50. Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.openQuestions[]` — string; required; minimum length 1; maximum length 1000.
- `content.generatedTickets` — array; optional; maximum items 50. Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.generatedTickets[]` — object; required.
- `content.generatedTickets[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.generatedTickets[].title` — string; required; minimum length 1; maximum length 500. Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
- `content.generatedTickets[].description` — JSON value; required. Human-readable explanatory text; null or omission means no description was supplied. A null value explicitly means no current value is available. Maximum accepted length or value is 10000.
- `content.generatedTickets[].description (anyOf branch 1)` — string; required; maximum length 10000.
- `content.generatedTickets[].description (anyOf branch 2)` — null; required.
- `content.generatedTickets[].boundCriteria` — array; required; maximum items 50. Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items.
- `content.generatedTickets[].boundCriteria[]` — string; required; minimum length 1; maximum length 200.
- `content.generatedTickets[].boundRequirements` — array; optional; maximum items 50. Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.generatedTickets[].boundRequirements[]` — string; required; minimum length 1; maximum length 200.
- `content.requiredEvidence` — array; optional; maximum items 50. Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.requiredEvidence[]` — object; required.
- `content.requiredEvidence[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.requiredEvidence[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.requiredEvidence[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.requiredEvidence[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.requiredEvidence[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `content.requiredEvidence[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `content.decisions` — array; optional; maximum items 50. Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.decisions[]` — object; required.
- `content.decisions[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.decisions[].source` — string; optional; maximum length 1000. Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000.
- `content.decisions[].stated` — boolean; optional. Whether the decision was explicitly stated rather than inferred; omission means unknown legacy provenance. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.sourceArtifactLinks` — array; optional; maximum items 50. Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.sourceArtifactLinks[]` — object; required.
- `content.sourceArtifactLinks[].label` — string; required; minimum length 1; maximum length 1000. Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive.
- `content.sourceArtifactLinks[].kind` — string; optional; maximum length 200. Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.sourceArtifactLinks[].read` — boolean; optional. Whether the referenced source artifact was read when the brief snapshot was produced. Omit the field when it does not apply; omission is distinct from an empty value.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive."
},
"content": {
"type": "object",
"properties": {
"goal": {
"type": "string",
"maxLength": 4000,
"description": "Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"userPersonaContext": {
"type": "string",
"maxLength": 4000,
"description": "User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"scope": {
"type": "string",
"maxLength": 4000,
"description": "Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"outOfScope": {
"type": "string",
"maxLength": 4000,
"description": "Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"requirements": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"edgeCases": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"acceptanceCriteria": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"implementation": {
"type": "boolean",
"description": "Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value."
},
"manualEvidence": {
"type": "object",
"properties": {
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive."
},
"evidencePath": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive."
}
},
"required": [
"rationale",
"evidencePath"
],
"additionalProperties": false,
"description": "Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"id",
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"rolesPermissions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"states": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"productSolution": {
"type": "string",
"maxLength": 4000,
"description": "Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"technicalSolution": {
"type": "string",
"maxLength": 4000,
"description": "Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"dataModelImplications": {
"type": "string",
"maxLength": 4000,
"description": "Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"architectureAssumptions": {
"type": "string",
"maxLength": 4000,
"description": "Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"design": {
"type": "string",
"maxLength": 4000,
"description": "Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"testingQaChecklist": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"checked": {
"type": "boolean",
"description": "Whether this QA checklist item is currently complete."
},
"addedBy": {
"type": "string",
"maxLength": 200,
"description": "Actor label that added the QA item; omission means legacy or unavailable attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"checkedBy": {
"type": "string",
"maxLength": 200,
"description": "Actor label that last checked the item; omission means it has no check attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"checkedAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp when the item was checked; omission means it is unchecked or legacy data. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string."
}
},
"required": [
"text",
"checked"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanUnit": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanIntegration": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanUiUx": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"openQuestions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"generatedTickets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive."
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 10000
},
{
"type": "null"
}
],
"description": "Human-readable explanatory text; null or omission means no description was supplied. A null value explicitly means no current value is available. Maximum accepted length or value is 10000."
},
"boundCriteria": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
},
"maxItems": 50,
"description": "Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items."
},
"boundRequirements": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
},
"maxItems": 50,
"description": "Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"required": [
"id",
"title",
"description",
"boundCriteria"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"requiredEvidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"implementation": {
"type": "boolean",
"description": "Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value."
},
"manualEvidence": {
"type": "object",
"properties": {
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive."
},
"evidencePath": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive."
}
},
"required": [
"rationale",
"evidencePath"
],
"additionalProperties": false,
"description": "Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"id",
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"decisions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"source": {
"type": "string",
"maxLength": 1000,
"description": "Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000."
},
"stated": {
"type": "boolean",
"description": "Whether the decision was explicitly stated rather than inferred; omission means unknown legacy provenance. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"sourceArtifactLinks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive."
},
"kind": {
"type": "string",
"maxLength": 200,
"description": "Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"read": {
"type": "boolean",
"description": "Whether the referenced source artifact was read when the brief snapshot was produced. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"label"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"additionalProperties": true,
"description": "Complete replacement brief document for agent writes, limited to 262144 serialized bytes. Known sections use the canonical nested shapes; unknown metadata and _draft remain round-trippable."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"projectId",
"title",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"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": "recipe-brief-create-v1"
}
```
**Binding template**
```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}}"
}
```
**Returns**
- `brief` — object; required. Current brief record returned by the operation.
- `brief.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `brief.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `brief.title` — string; required. Human-readable title displayed in Semel.
- `brief.state` — "drafting" | "in_review" | "baselined" | "in_development" | "checked" | "superseded" | "closed"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "drafting", "in_review", "baselined", "in_development", "checked", "superseded", "closed".
- `brief.currentVersionHash` — string | null; required. Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available.
- `brief.content` — object; required. Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
- `brief.content{key}` — JSON value; optional.
- `brief.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"brief": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"state": {
"type": "string",
"enum": [
"drafting",
"in_review",
"baselined",
"in_development",
"checked",
"superseded",
"closed"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"drafting\", \"in_review\", \"baselined\", \"in_development\", \"checked\", \"superseded\", \"closed\"."
},
"currentVersionHash": {
"type": [
"string",
"null"
],
"description": "Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available."
},
"content": {
"type": "object",
"additionalProperties": {},
"description": "Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
}
},
"required": [
"id",
"projectId",
"title",
"state",
"currentVersionHash",
"content",
"versionNum"
],
"additionalProperties": false,
"description": "Current brief record returned by the operation."
}
},
"required": [
"brief"
],
"additionalProperties": false
}
```
**Example structured result (brief-created)**
```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
}
}
```
Bindings: briefId from structuredContent.brief.id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}"
}
],
"structuredContent": {
"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
}
}
}
```
Next permitted action: Load the complete persisted aggregate by the returned brief id.
**Example requests**
- “/semel create a brief for the checkout flow”
- “/semel start a new brief in the billing project”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `brief_update`, `brief_get_full`.
---
### brief_export_markdown
DEPRECATED compatibility export that renders a brief to Markdown only. It is not a verified implementation handoff; use brief_export_package instead.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
}
},
"required": [
"briefId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}"
}
```
**Returns**
- `filename` — string; required. Safe suggested filename for the downloaded export.
- `resource` — JSON value; required. Optional MCP resource descriptor for the Markdown export; null means the export is available only in the inline payload. A null value explicitly means no current value is available.
- `resource (anyOf branch 1)` — object; required.
- `resource (anyOf branch 1).uri` — string; required. Absolute or same-origin URI for the referenced resource or required operator action.
- `resource (anyOf branch 1).name` — string; required. Human-readable name displayed in Semel.
- `resource (anyOf branch 1).mimeType` — string; required. Internet media type of the artifact or exported resource; null means the producer did not record one.
- `resource (anyOf branch 2)` — null; required.
- `downloadUrl` — string | null; required. Short-lived or public download URL returned by Semel; do not construct or persist it as an identifier. A null value explicitly means no current value is available.
- `markdown` — string | null; required. Complete Markdown export of the selected brief snapshot. A null value explicitly means no current value is available.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "Safe suggested filename for the downloaded export."
},
"resource": {
"anyOf": [
{
"type": "object",
"properties": {
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"mimeType": {
"type": "string",
"description": "Internet media type of the artifact or exported resource; null means the producer did not record one."
}
},
"required": [
"uri",
"name",
"mimeType"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Optional MCP resource descriptor for the Markdown export; null means the export is available only in the inline payload. A null value explicitly means no current value is available."
},
"downloadUrl": {
"type": [
"string",
"null"
],
"description": "Short-lived or public download URL returned by Semel; do not construct or persist it as an identifier. A null value explicitly means no current value is available."
},
"markdown": {
"type": [
"string",
"null"
],
"description": "Complete Markdown export of the selected brief snapshot. A null value explicitly means no current value is available."
}
},
"required": [
"filename",
"resource",
"downloadUrl",
"markdown"
],
"additionalProperties": false
}
```
**Example structured result (legacy-markdown)**
```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"
}
```
Bindings: legacyResource from structuredContent.resource.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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\"}"
},
{
"type": "resource_link",
"uri": "https://mcp.semel.ai/brief-exports/brf_fixture_checkout.md",
"name": "retry-safe-checkout.md",
"mimeType": "text/markdown"
}
],
"structuredContent": {
"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"
}
}
```
Next permitted action: Label the result deprecated and do not treat it as a verified handoff.
**Example requests**
- “/semel export this brief as markdown”
- “/semel give me the markdown for the checkout brief”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `brief_export_package`, `brief_get_full`.
---
### brief_export_package
Create a verified, immutable ZIP implementation handoff for a brief — the canonical R9 export. Use to hand a completed brief off to implementation; if it errors, no usable package exists and you should not fall back to the deprecated Markdown export.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"briefId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"idempotencyKey": "recipe-brief-export-package-v1"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `exportId` — string; required; minimum length 1. Opaque identifier assigned to this deterministic export package; use returned download metadata rather than constructing it. Minimum accepted length or value is 1.
- `status` — constant "ready"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "ready".
- `filename` — string; required; minimum length 1. Safe suggested filename for the downloaded export. Minimum accepted length or value is 1.
- `downloadUrl` — string; required; minimum length 1. Short-lived or public download URL returned by Semel; do not construct or persist it as an identifier. Minimum accepted length or value is 1.
- `manifestSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the export manifest.
- `implementationReady` — constant true; required. Whether the exported brief satisfies Semel implementation-readiness checks. This branch always uses true.
- `expiresAt` — string; required; format date-time. RFC 3339 expiration timestamp. Use an RFC 3339 date-time string.
- `snapshotId` — string; required; minimum length 1. Immutable export snapshot identifier used to reproduce the exported brief state. Minimum accepted length or value is 1.
- `contractVersionId` — string; required; minimum length 1. Immutable brief contract-version identifier resolved by Semel. Minimum accepted length or value is 1.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"exportId": {
"type": "string",
"minLength": 1,
"description": "Opaque identifier assigned to this deterministic export package; use returned download metadata rather than constructing it. Minimum accepted length or value is 1."
},
"status": {
"type": "string",
"const": "ready",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"ready\"."
},
"filename": {
"type": "string",
"minLength": 1,
"description": "Safe suggested filename for the downloaded export. Minimum accepted length or value is 1."
},
"downloadUrl": {
"type": "string",
"minLength": 1,
"description": "Short-lived or public download URL returned by Semel; do not construct or persist it as an identifier. Minimum accepted length or value is 1."
},
"manifestSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest of the export manifest."
},
"implementationReady": {
"type": "boolean",
"const": true,
"description": "Whether the exported brief satisfies Semel implementation-readiness checks. This branch always uses true."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 expiration timestamp. Use an RFC 3339 date-time string."
},
"snapshotId": {
"type": "string",
"minLength": 1,
"description": "Immutable export snapshot identifier used to reproduce the exported brief state. Minimum accepted length or value is 1."
},
"contractVersionId": {
"type": "string",
"minLength": 1,
"description": "Immutable brief contract-version identifier resolved by Semel. Minimum accepted length or value is 1."
}
},
"required": [
"exportId",
"status",
"filename",
"downloadUrl",
"manifestSha256",
"implementationReady",
"expiresAt",
"snapshotId",
"contractVersionId"
],
"additionalProperties": false
}
```
**Example structured result (ready)**
```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"
}
```
Bindings: downloadUrl from structuredContent.downloadUrl.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"exportId\":\"example\",\"status\":\"ready\",\"filename\":\"retry-safe-checkout.zip\",\"downloadUrl\":\"https://mcp.semel.ai/mcp/brief-exports/example/download\",\"manifestSha256\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"implementationReady\":true,\"expiresAt\":\"2026-09-07T16:00:00.000Z\",\"snapshotId\":\"example\",\"contractVersionId\":\"example\"}"
},
{
"type": "resource_link",
"uri": "https://mcp.semel.ai/mcp/brief-exports/example/download",
"name": "retry-safe-checkout.zip",
"mimeType": "application/zip"
}
],
"structuredContent": {
"exportId": "example",
"status": "ready",
"filename": "retry-safe-checkout.zip",
"downloadUrl": "https://mcp.semel.ai/mcp/brief-exports/example/download",
"manifestSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"implementationReady": true,
"expiresAt": "2026-09-07T16:00:00.000Z",
"snapshotId": "example",
"contractVersionId": "example"
}
}
```
Next permitted action: Fetch the bearer-authenticated resource before expiresAt and verify the manifest/hash.
**Example requests**
- “/semel export the checkout brief as an implementation package”
- “/semel build the handoff package for this brief”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `brief_get_full`, `brief_export_markdown`.
---
### brief_get_full
Read the complete brief aggregate in one call — the current content plus the first page of every durable collection (versions, decision history, proposals, and more). Use to load everything about a brief before acting on it.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
}
},
"required": [
"briefId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}"
}
```
**Returns**
- `brief` — object; required. Current brief record returned by the operation.
- `brief.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `brief.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `brief.title` — string; required. Human-readable title displayed in Semel.
- `brief.state` — "drafting" | "in_review" | "baselined" | "in_development" | "checked" | "superseded" | "closed"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "drafting", "in_review", "baselined", "in_development", "checked", "superseded", "closed".
- `brief.currentVersionHash` — string | null; required. Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available.
- `brief.content` — object; required. Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
- `brief.content{key}` — JSON value; optional.
- `brief.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `collections` — object; required. First page of each durable collection associated with the brief.
- `collections.versions` — object; required. Immutable brief version summaries, newest first.
- `collections.versions.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.versions.items[]` — object; required.
- `collections.versions.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.versions.items[].versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `collections.versions.items[].contentHash` — string; required. Hash of the immutable brief content snapshot.
- `collections.versions.items[].aiReviewerRole` — string | null; required. Reviewer role that authored this immutable brief version; null means a human or legacy source authored it. A null value explicitly means no current value is available.
- `collections.versions.items[].sourceRunId` — string | null; required. Review-run identifier that authored this brief version; null means the version was not created by a reviewer run. A null value explicitly means no current value is available.
- `collections.versions.items[].isRevert` — boolean; required. Whether this immutable version was created by reverting to prior content.
- `collections.versions.items[].createdById` — string; required. Semel user identifier recorded as the initiating creator.
- `collections.versions.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.versions.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.decisionHistory` — object; required. Durable question and decision history for the brief.
- `collections.decisionHistory.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.decisionHistory.items[]` — object; required.
- `collections.decisionHistory.items[].kind` — "canonical_decision" | "reviewer_question"; required. Discriminator identifying the typed variant represented by this object. Allowed values: "canonical_decision", "reviewer_question".
- `collections.decisionHistory.items[].sourceId` — string; required. Opaque source identifier returned by project_context_sources_list; pass it back unchanged.
- `collections.decisionHistory.items[].text` — string; required. Human-authored or model-produced text for this typed record.
- `collections.decisionHistory.items[].answer` — string | null; required. Durable answer text recorded for this decision-history entry; null means the question had no accepted answer at this snapshot. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].status` — string | null; required. Current typed status; the schema enum or union branch lists every allowed value. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].reviewerRole` — string | null; required. Reviewer role attributed to this question, finding, or version. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].section` — string | null; required. Canonical brief section key associated with the question, finding, proposal, or decision entry. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].iterationRound` — JSON value; required. One-based review iteration that produced this decision-history entry; null means legacy round data is unavailable. A null value explicitly means no current value is available. The value must be an integer.
- `collections.decisionHistory.items[].iterationRound (anyOf branch 1)` — integer; required.
- `collections.decisionHistory.items[].iterationRound (anyOf branch 2)` — null; required.
- `collections.decisionHistory.items[].sessionId` — string | null; required. Review-session identifier associated with this historical record; null means legacy provenance is unavailable. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].runId` — string | null; required. Review-run identifier returned by a review start, status, or cascade handoff result. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].actorUserId` — string | null; required. Accountable Semel user identifier recorded on the event. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].createdAt` — string | null; required. RFC 3339 timestamp assigned by Semel when this record was created. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].answeredAt` — string | null; required. RFC 3339 timestamp when the active answer was recorded. A null value explicitly means no current value is available.
- `collections.decisionHistory.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.findings` — object; required. Reviewer findings associated with the selected brief version.
- `collections.findings.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.findings.items[]` — object; required.
- `collections.findings.items[].section` — string; required. Canonical brief section key associated with the question, finding, proposal, or decision entry.
- `collections.findings.items[].note` — string; required. Reviewer-facing finding detail that explains the observed issue and the evidence-based change requested.
- `collections.findings.items[].severity` — "info" | "warn" | "block"; required. Finding impact level: info is advisory, warn requires attention, and block prevents approval or completion. Allowed values: "info", "warn", "block".
- `collections.findings.items[].citations` — array; optional. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `collections.findings.items[].citations[]` — JSON value; required.
- `collections.findings.items[].citations[] (anyOf branch 1)` — object; required.
- `collections.findings.items[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `collections.findings.items[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: "goal", "userPersonaContext", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `collections.findings.items[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 1).briefId` — string; required. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary.
- `collections.findings.items[].citations[] (anyOf branch 1).contractVersionId` — string; required. Immutable brief contract-version identifier resolved by Semel.
- `collections.findings.items[].citations[] (anyOf branch 1).versionNum` — integer; optional. Monotonic brief contract version number assigned by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citations[] (anyOf branch 1).reviewers` — array; required; minimum items 1. Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
- `collections.findings.items[].citations[] (anyOf branch 1).reviewers[]` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].citations[] (anyOf branch 1).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `collections.findings.items[].citations[] (anyOf branch 2)` — object; required.
- `collections.findings.items[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `collections.findings.items[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 2).extractedTextHash` — string; required. Hash of the normalized text extracted from the cited artifact, used to bind the citation to exact processed content.
- `collections.findings.items[].citations[] (anyOf branch 2).reviewers` — array; required; minimum items 1. Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
- `collections.findings.items[].citations[] (anyOf branch 2).reviewers[]` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].citations[] (anyOf branch 2).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `collections.findings.items[].citations[] (anyOf branch 3)` — object; required.
- `collections.findings.items[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `collections.findings.items[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 3).evidenceManifestId` — string; required; minimum length 1. Immutable evidence-manifest identifier captured for the review run. Minimum accepted length or value is 1.
- `collections.findings.items[].citations[] (anyOf branch 3).evidenceManifestItemId` — string; required; minimum length 1. Identifier of the exact item inside the immutable evidence manifest. Minimum accepted length or value is 1.
- `collections.findings.items[].citations[] (anyOf branch 3).workspaceRepositoryId` — string; required; minimum length 1. Workspace-scoped connected repository identifier recorded in evidence provenance. Minimum accepted length or value is 1.
- `collections.findings.items[].citations[] (anyOf branch 3).revisionId` — string; required; minimum length 1. Immutable indexed repository revision identifier. Minimum accepted length or value is 1.
- `collections.findings.items[].citations[] (anyOf branch 3).commitSha` — string; required. Git commit SHA pinned by the evidence manifest.
- `collections.findings.items[].citations[] (anyOf branch 3).blobSha` — string; required. Git blob SHA for the cited file contents.
- `collections.findings.items[].citations[] (anyOf branch 3).path` — string; required; minimum length 1. Repository-relative source path; it never denotes an arbitrary local filesystem path. Minimum accepted length or value is 1.
- `collections.findings.items[].citations[] (anyOf branch 3).startLine` — integer; required. One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citations[] (anyOf branch 3).endLine` — integer; required. One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citations[] (anyOf branch 3).excerptSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the exact cited excerpt.
- `collections.findings.items[].citations[] (anyOf branch 3).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `collections.findings.items[].citations[] (anyOf branch 3).coverage` — object; required. Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence.
- `collections.findings.items[].citations[] (anyOf branch 3).coverage{key}` — JSON value; optional.
- `collections.findings.items[].citations[] (anyOf branch 3).reviewers` — array; required; minimum items 1. Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
- `collections.findings.items[].citations[] (anyOf branch 3).reviewers[]` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].citations[] (anyOf branch 3).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `collections.findings.items[].evidenceUnavailable` — boolean; optional. Whether the finding was emitted without the evidence normally required for verification; omission means evidence availability was not separately recorded. Omit the field when it does not apply; omission is distinct from an empty value.
- `collections.findings.items[].claimDisposition` — "verified" | "unverified"; optional. Published support disposition for a code claim; omission indicates a legacy row that is treated as verified. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: "verified", "unverified".
- `collections.findings.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.proposals` — object; required. Reviewer proposals and their decision/commit state.
- `collections.proposals.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.proposals.items[]` — object; required.
- `collections.proposals.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.proposals.items[].sessionId` — string; required. Review-session identifier associated with this historical record; null means legacy provenance is unavailable.
- `collections.proposals.items[].section` — string; required. Canonical brief section key associated with the question, finding, proposal, or decision entry.
- `collections.proposals.items[].summary` — string | null; required. Concise safe summary intended for users and logs. A null value explicitly means no current value is available.
- `collections.proposals.items[].status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `collections.proposals.items[].decidedById` — string | null; required. Semel user identifier that decided this proposal; absent until a decision exists. A null value explicitly means no current value is available.
- `collections.proposals.items[].decidedAt` — string | null; required. RFC 3339 timestamp of the proposal decision; null means undecided. A null value explicitly means no current value is available.
- `collections.proposals.items[].decisionSource` — string | null; required. Typed provenance showing whether a proposal decision came from a user, reviewer, or system rule; null means unavailable legacy provenance. A null value explicitly means no current value is available.
- `collections.proposals.items[].committedAt` — string | null; required. RFC 3339 timestamp when the accepted proposal was committed; null means not committed. A null value explicitly means no current value is available.
- `collections.proposals.items[].sourceRound` — JSON value; required. Review round that produced this proposal; null means no round provenance was recorded. A null value explicitly means no current value is available. The value must be an integer.
- `collections.proposals.items[].sourceRound (anyOf branch 1)` — integer; required.
- `collections.proposals.items[].sourceRound (anyOf branch 2)` — null; required.
- `collections.proposals.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.proposals.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.approvals` — object; required. Append-only human approval records for brief versions.
- `collections.approvals.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.approvals.items[]` — object; required.
- `collections.approvals.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.approvals.items[].contractVersionId` — string; required. Immutable brief contract-version identifier resolved by Semel.
- `collections.approvals.items[].approverId` — string; required. Semel user identifier for the human who recorded this approval decision.
- `collections.approvals.items[].action` — string; required. Typed human approval action recorded in the append-only approval ledger.
- `collections.approvals.items[].isStale` — boolean; required. Whether this historical approval no longer targets the current brief version.
- `collections.approvals.items[].reRequestReason` — string | null; required. Reason a previously decided approval was requested again; null means no re-request reason applies. A null value explicitly means no current value is available.
- `collections.approvals.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.approvals.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.comments` — object; required. Human comments attached to brief sections or anchors.
- `collections.comments.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.comments.items[]` — object; required.
- `collections.comments.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.comments.items[].sectionKey` — string; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result.
- `collections.comments.items[].anchor` — string | null; required. Optional structured location within a brief section for this comment; null means the comment applies to the section as a whole. A null value explicitly means no current value is available.
- `collections.comments.items[].text` — string; required. Human-authored or model-produced text for this typed record.
- `collections.comments.items[].authorId` — string; required. Semel user identifier for the comment or content author.
- `collections.comments.items[].resolvedAt` — string | null; required. RFC 3339 timestamp when the comment was resolved; null means unresolved. A null value explicitly means no current value is available.
- `collections.comments.items[].resolvedBy` — string | null; required. Semel user identifier that resolved the comment; absent until resolution. A null value explicitly means no current value is available.
- `collections.comments.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.comments.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.artifacts` — object; required. Source artifacts attached to the brief.
- `collections.artifacts.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.artifacts.items[]` — object; required.
- `collections.artifacts.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.artifacts.items[].artifactType` — string; required. Semel artifact classification used to select ingestion and display behavior for this source material.
- `collections.artifacts.items[].label` — string | null; required. Human-readable label displayed for this record. A null value explicitly means no current value is available.
- `collections.artifacts.items[].sourceUrl` — string | null; required. Original source URL recorded for the artifact; null means the artifact has no external source URL. A null value explicitly means no current value is available.
- `collections.artifacts.items[].mimeType` — string | null; required. Internet media type of the artifact or exported resource; null means the producer did not record one. A null value explicitly means no current value is available.
- `collections.artifacts.items[].sizeBytes` — JSON value; required. Artifact size in bytes. A null value explicitly means no current value is available. The value must be an integer.
- `collections.artifacts.items[].sizeBytes (anyOf branch 1)` — integer; required.
- `collections.artifacts.items[].sizeBytes (anyOf branch 2)` — null; required.
- `collections.artifacts.items[].ingestionStatus` — string; required. Current artifact ingestion lifecycle state; only ready artifacts may supply reviewed evidence.
- `collections.artifacts.items[].createdById` — string | null; required. Semel user identifier recorded as the initiating creator. A null value explicitly means no current value is available.
- `collections.artifacts.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.artifacts.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.workOrders` — object; required. Materialized implementation work orders for the brief.
- `collections.workOrders.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.workOrders.items[]` — object; required.
- `collections.workOrders.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.workOrders.items[].title` — string; required. Human-readable title displayed in Semel.
- `collections.workOrders.items[].description` — string | null; required. Human-readable explanatory text; null or omission means no description was supplied. A null value explicitly means no current value is available.
- `collections.workOrders.items[].position` — integer; required. Stable zero-based or configured ordering position returned by Semel. The value must be an integer.
- `collections.workOrders.items[].boundCriteria` — array; required. Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items.
- `collections.workOrders.items[].boundCriteria[]` — string; required.
- `collections.workOrders.items[].boundRequirements` — array; required. Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. An empty array explicitly means no matching items.
- `collections.workOrders.items[].boundRequirements[]` — string; required.
- `collections.workOrders.items[].externalTracker` — string | null; required. External issue-tracker provider associated with the work order; null means the work order has not been exported. A null value explicitly means no current value is available.
- `collections.workOrders.items[].externalUrl` — string | null; required. External tracker URL associated with the work order; null means no issue is linked. A null value explicitly means no current value is available.
- `collections.workOrders.items[].exportState` — string; required. Current external-tracker export lifecycle state for this generated work order.
- `collections.workOrders.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.workOrders.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.reviewSessions` — object; required. Review session summaries associated with the brief.
- `collections.reviewSessions.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.reviewSessions.items[]` — object; required.
- `collections.reviewSessions.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.reviewSessions.items[].runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `collections.reviewSessions.items[].status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `collections.reviewSessions.items[].reviewerSet` — array; required. Ordered reviewer roles configured for this cascade. An empty array explicitly means no matching items.
- `collections.reviewSessions.items[].reviewerSet[]` — string; required.
- `collections.reviewSessions.items[].reviewedContractVersionId` — string | null; required. Immutable contract-version identifier actually reviewed by this session; null means the session has not pinned one. A null value explicitly means no current value is available.
- `collections.reviewSessions.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.reviewSessions.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.shares` — object; required. Share-link records associated with the brief.
- `collections.shares.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.shares.items[]` — object; required.
- `collections.shares.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.shares.items[].accessLevel` — string; required. Share-link access policy assigned by Semel; the enum identifies whether the recipient may only view or may also interact.
- `collections.shares.items[].sharedById` — string; required. Semel user identifier for the person who created the share.
- `collections.shares.items[].isActive` — boolean; required. Whether this share link remains active.
- `collections.shares.items[].expiresAt` — string | null; required. RFC 3339 expiration timestamp. A null value explicitly means no current value is available.
- `collections.shares.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.shares.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `gateNotificationStatus` — JSON value; required. Latest human gate notification status; null means no notification request exists. A null value explicitly means no current value is available.
- `gateNotificationStatus (anyOf branch 1)` — object; required.
- `gateNotificationStatus (anyOf branch 1).requestId` — string; required. Server request identifier used for support correlation; it is not an idempotency key.
- `gateNotificationStatus (anyOf branch 1).assignmentId` — string | null; required. Human gate assignment identifier created by Semel. A null value explicitly means no current value is available.
- `gateNotificationStatus (anyOf branch 1).contentHash` — string | null; required. Hash of the immutable brief content snapshot. A null value explicitly means no current value is available.
- `gateNotificationStatus (anyOf branch 1).notifiedAt` — string | null; required. RFC 3339 timestamp when the gate notification was sent; null means not sent. A null value explicitly means no current value is available.
- `gateNotificationStatus (anyOf branch 1).createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `gateNotificationStatus (anyOf branch 2)` — null; required.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"brief": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"state": {
"type": "string",
"enum": [
"drafting",
"in_review",
"baselined",
"in_development",
"checked",
"superseded",
"closed"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"drafting\", \"in_review\", \"baselined\", \"in_development\", \"checked\", \"superseded\", \"closed\"."
},
"currentVersionHash": {
"type": [
"string",
"null"
],
"description": "Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available."
},
"content": {
"type": "object",
"additionalProperties": {},
"description": "Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
}
},
"required": [
"id",
"projectId",
"title",
"state",
"currentVersionHash",
"content",
"versionNum"
],
"additionalProperties": false,
"description": "Current brief record returned by the operation."
},
"collections": {
"type": "object",
"properties": {
"versions": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
},
"contentHash": {
"type": "string",
"description": "Hash of the immutable brief content snapshot."
},
"aiReviewerRole": {
"type": [
"string",
"null"
],
"description": "Reviewer role that authored this immutable brief version; null means a human or legacy source authored it. A null value explicitly means no current value is available."
},
"sourceRunId": {
"type": [
"string",
"null"
],
"description": "Review-run identifier that authored this brief version; null means the version was not created by a reviewer run. A null value explicitly means no current value is available."
},
"isRevert": {
"type": "boolean",
"description": "Whether this immutable version was created by reverting to prior content."
},
"createdById": {
"type": "string",
"description": "Semel user identifier recorded as the initiating creator."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"versionNum",
"contentHash",
"aiReviewerRole",
"sourceRunId",
"isRevert",
"createdById",
"createdAt"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Immutable brief version summaries, newest first."
},
"decisionHistory": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"canonical_decision",
"reviewer_question"
],
"description": "Discriminator identifying the typed variant represented by this object. Allowed values: \"canonical_decision\", \"reviewer_question\"."
},
"sourceId": {
"type": "string",
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged."
},
"text": {
"type": "string",
"description": "Human-authored or model-produced text for this typed record."
},
"answer": {
"type": [
"string",
"null"
],
"description": "Durable answer text recorded for this decision-history entry; null means the question had no accepted answer at this snapshot. A null value explicitly means no current value is available."
},
"status": {
"type": [
"string",
"null"
],
"description": "Current typed status; the schema enum or union branch lists every allowed value. A null value explicitly means no current value is available."
},
"reviewerRole": {
"type": [
"string",
"null"
],
"description": "Reviewer role attributed to this question, finding, or version. A null value explicitly means no current value is available."
},
"section": {
"type": [
"string",
"null"
],
"description": "Canonical brief section key associated with the question, finding, proposal, or decision entry. A null value explicitly means no current value is available."
},
"iterationRound": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "One-based review iteration that produced this decision-history entry; null means legacy round data is unavailable. A null value explicitly means no current value is available. The value must be an integer."
},
"sessionId": {
"type": [
"string",
"null"
],
"description": "Review-session identifier associated with this historical record; null means legacy provenance is unavailable. A null value explicitly means no current value is available."
},
"runId": {
"type": [
"string",
"null"
],
"description": "Review-run identifier returned by a review start, status, or cascade handoff result. A null value explicitly means no current value is available."
},
"actorUserId": {
"type": [
"string",
"null"
],
"description": "Accountable Semel user identifier recorded on the event. A null value explicitly means no current value is available."
},
"createdAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp assigned by Semel when this record was created. A null value explicitly means no current value is available."
},
"answeredAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp when the active answer was recorded. A null value explicitly means no current value is available."
}
},
"required": [
"kind",
"sourceId",
"text",
"answer",
"status",
"reviewerRole",
"section",
"iterationRound",
"sessionId",
"runId",
"actorUserId",
"createdAt",
"answeredAt"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Durable question and decision history for the brief."
},
"findings": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"section": {
"type": "string",
"description": "Canonical brief section key associated with the question, finding, proposal, or decision entry."
},
"note": {
"type": "string",
"description": "Reviewer-facing finding detail that explains the observed issue and the evidence-based change requested."
},
"severity": {
"type": "string",
"enum": [
"info",
"warn",
"block"
],
"description": "Finding impact level: info is advisory, warn requires attention, and block prevents approval or completion. Allowed values: \"info\", \"warn\", \"block\"."
},
"citations": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "brief-section",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"brief-section\"."
},
"sectionKey": {
"type": "string",
"enum": [
"goal",
"userPersonaContext",
"scope",
"outOfScope",
"requirements",
"edgeCases",
"acceptanceCriteria",
"rolesPermissions",
"states",
"productSolution",
"technicalSolution",
"dataModelImplications",
"architectureAssumptions",
"design",
"testingQaChecklist",
"testPlanUnit",
"testPlanIntegration",
"testPlanUiUx",
"openQuestions",
"generatedTickets",
"requiredEvidence",
"decisions",
"sourceArtifactLinks"
],
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: \"goal\", \"userPersonaContext\", \"scope\", \"outOfScope\", \"requirements\", \"edgeCases\", \"acceptanceCriteria\", \"rolesPermissions\", \"states\", \"productSolution\", \"technicalSolution\", \"dataModelImplications\", \"architectureAssumptions\", \"design\", \"testingQaChecklist\", \"testPlanUnit\", \"testPlanIntegration\", \"testPlanUiUx\", \"openQuestions\", \"generatedTickets\", \"requiredEvidence\", \"decisions\", \"sourceArtifactLinks\"."
},
"statementId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
},
"briefId": {
"type": "string",
"description": "Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary."
},
"contractVersionId": {
"type": "string",
"description": "Immutable brief contract-version identifier resolved by Semel."
},
"versionNum": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Monotonic brief contract version number assigned by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 0. The value must be an integer."
},
"reviewers": {
"type": "array",
"items": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
"minItems": 1,
"description": "Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items."
},
"verification": {
"type": "string",
"enum": [
"exact",
"canonical",
"unverified"
],
"description": "Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: \"exact\", \"canonical\", \"unverified\"."
}
},
"required": [
"sourceType",
"sectionKey",
"verbatim",
"briefId",
"contractVersionId",
"reviewers",
"verification"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "artifact",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"artifact\"."
},
"artifactId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
},
"extractedTextHash": {
"type": "string",
"description": "Hash of the normalized text extracted from the cited artifact, used to bind the citation to exact processed content."
},
"reviewers": {
"type": "array",
"items": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
"minItems": 1,
"description": "Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items."
},
"verification": {
"type": "string",
"enum": [
"exact",
"canonical",
"unverified"
],
"description": "Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: \"exact\", \"canonical\", \"unverified\"."
}
},
"required": [
"sourceType",
"artifactId",
"verbatim",
"extractedTextHash",
"reviewers",
"verification"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "repository-code",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"repository-code\"."
},
"citationKey": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
},
"evidenceManifestId": {
"type": "string",
"minLength": 1,
"description": "Immutable evidence-manifest identifier captured for the review run. Minimum accepted length or value is 1."
},
"evidenceManifestItemId": {
"type": "string",
"minLength": 1,
"description": "Identifier of the exact item inside the immutable evidence manifest. Minimum accepted length or value is 1."
},
"workspaceRepositoryId": {
"type": "string",
"minLength": 1,
"description": "Workspace-scoped connected repository identifier recorded in evidence provenance. Minimum accepted length or value is 1."
},
"revisionId": {
"type": "string",
"minLength": 1,
"description": "Immutable indexed repository revision identifier. Minimum accepted length or value is 1."
},
"commitSha": {
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$",
"description": "Git commit SHA pinned by the evidence manifest."
},
"blobSha": {
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$",
"description": "Git blob SHA for the cited file contents."
},
"path": {
"type": "string",
"minLength": 1,
"description": "Repository-relative source path; it never denotes an arbitrary local filesystem path. Minimum accepted length or value is 1."
},
"startLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
},
"endLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
},
"excerptSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest of the exact cited excerpt."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"coverage": {
"type": "object",
"additionalProperties": {},
"description": "Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence."
},
"reviewers": {
"type": "array",
"items": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
"minItems": 1,
"description": "Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items."
},
"verification": {
"type": "string",
"enum": [
"exact",
"canonical",
"unverified"
],
"description": "Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: \"exact\", \"canonical\", \"unverified\"."
}
},
"required": [
"sourceType",
"citationKey",
"verbatim",
"evidenceManifestId",
"evidenceManifestItemId",
"workspaceRepositoryId",
"revisionId",
"commitSha",
"blobSha",
"path",
"startLine",
"endLine",
"excerptSha256",
"route",
"coverage",
"reviewers",
"verification"
],
"additionalProperties": false
}
]
},
"description": "Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"evidenceUnavailable": {
"type": "boolean",
"description": "Whether the finding was emitted without the evidence normally required for verification; omission means evidence availability was not separately recorded. Omit the field when it does not apply; omission is distinct from an empty value."
},
"claimDisposition": {
"type": "string",
"enum": [
"verified",
"unverified"
],
"description": "Published support disposition for a code claim; omission indicates a legacy row that is treated as verified. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: \"verified\", \"unverified\"."
}
},
"required": [
"section",
"note",
"severity"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Reviewer findings associated with the selected brief version."
},
"proposals": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"sessionId": {
"type": "string",
"description": "Review-session identifier associated with this historical record; null means legacy provenance is unavailable."
},
"section": {
"type": "string",
"description": "Canonical brief section key associated with the question, finding, proposal, or decision entry."
},
"summary": {
"type": [
"string",
"null"
],
"description": "Concise safe summary intended for users and logs. A null value explicitly means no current value is available."
},
"status": {
"type": "string",
"description": "Current typed status; the schema enum or union branch lists every allowed value."
},
"decidedById": {
"type": [
"string",
"null"
],
"description": "Semel user identifier that decided this proposal; absent until a decision exists. A null value explicitly means no current value is available."
},
"decidedAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp of the proposal decision; null means undecided. A null value explicitly means no current value is available."
},
"decisionSource": {
"type": [
"string",
"null"
],
"description": "Typed provenance showing whether a proposal decision came from a user, reviewer, or system rule; null means unavailable legacy provenance. A null value explicitly means no current value is available."
},
"committedAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp when the accepted proposal was committed; null means not committed. A null value explicitly means no current value is available."
},
"sourceRound": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Review round that produced this proposal; null means no round provenance was recorded. A null value explicitly means no current value is available. The value must be an integer."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"sessionId",
"section",
"summary",
"status",
"decidedById",
"decidedAt",
"decisionSource",
"committedAt",
"sourceRound",
"createdAt"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Reviewer proposals and their decision/commit state."
},
"approvals": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"contractVersionId": {
"type": "string",
"description": "Immutable brief contract-version identifier resolved by Semel."
},
"approverId": {
"type": "string",
"description": "Semel user identifier for the human who recorded this approval decision."
},
"action": {
"type": "string",
"description": "Typed human approval action recorded in the append-only approval ledger."
},
"isStale": {
"type": "boolean",
"description": "Whether this historical approval no longer targets the current brief version."
},
"reRequestReason": {
"type": [
"string",
"null"
],
"description": "Reason a previously decided approval was requested again; null means no re-request reason applies. A null value explicitly means no current value is available."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"contractVersionId",
"approverId",
"action",
"isStale",
"reRequestReason",
"createdAt"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Append-only human approval records for brief versions."
},
"comments": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"sectionKey": {
"type": "string",
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result."
},
"anchor": {
"type": [
"string",
"null"
],
"description": "Optional structured location within a brief section for this comment; null means the comment applies to the section as a whole. A null value explicitly means no current value is available."
},
"text": {
"type": "string",
"description": "Human-authored or model-produced text for this typed record."
},
"authorId": {
"type": "string",
"description": "Semel user identifier for the comment or content author."
},
"resolvedAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp when the comment was resolved; null means unresolved. A null value explicitly means no current value is available."
},
"resolvedBy": {
"type": [
"string",
"null"
],
"description": "Semel user identifier that resolved the comment; absent until resolution. A null value explicitly means no current value is available."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"sectionKey",
"anchor",
"text",
"authorId",
"resolvedAt",
"resolvedBy",
"createdAt"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Human comments attached to brief sections or anchors."
},
"artifacts": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"artifactType": {
"type": "string",
"description": "Semel artifact classification used to select ingestion and display behavior for this source material."
},
"label": {
"type": [
"string",
"null"
],
"description": "Human-readable label displayed for this record. A null value explicitly means no current value is available."
},
"sourceUrl": {
"type": [
"string",
"null"
],
"description": "Original source URL recorded for the artifact; null means the artifact has no external source URL. A null value explicitly means no current value is available."
},
"mimeType": {
"type": [
"string",
"null"
],
"description": "Internet media type of the artifact or exported resource; null means the producer did not record one. A null value explicitly means no current value is available."
},
"sizeBytes": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Artifact size in bytes. A null value explicitly means no current value is available. The value must be an integer."
},
"ingestionStatus": {
"type": "string",
"description": "Current artifact ingestion lifecycle state; only ready artifacts may supply reviewed evidence."
},
"createdById": {
"type": [
"string",
"null"
],
"description": "Semel user identifier recorded as the initiating creator. A null value explicitly means no current value is available."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"artifactType",
"label",
"sourceUrl",
"mimeType",
"sizeBytes",
"ingestionStatus",
"createdById",
"createdAt"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Source artifacts attached to the brief."
},
"workOrders": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"description": {
"type": [
"string",
"null"
],
"description": "Human-readable explanatory text; null or omission means no description was supplied. A null value explicitly means no current value is available."
},
"position": {
"type": "integer",
"description": "Stable zero-based or configured ordering position returned by Semel. The value must be an integer."
},
"boundCriteria": {
"type": "array",
"items": {
"type": "string"
},
"description": "Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items."
},
"boundRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. An empty array explicitly means no matching items."
},
"externalTracker": {
"type": [
"string",
"null"
],
"description": "External issue-tracker provider associated with the work order; null means the work order has not been exported. A null value explicitly means no current value is available."
},
"externalUrl": {
"type": [
"string",
"null"
],
"description": "External tracker URL associated with the work order; null means no issue is linked. A null value explicitly means no current value is available."
},
"exportState": {
"type": "string",
"description": "Current external-tracker export lifecycle state for this generated work order."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"title",
"description",
"position",
"boundCriteria",
"boundRequirements",
"externalTracker",
"externalUrl",
"exportState",
"createdAt"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Materialized implementation work orders for the brief."
},
"reviewSessions": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"runId": {
"type": "string",
"description": "Review-run identifier returned by a review start, status, or cascade handoff result."
},
"status": {
"type": "string",
"description": "Current typed status; the schema enum or union branch lists every allowed value."
},
"reviewerSet": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ordered reviewer roles configured for this cascade. An empty array explicitly means no matching items."
},
"reviewedContractVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable contract-version identifier actually reviewed by this session; null means the session has not pinned one. A null value explicitly means no current value is available."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"runId",
"status",
"reviewerSet",
"reviewedContractVersionId",
"createdAt"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Review session summaries associated with the brief."
},
"shares": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"accessLevel": {
"type": "string",
"description": "Share-link access policy assigned by Semel; the enum identifies whether the recipient may only view or may also interact."
},
"sharedById": {
"type": "string",
"description": "Semel user identifier for the person who created the share."
},
"isActive": {
"type": "boolean",
"description": "Whether this share link remains active."
},
"expiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 expiration timestamp. A null value explicitly means no current value is available."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"accessLevel",
"sharedById",
"isActive",
"expiresAt",
"createdAt"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Share-link records associated with the brief."
}
},
"required": [
"versions",
"decisionHistory",
"findings",
"proposals",
"approvals",
"comments",
"artifacts",
"workOrders",
"reviewSessions",
"shares"
],
"additionalProperties": false,
"description": "First page of each durable collection associated with the brief."
},
"gateNotificationStatus": {
"anyOf": [
{
"type": "object",
"properties": {
"requestId": {
"type": "string",
"description": "Server request identifier used for support correlation; it is not an idempotency key."
},
"assignmentId": {
"type": [
"string",
"null"
],
"description": "Human gate assignment identifier created by Semel. A null value explicitly means no current value is available."
},
"contentHash": {
"type": [
"string",
"null"
],
"description": "Hash of the immutable brief content snapshot. A null value explicitly means no current value is available."
},
"notifiedAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp when the gate notification was sent; null means not sent. A null value explicitly means no current value is available."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"requestId",
"assignmentId",
"contentHash",
"notifiedAt",
"createdAt"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Latest human gate notification status; null means no notification request exists. A null value explicitly means no current value is available."
}
},
"required": [
"brief",
"collections",
"gateNotificationStatus"
],
"additionalProperties": false
}
```
**Example structured result (full-brief)**
```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
}
```
Bindings: brief from structuredContent.brief.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}"
}
],
"structuredContent": {
"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
}
}
```
Next permitted action: Show the created brief and call out any source gaps for the human.
**Example requests**
- “/semel show me everything in the checkout brief”
- “/semel open the full brief for the billing project”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `brief_list`, `brief_collection_list`, `brief_export_package`.
---
### brief_list
List the briefs this principal may reach (filtered by its project allowlist), newest-updated first. Use to find a brief before reading or editing it.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `cursor` — string; optional; minimum length 1. Opaque keyset cursor returned as nextCursor by the preceding brief_list response. Omit to read the first page.
- `limit` — integer; optional; minimum 1; maximum 200. Maximum briefs to return, as an integer from 1 through 200. Omit to use the server default.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque keyset cursor returned as nextCursor by the preceding brief_list response. Omit to read the first page."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Maximum briefs to return, as an integer from 1 through 200. Omit to use the server default."
}
},
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"limit": 50
}
```
**Binding template**
```json
{
"limit": 50
}
```
**Returns**
- `briefs` — array; required. Brief summaries reachable by the authenticated principal. An empty array explicitly means no matching items.
- `briefs[]` — object; required.
- `briefs[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `briefs[].projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `briefs[].title` — string; required. Human-readable title displayed in Semel.
- `briefs[].state` — string; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `briefs[].versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `briefs[].updatedAt` — string; required. RFC 3339 timestamp when this record was last updated.
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"briefs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"state": {
"type": "string",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
},
"updatedAt": {
"type": "string",
"description": "RFC 3339 timestamp when this record was last updated."
}
},
"required": [
"id",
"projectId",
"title",
"state",
"versionNum",
"updatedAt"
],
"additionalProperties": false
},
"description": "Brief summaries reachable by the authenticated principal. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"briefs",
"nextCursor"
],
"additionalProperties": false
}
```
**Example structured result (brief-list)**
```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
}
```
Bindings: briefId from structuredContent.briefs[0].id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}"
}
],
"structuredContent": {
"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
}
}
```
Next permitted action: Select an exact brief or ask the human to disambiguate.
**Example requests**
- “/semel list my briefs”
- “/semel what briefs are there in progress?”
Errors: universal authentication and validation errors only.
Related operations: `brief_get_full`, `brief_collection_list`.
---
### brief_update
Edit a brief's title and content, minting a new immutable contract version whenever the content changes. Use to revise requirements or work orders on an existing brief; pass ifVersionNum to guard against a concurrent edit.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `content` — object; required. Complete replacement brief document for agent writes, limited to 262144 serialized bytes. Known sections use the canonical nested shapes; unknown metadata and _draft remain round-trippable.
- `content.goal` — string; optional; maximum length 4000. Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.userPersonaContext` — string; optional; maximum length 4000. User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.scope` — string; optional; maximum length 4000. Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.outOfScope` — string; optional; maximum length 4000. Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.requirements` — array; optional; maximum items 50. Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.requirements[]` — string; required; minimum length 1; maximum length 1000.
- `content.edgeCases` — array; optional; maximum items 50. Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.edgeCases[]` — string; required; minimum length 1; maximum length 1000.
- `content.acceptanceCriteria` — array; optional; maximum items 50. Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.acceptanceCriteria[]` — object; required.
- `content.acceptanceCriteria[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.acceptanceCriteria[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.acceptanceCriteria[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.acceptanceCriteria[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.acceptanceCriteria[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `content.acceptanceCriteria[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `content.rolesPermissions` — array; optional; maximum items 50. Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.rolesPermissions[]` — string; required; minimum length 1; maximum length 1000.
- `content.states` — array; optional; maximum items 50. User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.states[]` — string; required; minimum length 1; maximum length 1000.
- `content.productSolution` — string; optional; maximum length 4000. Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.technicalSolution` — string; optional; maximum length 4000. Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.dataModelImplications` — string; optional; maximum length 4000. Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.architectureAssumptions` — string; optional; maximum length 4000. Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.design` — string; optional; maximum length 4000. Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.testingQaChecklist` — array; optional; maximum items 50. Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testingQaChecklist[]` — object; required.
- `content.testingQaChecklist[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.testingQaChecklist[].checked` — boolean; required. Whether this QA checklist item is currently complete.
- `content.testingQaChecklist[].addedBy` — string; optional; maximum length 200. Actor label that added the QA item; omission means legacy or unavailable attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.testingQaChecklist[].checkedBy` — string; optional; maximum length 200. Actor label that last checked the item; omission means it has no check attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.testingQaChecklist[].checkedAt` — string; optional; format date-time. RFC 3339 timestamp when the item was checked; omission means it is unchecked or legacy data. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string.
- `content.testPlanUnit` — array; optional; maximum items 50. Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanUnit[]` — string; required; minimum length 1; maximum length 1000.
- `content.testPlanIntegration` — array; optional; maximum items 50. Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanIntegration[]` — string; required; minimum length 1; maximum length 1000.
- `content.testPlanUiUx` — array; optional; maximum items 50. Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanUiUx[]` — string; required; minimum length 1; maximum length 1000.
- `content.openQuestions` — array; optional; maximum items 50. Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.openQuestions[]` — string; required; minimum length 1; maximum length 1000.
- `content.generatedTickets` — array; optional; maximum items 50. Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.generatedTickets[]` — object; required.
- `content.generatedTickets[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.generatedTickets[].title` — string; required; minimum length 1; maximum length 500. Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
- `content.generatedTickets[].description` — JSON value; required. Human-readable explanatory text; null or omission means no description was supplied. A null value explicitly means no current value is available. Maximum accepted length or value is 10000.
- `content.generatedTickets[].description (anyOf branch 1)` — string; required; maximum length 10000.
- `content.generatedTickets[].description (anyOf branch 2)` — null; required.
- `content.generatedTickets[].boundCriteria` — array; required; maximum items 50. Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items.
- `content.generatedTickets[].boundCriteria[]` — string; required; minimum length 1; maximum length 200.
- `content.generatedTickets[].boundRequirements` — array; optional; maximum items 50. Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.generatedTickets[].boundRequirements[]` — string; required; minimum length 1; maximum length 200.
- `content.requiredEvidence` — array; optional; maximum items 50. Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.requiredEvidence[]` — object; required.
- `content.requiredEvidence[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.requiredEvidence[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.requiredEvidence[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.requiredEvidence[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.requiredEvidence[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `content.requiredEvidence[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `content.decisions` — array; optional; maximum items 50. Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.decisions[]` — object; required.
- `content.decisions[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.decisions[].source` — string; optional; maximum length 1000. Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000.
- `content.decisions[].stated` — boolean; optional. Whether the decision was explicitly stated rather than inferred; omission means unknown legacy provenance. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.sourceArtifactLinks` — array; optional; maximum items 50. Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.sourceArtifactLinks[]` — object; required.
- `content.sourceArtifactLinks[].label` — string; required; minimum length 1; maximum length 1000. Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive.
- `content.sourceArtifactLinks[].kind` — string; optional; maximum length 200. Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.sourceArtifactLinks[].read` — boolean; optional. Whether the referenced source artifact was read when the brief snapshot was produced. Omit the field when it does not apply; omission is distinct from an empty value.
- `title` — string; optional; minimum length 1; maximum length 500. Human-readable title displayed in Semel. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 500, inclusive.
- `ifVersionNum` — integer; optional. Optional optimistic precondition using the current brief contract version number. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `clearDraft` — boolean; optional. When true, explicitly clears draft state after the complete document update; omission leaves it unchanged. Omit the field when it does not apply; omission is distinct from an empty value.
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"content": {
"type": "object",
"properties": {
"goal": {
"type": "string",
"maxLength": 4000,
"description": "Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"userPersonaContext": {
"type": "string",
"maxLength": 4000,
"description": "User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"scope": {
"type": "string",
"maxLength": 4000,
"description": "Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"outOfScope": {
"type": "string",
"maxLength": 4000,
"description": "Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"requirements": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"edgeCases": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"acceptanceCriteria": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"implementation": {
"type": "boolean",
"description": "Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value."
},
"manualEvidence": {
"type": "object",
"properties": {
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive."
},
"evidencePath": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive."
}
},
"required": [
"rationale",
"evidencePath"
],
"additionalProperties": false,
"description": "Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"id",
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"rolesPermissions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"states": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"productSolution": {
"type": "string",
"maxLength": 4000,
"description": "Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"technicalSolution": {
"type": "string",
"maxLength": 4000,
"description": "Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"dataModelImplications": {
"type": "string",
"maxLength": 4000,
"description": "Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"architectureAssumptions": {
"type": "string",
"maxLength": 4000,
"description": "Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"design": {
"type": "string",
"maxLength": 4000,
"description": "Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"testingQaChecklist": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"checked": {
"type": "boolean",
"description": "Whether this QA checklist item is currently complete."
},
"addedBy": {
"type": "string",
"maxLength": 200,
"description": "Actor label that added the QA item; omission means legacy or unavailable attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"checkedBy": {
"type": "string",
"maxLength": 200,
"description": "Actor label that last checked the item; omission means it has no check attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"checkedAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp when the item was checked; omission means it is unchecked or legacy data. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string."
}
},
"required": [
"text",
"checked"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanUnit": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanIntegration": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanUiUx": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"openQuestions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"generatedTickets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive."
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 10000
},
{
"type": "null"
}
],
"description": "Human-readable explanatory text; null or omission means no description was supplied. A null value explicitly means no current value is available. Maximum accepted length or value is 10000."
},
"boundCriteria": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
},
"maxItems": 50,
"description": "Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items."
},
"boundRequirements": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
},
"maxItems": 50,
"description": "Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"required": [
"id",
"title",
"description",
"boundCriteria"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"requiredEvidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"implementation": {
"type": "boolean",
"description": "Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value."
},
"manualEvidence": {
"type": "object",
"properties": {
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive."
},
"evidencePath": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive."
}
},
"required": [
"rationale",
"evidencePath"
],
"additionalProperties": false,
"description": "Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"id",
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"decisions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"source": {
"type": "string",
"maxLength": 1000,
"description": "Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000."
},
"stated": {
"type": "boolean",
"description": "Whether the decision was explicitly stated rather than inferred; omission means unknown legacy provenance. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"sourceArtifactLinks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive."
},
"kind": {
"type": "string",
"maxLength": 200,
"description": "Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"read": {
"type": "boolean",
"description": "Whether the referenced source artifact was read when the brief snapshot was produced. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"label"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"additionalProperties": true,
"description": "Complete replacement brief document for agent writes, limited to 262144 serialized bytes. Known sections use the canonical nested shapes; unknown metadata and _draft remain round-trippable."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Human-readable title displayed in Semel. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 500, inclusive."
},
"ifVersionNum": {
"type": "integer",
"description": "Optional optimistic precondition using the current brief contract version number. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"clearDraft": {
"type": "boolean",
"description": "When true, explicitly clears draft state after the complete document update; omission leaves it unchanged. Omit the field when it does not apply; omission is distinct from an empty value."
},
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"content",
"briefId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"title": "Retry-safe checkout",
"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": "recipe-brief-update-v1"
}
```
**Binding template**
```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}}"
}
```
**Returns**
- `brief` — object; required. Current brief record returned by the operation.
- `brief.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `brief.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `brief.title` — string; required. Human-readable title displayed in Semel.
- `brief.state` — "drafting" | "in_review" | "baselined" | "in_development" | "checked" | "superseded" | "closed"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "drafting", "in_review", "baselined", "in_development", "checked", "superseded", "closed".
- `brief.currentVersionHash` — string | null; required. Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available.
- `brief.content` — object; required. Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
- `brief.content{key}` — JSON value; optional.
- `brief.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `brief.createdNewVersion` — boolean; required. Whether the write changed canonical content and minted a new immutable brief version.
- `brief.staledApprovals` — integer; required. Number of prior approval rows made stale by this content change. The value must be an integer.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"brief": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"state": {
"type": "string",
"enum": [
"drafting",
"in_review",
"baselined",
"in_development",
"checked",
"superseded",
"closed"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"drafting\", \"in_review\", \"baselined\", \"in_development\", \"checked\", \"superseded\", \"closed\"."
},
"currentVersionHash": {
"type": [
"string",
"null"
],
"description": "Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available."
},
"content": {
"type": "object",
"additionalProperties": {},
"description": "Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
},
"createdNewVersion": {
"type": "boolean",
"description": "Whether the write changed canonical content and minted a new immutable brief version."
},
"staledApprovals": {
"type": "integer",
"description": "Number of prior approval rows made stale by this content change. The value must be an integer."
}
},
"required": [
"id",
"projectId",
"title",
"state",
"currentVersionHash",
"content",
"versionNum",
"createdNewVersion",
"staledApprovals"
],
"additionalProperties": false,
"description": "Current brief record returned by the operation."
}
},
"required": [
"brief"
],
"additionalProperties": false
}
```
**Example structured result (brief-updated)**
```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
}
}
```
Bindings: versionNum from structuredContent.brief.versionNum.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}"
}
],
"structuredContent": {
"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
}
}
}
```
Next permitted action: Inspect createdNewVersion and the returned current version.
**Example requests**
- “/semel update the checkout brief with the new acceptance criteria”
- “/semel revise the requirements on this brief”
Errors: `PROJECT_ACCESS_DENIED`, `BRIEF_VERSION_CONFLICT`.
Related operations: `brief_create`, `brief_get_full`, `brief_checklist_update`.
---
### project_codebase_link
Turn on one already-connected codebase for a project after the agent inventories plausible repositories and the user confirms the proposed scope.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `repositoryId` — string; required; minimum length 1. Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"repositoryId": {
"type": "string",
"minLength": 1,
"description": "Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"projectId",
"repositoryId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"repositoryId": "repo_fixture_throughline",
"idempotencyKey": "recipe-project-codebase-link-v1"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"repositoryId": "{{repositoryId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `projectCodebase` — object; required. Project-to-repository link returned by the operation.
- `projectCodebase.projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `projectCodebase.repositoryId` — string; required; minimum length 1. Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
- `projectCodebase.linked` — constant true; required. Whether the repository is currently linked to the project. This branch always uses true.
- `projectCodebase.newlyLinked` — boolean; required. Whether this call created the project-to-repository link instead of replaying an existing link.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"projectCodebase": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"repositoryId": {
"type": "string",
"minLength": 1,
"description": "Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1."
},
"linked": {
"type": "boolean",
"const": true,
"description": "Whether the repository is currently linked to the project. This branch always uses true."
},
"newlyLinked": {
"type": "boolean",
"description": "Whether this call created the project-to-repository link instead of replaying an existing link."
}
},
"required": [
"projectId",
"repositoryId",
"linked",
"newlyLinked"
],
"additionalProperties": false,
"description": "Project-to-repository link returned by the operation."
}
},
"required": [
"projectCodebase"
],
"additionalProperties": false
}
```
**Example structured result (codebase-linked)**
```json
{
"projectCodebase": {
"projectId": "prj_fixture_checkout",
"repositoryId": "repo_fixture_throughline",
"linked": true,
"newlyLinked": true
}
}
```
Bindings: linked from structuredContent.projectCodebase.linked.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"projectCodebase\":{\"projectId\":\"prj_fixture_checkout\",\"repositoryId\":\"repo_fixture_throughline\",\"linked\":true,\"newlyLinked\":true}}"
}
],
"structuredContent": {
"projectCodebase": {
"projectId": "prj_fixture_checkout",
"repositoryId": "repo_fixture_throughline",
"linked": true,
"newlyLinked": true
}
}
}
```
Next permitted action: Proceed with the confirmed repository in project scope.
**Example requests**
- “/semel add the throughlineos codebase to this project”
- “/semel use this connected repository as project evidence”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `project_codebases_list`, `project_context_sources_list`, `brief_create`.
---
### project_codebases_list
List connected workspace codebases, including unselected ones, and show which are currently in a project so the user can confirm repository scope before brief creation or review. Follow nextCursor until it is null before treating the inventory as complete.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `cursor` — string; optional; minimum length 1. Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
- `limit` — integer; optional; minimum 1; maximum 200. Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer."
}
},
"required": [
"projectId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"limit": 50
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"limit": 50
}
```
**Returns**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `codebases` — array; required. Connected repository options visible to this project actor. An empty array explicitly means no matching items.
- `codebases[]` — object; required.
- `codebases[].repositoryId` — string; required; minimum length 1. Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
- `codebases[].owner` — string; required; minimum length 1. Repository owner or organization slug returned by the connected source provider; pair it with repository name. Minimum accepted length or value is 1.
- `codebases[].name` — string; required; minimum length 1. Human-readable name displayed in Semel. Minimum accepted length or value is 1.
- `codebases[].trackingBranch` — string; required; minimum length 1. Repository branch configured for indexing and review evidence. Minimum accepted length or value is 1.
- `codebases[].selected` — boolean; required. Whether this connected repository is selected for the project.
- `codebases[].selectionStatus` — "available" | "access_unavailable" | "removing"; required. Current availability state of a connected repository for project selection; unavailable or removing repositories cannot be newly selected. Allowed values: "available", "access_unavailable", "removing".
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"codebases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"repositoryId": {
"type": "string",
"minLength": 1,
"description": "Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1."
},
"owner": {
"type": "string",
"minLength": 1,
"description": "Repository owner or organization slug returned by the connected source provider; pair it with repository name. Minimum accepted length or value is 1."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable name displayed in Semel. Minimum accepted length or value is 1."
},
"trackingBranch": {
"type": "string",
"minLength": 1,
"description": "Repository branch configured for indexing and review evidence. Minimum accepted length or value is 1."
},
"selected": {
"type": "boolean",
"description": "Whether this connected repository is selected for the project."
},
"selectionStatus": {
"type": "string",
"enum": [
"available",
"access_unavailable",
"removing"
],
"description": "Current availability state of a connected repository for project selection; unavailable or removing repositories cannot be newly selected. Allowed values: \"available\", \"access_unavailable\", \"removing\"."
}
},
"required": [
"repositoryId",
"owner",
"name",
"trackingBranch",
"selected",
"selectionStatus"
],
"additionalProperties": false
},
"description": "Connected repository options visible to this project actor. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"projectId",
"codebases",
"nextCursor"
],
"additionalProperties": false
}
```
**Example structured result (codebase-inventory)**
```json
{
"projectId": "prj_fixture_checkout",
"codebases": [
{
"repositoryId": "repo_fixture_throughline",
"owner": "throughline",
"name": "throughlineos",
"trackingBranch": "main",
"selected": false,
"selectionStatus": "available"
}
],
"nextCursor": null
}
```
Bindings: codebases from structuredContent.codebases.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"projectId\":\"prj_fixture_checkout\",\"codebases\":[{\"repositoryId\":\"repo_fixture_throughline\",\"owner\":\"throughline\",\"name\":\"throughlineos\",\"trackingBranch\":\"main\",\"selected\":false,\"selectionStatus\":\"available\"}],\"nextCursor\":null}"
}
],
"structuredContent": {
"projectId": "prj_fixture_checkout",
"codebases": [
{
"repositoryId": "repo_fixture_throughline",
"owner": "throughline",
"name": "throughlineos",
"trackingBranch": "main",
"selected": false,
"selectionStatus": "available"
}
],
"nextCursor": null
}
}
```
Next permitted action: Follow nextCursor until null before proposing repository scope.
**Example requests**
- “/semel which connected codebases may be relevant to this project?”
- “/semel show the selected and available repositories for this project”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `project_get`, `project_codebase_link`, `brief_create`.
---
### project_context_evidence_get
Fetch the bounded excerpt or statement a search result cited, preserving its source/version/provenance.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `citationHandle` — string; required; minimum length 1. Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"citationHandle": {
"type": "string",
"minLength": 1,
"description": "Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1."
}
},
"required": [
"projectId",
"citationHandle"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"citationHandle": "ctx1.repository.fixture"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"citationHandle": "{{citationHandle}}"
}
```
**Returns**
- `citation` — JSON value; required. Durable citation metadata for the returned evidence excerpt.
- `citation (anyOf branch 1)` — object; required.
- `citation (anyOf branch 1).citationHandle` — string; required; minimum length 1. Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.
- `citation (anyOf branch 1).sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `citation (anyOf branch 1).provenance` — "semel_indexed" | "local_harness"; required. Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".
- `citation (anyOf branch 1).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `citation (anyOf branch 1).score` — number; required. Retrieval relevance score used to order evidence results.
- `citation (anyOf branch 1).kind` — constant "repository"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "repository".
- `citation (anyOf branch 1).repository` — object; required. Connected repository identity and provider metadata.
- `citation (anyOf branch 1).repository.owner` — string; required. Repository owner or organization slug returned by the connected source provider; pair it with repository name.
- `citation (anyOf branch 1).repository.name` — string; required. Human-readable name displayed in Semel.
- `citation (anyOf branch 1).revision` — object; required. Indexed repository revision used for this evidence result.
- `citation (anyOf branch 1).revision.commitSha` — string; required. Git commit SHA pinned by the evidence manifest.
- `citation (anyOf branch 1).revision.revisionId` — string; required. Immutable indexed repository revision identifier.
- `citation (anyOf branch 1).path` — string; required. Repository-relative source path; it never denotes an arbitrary local filesystem path.
- `citation (anyOf branch 1).startLine` — integer; required. One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `citation (anyOf branch 1).endLine` — integer; required. One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `citation (anyOf branch 2)` — object; required.
- `citation (anyOf branch 2).citationHandle` — string; required; minimum length 1. Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.
- `citation (anyOf branch 2).sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `citation (anyOf branch 2).provenance` — "semel_indexed" | "local_harness"; required. Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".
- `citation (anyOf branch 2).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `citation (anyOf branch 2).score` — number; required. Retrieval relevance score used to order evidence results.
- `citation (anyOf branch 2).kind` — constant "knowledge_collection"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "knowledge_collection".
- `citation (anyOf branch 2).collection` — object; required. Named durable brief collection to page; use one of the documented enum values.
- `citation (anyOf branch 2).collection.scopeKind` — "workspace" | "project" | "repository"; required. Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: "workspace", "project", "repository".
- `citation (anyOf branch 2).collection.scopeId` — string; required. Stable identifier of the repository scope that produced this evidence.
- `citation (anyOf branch 2).collection.snapshotId` — string; required. Immutable export snapshot identifier used to reproduce the exported brief state.
- `citation (anyOf branch 2).collection.version` — integer; required; minimum 0. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer.
- `citation (anyOf branch 2).sectionKey` — string; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result.
- `citation (anyOf branch 2).statementIndex` — integer; required; minimum 0. Zero-based statement position within the cited brief section. Minimum accepted length or value is 0. The value must be an integer.
- `excerpt` — string; required. Bounded source excerpt authorized for this result; an empty string means no excerpt text was returned.
- `truncated` — boolean; required. Whether the returned excerpt was shortened to the response limit.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"citation": {
"anyOf": [
{
"type": "object",
"properties": {
"citationHandle": {
"type": "string",
"minLength": 1,
"description": "Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1."
},
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"provenance": {
"type": "string",
"enum": [
"semel_indexed",
"local_harness"
],
"description": "Immutable repository revision and evidence-source provenance. Allowed values: \"semel_indexed\", \"local_harness\"."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"score": {
"type": "number",
"description": "Retrieval relevance score used to order evidence results."
},
"kind": {
"type": "string",
"const": "repository",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"repository\"."
},
"repository": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"description": "Repository owner or organization slug returned by the connected source provider; pair it with repository name."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
}
},
"required": [
"owner",
"name"
],
"additionalProperties": false,
"description": "Connected repository identity and provider metadata."
},
"revision": {
"type": "object",
"properties": {
"commitSha": {
"type": "string",
"description": "Git commit SHA pinned by the evidence manifest."
},
"revisionId": {
"type": "string",
"description": "Immutable indexed repository revision identifier."
}
},
"required": [
"commitSha",
"revisionId"
],
"additionalProperties": false,
"description": "Indexed repository revision used for this evidence result."
},
"path": {
"type": "string",
"description": "Repository-relative source path; it never denotes an arbitrary local filesystem path."
},
"startLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
},
"endLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"citationHandle",
"sourceId",
"provenance",
"route",
"score",
"kind",
"repository",
"revision",
"path",
"startLine",
"endLine"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"citationHandle": {
"type": "string",
"minLength": 1,
"description": "Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1."
},
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"provenance": {
"type": "string",
"enum": [
"semel_indexed",
"local_harness"
],
"description": "Immutable repository revision and evidence-source provenance. Allowed values: \"semel_indexed\", \"local_harness\"."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"score": {
"type": "number",
"description": "Retrieval relevance score used to order evidence results."
},
"kind": {
"type": "string",
"const": "knowledge_collection",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"knowledge_collection\"."
},
"collection": {
"type": "object",
"properties": {
"scopeKind": {
"type": "string",
"enum": [
"workspace",
"project",
"repository"
],
"description": "Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: \"workspace\", \"project\", \"repository\"."
},
"scopeId": {
"type": "string",
"description": "Stable identifier of the repository scope that produced this evidence."
},
"snapshotId": {
"type": "string",
"description": "Immutable export snapshot identifier used to reproduce the exported brief state."
},
"version": {
"type": "integer",
"minimum": 0,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"scopeKind",
"scopeId",
"snapshotId",
"version"
],
"additionalProperties": false,
"description": "Named durable brief collection to page; use one of the documented enum values."
},
"sectionKey": {
"type": "string",
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result."
},
"statementIndex": {
"type": "integer",
"minimum": 0,
"description": "Zero-based statement position within the cited brief section. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"citationHandle",
"sourceId",
"provenance",
"route",
"score",
"kind",
"collection",
"sectionKey",
"statementIndex"
],
"additionalProperties": false
}
],
"description": "Durable citation metadata for the returned evidence excerpt."
},
"excerpt": {
"type": "string",
"description": "Bounded source excerpt authorized for this result; an empty string means no excerpt text was returned."
},
"truncated": {
"type": "boolean",
"description": "Whether the returned excerpt was shortened to the response limit."
}
},
"required": [
"citation",
"excerpt",
"truncated"
],
"additionalProperties": false
}
```
**Example structured result (bounded-evidence)**
```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
}
```
Bindings: excerpt from structuredContent.excerpt.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}"
}
],
"structuredContent": {
"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
}
}
```
Next permitted action: Cite the returned provenance/revision/path and disclose truncated when true.
**Example requests**
- “show me the code that matched that last search result”
Errors: `AUTHORIZATION_SCOPE_MISSING`, `PROJECT_ACCESS_DENIED`.
Related operations: `project_context_search`.
---
### project_context_search
Search one or more already-listed context sources for evidence relevant to the active reviewer skill’s question.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `sourceIds` — array; required; minimum items 1; maximum items 5. Source identifiers returned by project_context_sources_list that bound this search. An empty array explicitly means no matching items.
- `sourceIds[]` — string; required; minimum length 1.
- `query` — string; required; minimum length 1; maximum length 500. Natural-language or code search query evaluated only against the selected project context sources. Accepted length or value is 1 through 500, inclusive.
- `limit` — integer; optional; minimum 1; maximum 200. Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"sourceIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"maxItems": 5,
"description": "Source identifiers returned by project_context_sources_list that bound this search. An empty array explicitly means no matching items."
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Natural-language or code search query evaluated only against the selected project context sources. Accepted length or value is 1 through 500, inclusive."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer."
}
},
"required": [
"projectId",
"sourceIds",
"query"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"sourceIds": [
"src_fixture_repository"
],
"query": "payment retry idempotency",
"limit": 20
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"sourceIds": [
"{{sourceId}}"
],
"query": "payment retry idempotency",
"limit": 20
}
```
**Returns**
- `results` — array; required. Ranked evidence matches for the requested sources and query. An empty array explicitly means no matching items.
- `results[]` — object; required.
- `results[].citation` — JSON value; required. Durable citation metadata for the returned evidence excerpt.
- `results[].citation (anyOf branch 1)` — object; required.
- `results[].citation (anyOf branch 1).citationHandle` — string; required; minimum length 1. Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.
- `results[].citation (anyOf branch 1).sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `results[].citation (anyOf branch 1).provenance` — "semel_indexed" | "local_harness"; required. Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".
- `results[].citation (anyOf branch 1).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `results[].citation (anyOf branch 1).score` — number; required. Retrieval relevance score used to order evidence results.
- `results[].citation (anyOf branch 1).kind` — constant "repository"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "repository".
- `results[].citation (anyOf branch 1).repository` — object; required. Connected repository identity and provider metadata.
- `results[].citation (anyOf branch 1).repository.owner` — string; required. Repository owner or organization slug returned by the connected source provider; pair it with repository name.
- `results[].citation (anyOf branch 1).repository.name` — string; required. Human-readable name displayed in Semel.
- `results[].citation (anyOf branch 1).revision` — object; required. Indexed repository revision used for this evidence result.
- `results[].citation (anyOf branch 1).revision.commitSha` — string; required. Git commit SHA pinned by the evidence manifest.
- `results[].citation (anyOf branch 1).revision.revisionId` — string; required. Immutable indexed repository revision identifier.
- `results[].citation (anyOf branch 1).path` — string; required. Repository-relative source path; it never denotes an arbitrary local filesystem path.
- `results[].citation (anyOf branch 1).startLine` — integer; required. One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `results[].citation (anyOf branch 1).endLine` — integer; required. One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `results[].citation (anyOf branch 2)` — object; required.
- `results[].citation (anyOf branch 2).citationHandle` — string; required; minimum length 1. Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.
- `results[].citation (anyOf branch 2).sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `results[].citation (anyOf branch 2).provenance` — "semel_indexed" | "local_harness"; required. Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".
- `results[].citation (anyOf branch 2).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `results[].citation (anyOf branch 2).score` — number; required. Retrieval relevance score used to order evidence results.
- `results[].citation (anyOf branch 2).kind` — constant "knowledge_collection"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "knowledge_collection".
- `results[].citation (anyOf branch 2).collection` — object; required. Named durable brief collection to page; use one of the documented enum values.
- `results[].citation (anyOf branch 2).collection.scopeKind` — "workspace" | "project" | "repository"; required. Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: "workspace", "project", "repository".
- `results[].citation (anyOf branch 2).collection.scopeId` — string; required. Stable identifier of the repository scope that produced this evidence.
- `results[].citation (anyOf branch 2).collection.snapshotId` — string; required. Immutable export snapshot identifier used to reproduce the exported brief state.
- `results[].citation (anyOf branch 2).collection.version` — integer; required; minimum 0. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer.
- `results[].citation (anyOf branch 2).sectionKey` — string; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result.
- `results[].citation (anyOf branch 2).statementIndex` — integer; required; minimum 0. Zero-based statement position within the cited brief section. Minimum accepted length or value is 0. The value must be an integer.
- `searchedSources` — array; required. Source identifiers actually searched after authorization and availability checks. An empty array explicitly means no matching items.
- `searchedSources[]` — object; required.
- `searchedSources[].sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `searchedSources[].route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `searchedSources[].resultCount` — integer; required; minimum 0. Number of evidence matches returned in this response. Minimum accepted length or value is 0. The value must be an integer.
- `searchedSources[].abstained` — boolean; required. Whether search deliberately returned no evidence because trust or relevance requirements were unmet.
- `searchedSources[].abstentionReason` — string; optional. Safe explanation for why evidence search abstained; null means it returned normally. Omit the field when it does not apply; omission is distinct from an empty value.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"citation": {
"anyOf": [
{
"type": "object",
"properties": {
"citationHandle": {
"type": "string",
"minLength": 1,
"description": "Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1."
},
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"provenance": {
"type": "string",
"enum": [
"semel_indexed",
"local_harness"
],
"description": "Immutable repository revision and evidence-source provenance. Allowed values: \"semel_indexed\", \"local_harness\"."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"score": {
"type": "number",
"description": "Retrieval relevance score used to order evidence results."
},
"kind": {
"type": "string",
"const": "repository",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"repository\"."
},
"repository": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"description": "Repository owner or organization slug returned by the connected source provider; pair it with repository name."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
}
},
"required": [
"owner",
"name"
],
"additionalProperties": false,
"description": "Connected repository identity and provider metadata."
},
"revision": {
"type": "object",
"properties": {
"commitSha": {
"type": "string",
"description": "Git commit SHA pinned by the evidence manifest."
},
"revisionId": {
"type": "string",
"description": "Immutable indexed repository revision identifier."
}
},
"required": [
"commitSha",
"revisionId"
],
"additionalProperties": false,
"description": "Indexed repository revision used for this evidence result."
},
"path": {
"type": "string",
"description": "Repository-relative source path; it never denotes an arbitrary local filesystem path."
},
"startLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
},
"endLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"citationHandle",
"sourceId",
"provenance",
"route",
"score",
"kind",
"repository",
"revision",
"path",
"startLine",
"endLine"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"citationHandle": {
"type": "string",
"minLength": 1,
"description": "Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1."
},
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"provenance": {
"type": "string",
"enum": [
"semel_indexed",
"local_harness"
],
"description": "Immutable repository revision and evidence-source provenance. Allowed values: \"semel_indexed\", \"local_harness\"."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"score": {
"type": "number",
"description": "Retrieval relevance score used to order evidence results."
},
"kind": {
"type": "string",
"const": "knowledge_collection",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"knowledge_collection\"."
},
"collection": {
"type": "object",
"properties": {
"scopeKind": {
"type": "string",
"enum": [
"workspace",
"project",
"repository"
],
"description": "Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: \"workspace\", \"project\", \"repository\"."
},
"scopeId": {
"type": "string",
"description": "Stable identifier of the repository scope that produced this evidence."
},
"snapshotId": {
"type": "string",
"description": "Immutable export snapshot identifier used to reproduce the exported brief state."
},
"version": {
"type": "integer",
"minimum": 0,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"scopeKind",
"scopeId",
"snapshotId",
"version"
],
"additionalProperties": false,
"description": "Named durable brief collection to page; use one of the documented enum values."
},
"sectionKey": {
"type": "string",
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result."
},
"statementIndex": {
"type": "integer",
"minimum": 0,
"description": "Zero-based statement position within the cited brief section. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"citationHandle",
"sourceId",
"provenance",
"route",
"score",
"kind",
"collection",
"sectionKey",
"statementIndex"
],
"additionalProperties": false
}
],
"description": "Durable citation metadata for the returned evidence excerpt."
}
},
"required": [
"citation"
],
"additionalProperties": false
},
"description": "Ranked evidence matches for the requested sources and query. An empty array explicitly means no matching items."
},
"searchedSources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"resultCount": {
"type": "integer",
"minimum": 0,
"description": "Number of evidence matches returned in this response. Minimum accepted length or value is 0. The value must be an integer."
},
"abstained": {
"type": "boolean",
"description": "Whether search deliberately returned no evidence because trust or relevance requirements were unmet."
},
"abstentionReason": {
"type": "string",
"description": "Safe explanation for why evidence search abstained; null means it returned normally. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sourceId",
"route",
"resultCount",
"abstained"
],
"additionalProperties": false
},
"description": "Source identifiers actually searched after authorization and availability checks. An empty array explicitly means no matching items."
}
},
"required": [
"results",
"searchedSources"
],
"additionalProperties": false
}
```
**Example structured result (search-results)**
```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
}
]
}
```
Bindings: citationHandle from structuredContent.results[0].citation.citationHandle.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}]}"
}
],
"structuredContent": {
"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
}
]
}
}
```
Next permitted action: Preserve the returned citationHandle exactly; inspect abstention metadata when no result exists.
**Example requests**
- “search the indexed repository for the retry handler”
- “have we recorded any prior decisions about pricing?”
Errors: `AUTHORIZATION_SCOPE_MISSING`, `PROJECT_ACCESS_DENIED`.
Related operations: `project_context_sources_list`, `project_context_evidence_get`.
---
### project_context_sources_list
Discover which repositories and knowledge collections this project can search before claiming absence.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `cursor` — string; optional; minimum length 1. Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
- `limit` — integer; optional; minimum 1; maximum 200. Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer."
}
},
"required": [
"projectId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"limit": 50
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"limit": 50
}
```
**Returns**
- `sources` — array; required. Connected repository sources currently authorized for this project. An empty array explicitly means no matching items.
- `sources[]` — object; required.
- `sources[].sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `sources[].kind` — "repository" | "knowledge_collection"; required. Discriminator identifying the typed variant represented by this object. Allowed values: "repository", "knowledge_collection".
- `sources[].label` — string; required. Human-readable label displayed for this record.
- `sources[].scope` — object; required. Work explicitly included in this brief.
- `sources[].scope.kind` — "workspace" | "project" | "repository"; required. Discriminator identifying the typed variant represented by this object. Allowed values: "workspace", "project", "repository".
- `sources[].scope.id` — string | null; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. A null value explicitly means no current value is available.
- `sources[].repository` — object; optional. Connected repository identity and provider metadata. Omit the field when it does not apply; omission is distinct from an empty value.
- `sources[].repository.owner` — string; required. Repository owner or organization slug returned by the connected source provider; pair it with repository name.
- `sources[].repository.name` — string; required. Human-readable name displayed in Semel.
- `sources[].repository.defaultBranch` — string; required. Repository default branch reported by the connected provider.
- `sources[].repository.trackingBranch` — string; required. Repository branch configured for indexing and review evidence.
- `sources[].repository.commitSha` — string | null; required. Git commit SHA pinned by the evidence manifest. A null value explicitly means no current value is available.
- `sources[].repository.revisionId` — string | null; required. Immutable indexed repository revision identifier. A null value explicitly means no current value is available.
- `sources[].collection` — object; optional. Named durable brief collection to page; use one of the documented enum values. Omit the field when it does not apply; omission is distinct from an empty value.
- `sources[].collection.scopeKind` — "workspace" | "project" | "repository"; required. Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: "workspace", "project", "repository".
- `sources[].collection.version` — integer; required; minimum 0. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer.
- `sources[].collection.snapshotId` — string; required. Immutable export snapshot identifier used to reproduce the exported brief state.
- `sources[].status` — "ready" | "syncing" | "stale" | "degraded" | "unavailable"; required. Current typed status; the schema enum or union branch lists every allowed value. Allowed values: "ready", "syncing", "stale", "degraded", "unavailable".
- `sources[].freshness` — object; required. Repository indexing freshness and configured tracking branch.
- `sources[].freshness.asOf` — string | null; required. RFC 3339 timestamp describing evidence freshness. A null value explicitly means no current value is available.
- `sources[].freshness.coverage` — "full" | "partial" | "unknown"; required. Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence. Allowed values: "full", "partial", "unknown".
- `sources[].provenance` — "semel_indexed" | "local_harness"; required. Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"kind": {
"type": "string",
"enum": [
"repository",
"knowledge_collection"
],
"description": "Discriminator identifying the typed variant represented by this object. Allowed values: \"repository\", \"knowledge_collection\"."
},
"label": {
"type": "string",
"description": "Human-readable label displayed for this record."
},
"scope": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"workspace",
"project",
"repository"
],
"description": "Discriminator identifying the typed variant represented by this object. Allowed values: \"workspace\", \"project\", \"repository\"."
},
"id": {
"type": [
"string",
"null"
],
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. A null value explicitly means no current value is available."
}
},
"required": [
"kind",
"id"
],
"additionalProperties": false,
"description": "Work explicitly included in this brief."
},
"repository": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"description": "Repository owner or organization slug returned by the connected source provider; pair it with repository name."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"defaultBranch": {
"type": "string",
"description": "Repository default branch reported by the connected provider."
},
"trackingBranch": {
"type": "string",
"description": "Repository branch configured for indexing and review evidence."
},
"commitSha": {
"type": [
"string",
"null"
],
"description": "Git commit SHA pinned by the evidence manifest. A null value explicitly means no current value is available."
},
"revisionId": {
"type": [
"string",
"null"
],
"description": "Immutable indexed repository revision identifier. A null value explicitly means no current value is available."
}
},
"required": [
"owner",
"name",
"defaultBranch",
"trackingBranch",
"commitSha",
"revisionId"
],
"additionalProperties": false,
"description": "Connected repository identity and provider metadata. Omit the field when it does not apply; omission is distinct from an empty value."
},
"collection": {
"type": "object",
"properties": {
"scopeKind": {
"type": "string",
"enum": [
"workspace",
"project",
"repository"
],
"description": "Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: \"workspace\", \"project\", \"repository\"."
},
"version": {
"type": "integer",
"minimum": 0,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer."
},
"snapshotId": {
"type": "string",
"description": "Immutable export snapshot identifier used to reproduce the exported brief state."
}
},
"required": [
"scopeKind",
"version",
"snapshotId"
],
"additionalProperties": false,
"description": "Named durable brief collection to page; use one of the documented enum values. Omit the field when it does not apply; omission is distinct from an empty value."
},
"status": {
"type": "string",
"enum": [
"ready",
"syncing",
"stale",
"degraded",
"unavailable"
],
"description": "Current typed status; the schema enum or union branch lists every allowed value. Allowed values: \"ready\", \"syncing\", \"stale\", \"degraded\", \"unavailable\"."
},
"freshness": {
"type": "object",
"properties": {
"asOf": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp describing evidence freshness. A null value explicitly means no current value is available."
},
"coverage": {
"type": "string",
"enum": [
"full",
"partial",
"unknown"
],
"description": "Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence. Allowed values: \"full\", \"partial\", \"unknown\"."
}
},
"required": [
"asOf",
"coverage"
],
"additionalProperties": false,
"description": "Repository indexing freshness and configured tracking branch."
},
"provenance": {
"type": "string",
"enum": [
"semel_indexed",
"local_harness"
],
"description": "Immutable repository revision and evidence-source provenance. Allowed values: \"semel_indexed\", \"local_harness\"."
}
},
"required": [
"sourceId",
"kind",
"label",
"scope",
"status",
"freshness",
"provenance"
],
"additionalProperties": false
},
"description": "Connected repository sources currently authorized for this project. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"sources",
"nextCursor"
],
"additionalProperties": false
}
```
**Example structured result (source-list)**
```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
}
```
Bindings: sourceId from structuredContent.sources[0].sourceId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}"
}
],
"structuredContent": {
"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
}
}
```
Next permitted action: Follow nextCursor to completion and distinguish ready, stale, degraded, and unavailable sources.
**Example requests**
- “what context sources do I have for this project?”
- “is there an indexed repository for the checkout project?”
Errors: `AUTHORIZATION_SCOPE_MISSING`, `PROJECT_ACCESS_DENIED`.
Related operations: `project_context_search`, `project_context_evidence_get`.
---
### project_create
Create a new project (a fresh, independent effort) and seed its recommended pre-build review cascade. Use for any net-new effort; reuse an existing project only on considerable overlap.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `name` — string; required; minimum length 1; maximum length 200. Human-readable name displayed in Semel. Accepted length or value is 1 through 200, inclusive.
- `reviewMode` — "direct" | "propose"; optional. Project review interaction mode configured in Semel. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: "direct", "propose".
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Human-readable name displayed in Semel. Accepted length or value is 1 through 200, inclusive."
},
"reviewMode": {
"type": "string",
"enum": [
"direct",
"propose"
],
"description": "Project review interaction mode configured in Semel. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: \"direct\", \"propose\"."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"name",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"name": "Checkout reliability",
"reviewMode": "direct",
"idempotencyKey": "recipe-project-create-v1"
}
```
**Binding template**
```json
{
"name": "{{projectName}}",
"reviewMode": "direct",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `project` — object; required. Project record returned by the operation.
- `project.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `project.workspaceId` — string; required. Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
- `project.name` — string; required. Human-readable name displayed in Semel.
- `project.reviewMode` — "direct" | "propose"; required. Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
- `project.ownerId` — string; optional. Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value.
- `project.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"project": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"workspaceId": {
"type": "string",
"description": "Workspace identifier that owns the record; it is resolved from authenticated Semel membership."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"reviewMode": {
"type": "string",
"enum": [
"direct",
"propose"
],
"description": "Project review interaction mode configured in Semel. Allowed values: \"direct\", \"propose\"."
},
"ownerId": {
"type": "string",
"description": "Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"workspaceId",
"name",
"reviewMode",
"createdAt"
],
"additionalProperties": false,
"description": "Project record returned by the operation."
}
},
"required": [
"project"
],
"additionalProperties": false
}
```
**Example structured result (project-created)**
```json
{
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
```
Bindings: projectId from structuredContent.project.id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"project\":{\"id\":\"prj_fixture_checkout\",\"workspaceId\":\"ws_fixture_primary\",\"name\":\"Checkout reliability\",\"reviewMode\":\"direct\",\"createdAt\":\"2026-09-07T16:00:00.000Z\"}}"
}
],
"structuredContent": {
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
}
```
Next permitted action: Carry project.id into every project-scoped call.
**Example requests**
- “/semel create a project for the new onboarding flow”
- “/semel start a new project called Checkout v2”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `project_list`, `project_get`, `brief_create`.
---
### project_get
Read a single project by id — its name, review mode, creator, and created-at. Use to inspect one project's details, for example after finding it with project_list.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Supply a non-empty identifier.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Supply a non-empty identifier."
}
},
"required": [
"projectId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}"
}
```
**Returns**
- `project` — object; required. Canonical project record returned after authorization and, for project_rename, after the durable name update succeeds.
- `project.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `project.workspaceId` — string; required. Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
- `project.name` — string; required. Human-readable name displayed in Semel.
- `project.reviewMode` — "direct" | "propose"; required. Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
- `project.ownerId` — string; optional. Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value.
- `project.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"project": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"workspaceId": {
"type": "string",
"description": "Workspace identifier that owns the record; it is resolved from authenticated Semel membership."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"reviewMode": {
"type": "string",
"enum": [
"direct",
"propose"
],
"description": "Project review interaction mode configured in Semel. Allowed values: \"direct\", \"propose\"."
},
"ownerId": {
"type": "string",
"description": "Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"workspaceId",
"name",
"reviewMode",
"createdAt"
],
"additionalProperties": false,
"description": "Canonical project record returned after authorization and, for project_rename, after the durable name update succeeds."
}
},
"required": [
"project"
],
"additionalProperties": false
}
```
**Example structured result (project)**
```json
{
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
```
Bindings: project from structuredContent.project.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"project\":{\"id\":\"prj_fixture_checkout\",\"workspaceId\":\"ws_fixture_primary\",\"name\":\"Checkout reliability\",\"reviewMode\":\"direct\",\"createdAt\":\"2026-09-07T16:00:00.000Z\"}}"
}
],
"structuredContent": {
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
}
```
Next permitted action: Confirm the resolved project details before mutation.
**Example requests**
- “/semel show me the details of this project”
- “/semel what is the review mode for the checkout project?”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `project_list`, `project_rename`.
---
### project_list
List the projects this principal may reach (project-allowlist filtered), newest first. Use to confirm no considerably-overlapping project already exists before creating one.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `{}` — no arguments.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {},
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{}
```
**Binding template**
```json
{}
```
**Returns**
- `projects` — array; required. Projects reachable by the authenticated principal, filtered by its project allowlist and ordered newest first. An empty array means none are reachable.
- `projects[]` — object; required.
- `projects[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `projects[].workspaceId` — string; required. Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
- `projects[].name` — string; required. Human-readable name displayed in Semel.
- `projects[].reviewMode` — "direct" | "propose"; required. Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
- `projects[].ownerId` — string; optional. Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value.
- `projects[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"projects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"workspaceId": {
"type": "string",
"description": "Workspace identifier that owns the record; it is resolved from authenticated Semel membership."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"reviewMode": {
"type": "string",
"enum": [
"direct",
"propose"
],
"description": "Project review interaction mode configured in Semel. Allowed values: \"direct\", \"propose\"."
},
"ownerId": {
"type": "string",
"description": "Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"workspaceId",
"name",
"reviewMode",
"createdAt"
],
"additionalProperties": false
},
"description": "Projects reachable by the authenticated principal, filtered by its project allowlist and ordered newest first. An empty array means none are reachable."
}
},
"required": [
"projects"
],
"additionalProperties": false
}
```
**Example structured result (project-list)**
```json
{
"projects": []
}
```
Bindings: projects from structuredContent.projects.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"projects\":[]}"
}
],
"structuredContent": {
"projects": []
}
}
```
Next permitted action: Reuse one exact match, ask about ambiguity, or prepare project_create.
**Example requests**
- “/semel list my projects”
- “/semel what projects do I have?”
Errors: universal authentication and validation errors only.
Related operations: `project_get`, `project_create`.
---
### project_rename
Rename a project (name only). Requires the accountable human to be the project creator or the workspace owner (the same guard as the portal). Use to correct or update a project's display name.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the accountable human must be the project creator or workspace owner.
- `name` — string; required; minimum length 1; maximum length 200. Replacement project display name after trimming, from 1 through 200 characters. A successful call durably renames the project.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the accountable human must be the project creator or workspace owner."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Replacement project display name after trimming, from 1 through 200 characters. A successful call durably renames the project."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"projectId",
"name",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"name": "Payments reliability",
"idempotencyKey": "recipe-project-rename-v1"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"name": "Payments reliability",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `project` — object; required. Canonical project record returned after authorization and, for project_rename, after the durable name update succeeds.
- `project.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `project.workspaceId` — string; required. Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
- `project.name` — string; required. Human-readable name displayed in Semel.
- `project.reviewMode` — "direct" | "propose"; required. Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
- `project.ownerId` — string; optional. Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value.
- `project.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"project": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"workspaceId": {
"type": "string",
"description": "Workspace identifier that owns the record; it is resolved from authenticated Semel membership."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"reviewMode": {
"type": "string",
"enum": [
"direct",
"propose"
],
"description": "Project review interaction mode configured in Semel. Allowed values: \"direct\", \"propose\"."
},
"ownerId": {
"type": "string",
"description": "Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"workspaceId",
"name",
"reviewMode",
"createdAt"
],
"additionalProperties": false,
"description": "Canonical project record returned after authorization and, for project_rename, after the durable name update succeeds."
}
},
"required": [
"project"
],
"additionalProperties": false
}
```
**Example structured result (project-renamed)**
```json
{
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Payments reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
```
Bindings: renamedProject from structuredContent.project.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"project\":{\"id\":\"prj_fixture_checkout\",\"workspaceId\":\"ws_fixture_primary\",\"name\":\"Payments reliability\",\"reviewMode\":\"direct\",\"createdAt\":\"2026-09-07T16:00:00.000Z\"}}"
}
],
"structuredContent": {
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Payments reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
}
```
Next permitted action: Keep the same project id after the rename.
**Example requests**
- “/semel rename this project to Checkout v2”
- “/semel change the billing project name to Payments”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `project_get`, `project_list`.
---
### review_cancel
Cancel a review the agent originated — directly for an inert pre-claim local-intent run, by requesting cancellation of an in-progress run (a live harness finishes it), or by finalizing a released local run now.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:run`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `runId` — string; required; minimum length 1. Review-run identifier returned by a review start, status, or cascade handoff result. Minimum accepted length or value is 1.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"runId": {
"type": "string",
"minLength": 1,
"description": "Review-run identifier returned by a review start, status, or cascade handoff result. Minimum accepted length or value is 1."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"runId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"runId": "run_fixture_followup",
"idempotencyKey": "recipe-review-cancel-v1"
}
```
**Binding template**
```json
{
"runId": "{{newRunId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `outcome` — "cancelled" | "cancel_requested"; required. Typed result of this operation; union branches define the follow-up action for each value. Allowed values: "cancelled", "cancel_requested".
- `status` — "queued" | "invoking" | "running" | "waiting_input" | "completed" | "failed" | "cancelled" | "needs_attention" | "suspended"; required. Current typed status; the schema enum or union branch lists every allowed value. Allowed values: "queued", "invoking", "running", "waiting_input", "completed", "failed", "cancelled", "needs_attention", "suspended".
- `claimed` — boolean; optional. Whether the external execution currently has an active claimed epoch. Omit the field when it does not apply; omission is distinct from an empty value.
- `finalized` — boolean; optional. Whether this run has reached its terminal finalization step. Omit the field when it does not apply; omission is distinct from an empty value.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"runId": {
"type": "string",
"description": "Review-run identifier returned by a review start, status, or cascade handoff result."
},
"outcome": {
"type": "string",
"enum": [
"cancelled",
"cancel_requested"
],
"description": "Typed result of this operation; union branches define the follow-up action for each value. Allowed values: \"cancelled\", \"cancel_requested\"."
},
"status": {
"type": "string",
"enum": [
"queued",
"invoking",
"running",
"waiting_input",
"completed",
"failed",
"cancelled",
"needs_attention",
"suspended"
],
"description": "Current typed status; the schema enum or union branch lists every allowed value. Allowed values: \"queued\", \"invoking\", \"running\", \"waiting_input\", \"completed\", \"failed\", \"cancelled\", \"needs_attention\", \"suspended\"."
},
"claimed": {
"type": "boolean",
"description": "Whether the external execution currently has an active claimed epoch. Omit the field when it does not apply; omission is distinct from an empty value."
},
"finalized": {
"type": "boolean",
"description": "Whether this run has reached its terminal finalization step. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"runId",
"outcome",
"status"
],
"additionalProperties": false
}
```
**Example structured result (cancel-requested)**
```json
{
"runId": "run_fixture_followup",
"outcome": "cancel_requested",
"status": "queued"
}
```
Bindings: cancelOutcome from structuredContent.outcome.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"runId\":\"run_fixture_followup\",\"outcome\":\"cancel_requested\",\"status\":\"queued\"}"
}
],
"structuredContent": {
"runId": "run_fixture_followup",
"outcome": "cancel_requested",
"status": "queued"
}
}
```
Next permitted action: Stop local work and follow the authoritative returned status.
**Example requests**
- “/semel cancel that review — I did not mean to start it”
Errors: `RUN_ALREADY_TERMINAL`, `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `review_start`, `review_status`, `review_execution_release`.
---
### review_execution_checkpoint_append
Append one bounded semantic checkpoint milestone to the current fenced epoch.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `seq` — integer; required. Positive checkpoint event sequence within the current fence generation. Minimum accepted length or value is 0. The value must be an integer.
- `activeSkillId` — string; optional; minimum length 1; maximum length 200. Pinned active-skill identifier for this checkpoint; omit only before the first skill activation. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `milestoneName` — string; required; minimum length 1; maximum length 200. Short caller-chosen name for the completed execution milestone represented by this checkpoint. Accepted length or value is 1 through 200, inclusive.
- `safeSummary` — string; optional; maximum length 8192. Short progress summary safe for durable storage and display; never include secrets, reasoning, or raw source. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 8192.
- `receipt` — object; optional. Optional structured progress receipt; forbidden reasoning, raw-tool-output, prompt, and source fields are rejected recursively. Omit the field when it does not apply; omission is distinct from an empty value.
- `receipt{key}` — JSON value; optional.
- `clientObservedAt` — string; optional; format date-time. Optional RFC 3339 client timestamp for display only; server sequence controls ordering. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"seq": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Positive checkpoint event sequence within the current fence generation. Minimum accepted length or value is 0. The value must be an integer."
},
"activeSkillId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Pinned active-skill identifier for this checkpoint; omit only before the first skill activation. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"milestoneName": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Short caller-chosen name for the completed execution milestone represented by this checkpoint. Accepted length or value is 1 through 200, inclusive."
},
"safeSummary": {
"type": "string",
"maxLength": 8192,
"description": "Short progress summary safe for durable storage and display; never include secrets, reasoning, or raw source. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 8192."
},
"receipt": {
"type": "object",
"additionalProperties": {},
"description": "Optional structured progress receipt; forbidden reasoning, raw-tool-output, prompt, and source fields are rejected recursively. Omit the field when it does not apply; omission is distinct from an empty value."
},
"clientObservedAt": {
"type": "string",
"format": "date-time",
"description": "Optional RFC 3339 client timestamp for display only; server sequence controls ordering. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"seq",
"milestoneName",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"seq": 1,
"activeSkillId": "engineering",
"milestoneName": "skill_start",
"safeSummary": "Started the pinned engineering skill.",
"receipt": {
"skillRole": "engineering",
"skillSha256": "182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7"
},
"clientObservedAt": "2026-09-07T16:00:00.000Z",
"idempotencyKey": "recipe-execution-checkpoint-skill-start-v1"
}
```
**Binding template**
```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}}"
}
```
**Returns**
- `accepted` — constant true; required. Confirms that the checkpoint or answer was durably accepted. This branch always uses true.
- `seq` — integer; required. Positive checkpoint event sequence within the current fence generation. The value must be an integer.
- `highWaterMark` — integer; required. Highest checkpoint sequence durably accepted after this append. The value must be an integer.
- `suggestedNextPollAt` — string; required. RFC 3339 timestamp for the next recommended sync or status poll.
- `coalesce` — boolean; required. Whether Semel recommends coalescing further nonterminal updates for the same stage.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"accepted": {
"type": "boolean",
"const": true,
"description": "Confirms that the checkpoint or answer was durably accepted. This branch always uses true."
},
"seq": {
"type": "integer",
"description": "Positive checkpoint event sequence within the current fence generation. The value must be an integer."
},
"highWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted after this append. The value must be an integer."
},
"suggestedNextPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended sync or status poll."
},
"coalesce": {
"type": "boolean",
"description": "Whether Semel recommends coalescing further nonterminal updates for the same stage."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"accepted",
"seq",
"highWaterMark",
"suggestedNextPollAt",
"coalesce",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (checkpoint-accepted)**
```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
}
}
}
```
Bindings: checkpoint1HighWaterMark from structuredContent.highWaterMark.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}}"
}
],
"structuredContent": {
"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
}
}
}
}
```
Next permitted action: Inspect evidence readiness before drawing conclusions.
**Example requests**
- “report skill_start progress for the active reviewer skill”
Errors: `STALE_FENCE`, `SEQUENCE_GAP`, `CONFLICTING_IDEMPOTENCY_REPLAY`, `PAYLOAD_REJECTED`, `VALIDATION_FAILED`.
Related operations: `review_execution_sync`, `review_execution_status`.
---
### review_execution_claim
Claim a review session for external execution, pinning the frozen canonical bundle.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:execute`
- Confirmation: implicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `grantId` — string; required; minimum length 1. Execution-grant identifier returned when the human approval boundary is satisfied. Minimum accepted length or value is 1.
- `reviewSessionId` — string; required; minimum length 1. Review-session identifier returned by review_start, review_new_pass, or execution status. Minimum accepted length or value is 1.
- `supportedProtocolVersions` — array; required; minimum items 1. Protocol versions the harness can execute, ordered by its preference. An empty array explicitly means no matching items.
- `supportedProtocolVersions[]` — string; required; minimum length 1.
- `harnessDescriptor` — object; required. Self-declared harness, agent, model, and supported-protocol metadata recorded on the execution claim for compatibility and audit.
- `harnessDescriptor.harness` — string; required; minimum length 1; maximum length 200. Harness product name declared by the caller; Semel does not independently verify it. Accepted length or value is 1 through 200, inclusive.
- `harnessDescriptor.harnessVersion` — string; optional; minimum length 1; maximum length 100. Optional harness version declared by the caller. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `harnessDescriptor.agent` — string; optional; minimum length 1; maximum length 200. Optional agent product name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `harnessDescriptor.agentVersion` — string; optional; minimum length 1; maximum length 100. Optional agent version declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `harnessDescriptor.model` — string; optional; minimum length 1; maximum length 200. Optional model name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `harnessDescriptor.modelProvider` — string; optional; minimum length 1; maximum length 100. Optional model provider declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"grantId": {
"type": "string",
"minLength": 1,
"description": "Execution-grant identifier returned when the human approval boundary is satisfied. Minimum accepted length or value is 1."
},
"reviewSessionId": {
"type": "string",
"minLength": 1,
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. Minimum accepted length or value is 1."
},
"supportedProtocolVersions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Protocol versions the harness can execute, ordered by its preference. An empty array explicitly means no matching items."
},
"harnessDescriptor": {
"type": "object",
"properties": {
"harness": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Harness product name declared by the caller; Semel does not independently verify it. Accepted length or value is 1 through 200, inclusive."
},
"harnessVersion": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional harness version declared by the caller. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive."
},
"agent": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional agent product name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"agentVersion": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional agent version declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"modelProvider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional model provider declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"harness"
],
"additionalProperties": false,
"description": "Self-declared harness, agent, model, and supported-protocol metadata recorded on the execution claim for compatibility and audit."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"grantId",
"reviewSessionId",
"supportedProtocolVersions",
"harnessDescriptor",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"grantId": "xgr_fixture_engineering",
"reviewSessionId": "rs_fixture_engineering",
"supportedProtocolVersions": [
"1.1"
],
"harnessDescriptor": {
"harness": "codex",
"harnessVersion": "1",
"agent": "codex",
"model": "gpt-5"
},
"idempotencyKey": "recipe-execution-claim-v1"
}
```
**Binding template**
```json
{
"grantId": "{{grantId}}",
"reviewSessionId": "{{reviewSessionId}}",
"supportedProtocolVersions": [
"{{protocolVersion}}"
],
"harnessDescriptor": {
"harness": "codex",
"harnessVersion": "1",
"agent": "codex",
"model": "gpt-5"
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `bundle` — object; required. Frozen canonical execution bundle returned at claim time.
- `bundle.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `bundle.instructions` — string; required. Pinned executable runbook instructions for this external execution.
- `bundle.schemaHashes` — object; required. Map from frozen schema name to its SHA-256 identity.
- `bundle.schemaHashes{key}` — string; optional.
- `bundle.session` — object; required. Frozen review-session and run identity plus reviewer position for the claimed external execution.
- `bundle.session.reviewSessionId` — string; required. Review-session identifier returned by review_start, review_new_pass, or execution status.
- `bundle.session.runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `bundle.session.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `bundle.session.briefId` — string; required. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary.
- `bundle.session.reviewMode` — string; required. Project review interaction mode configured in Semel.
- `bundle.session.reviewerSet` — array; required. Ordered reviewer roles configured for this cascade. An empty array explicitly means no matching items.
- `bundle.session.reviewerSet[]` — string; required.
- `bundle.session.cascadeStepId` — string | null; required. Identifier of the configured reviewer-cascade step associated with this run. A null value explicitly means no current value is available.
- `bundle.briefBase` — object; required. Frozen brief identity, version, and content snapshot against which this external execution must produce its result.
- `bundle.briefBase.versionId` — string; required. Immutable brief version identifier returned by the brief or claim contract.
- `bundle.briefBase.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `bundle.briefBase.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `bundle.skills` — array; required. Ordered pinned reviewer-skill manifests required for this execution; fetch each artifact by its returned identifiers before use. An empty array explicitly means no matching items.
- `bundle.skills[]` — object; required.
- `bundle.skills[].role` — string; required; minimum length 1. Pinned reviewer or artifact role used by the execution bundle. Minimum accepted length or value is 1.
- `bundle.skills[].version` — string; required; minimum length 1. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 1.
- `bundle.skills[].sha256` — string; required; minimum length 1. Lowercase hexadecimal SHA-256 digest used to verify exact bytes. Minimum accepted length or value is 1.
- `bundle.skills[].framingHash` — string; optional. SHA-256 identity of the shared framing artifact; null or omission means none is pinned. Omit the field when it does not apply; omission is distinct from an empty value.
- `bundle.evidencePolicy` — object; required. Frozen evidence policy map for this execution bundle; keys are versioned by the bundle contract.
- `bundle.evidencePolicy{key}` — JSON value; optional.
- `bundle.requiredCheckpoints` — array; required. Milestone names that must be checkpointed before final submission. An empty array explicitly means no matching items.
- `bundle.requiredCheckpoints[]` — string; required.
- `bundle.limits` — object; required. Server-issued byte, count, timeout, and polling limits that the external harness must obey for this execution.
- `bundle.limits.checkpointMaxBytes` — integer; required. Maximum serialized checkpoint receipt size in bytes. The value must be an integer.
- `bundle.limits.summaryMaxBytes` — integer; required. Maximum safe progress-summary size in UTF-8 bytes. The value must be an integer.
- `bundle.limits.sessionEventBudgetBytes` — integer; required. Maximum total persisted external-event payload for one session, in bytes. The value must be an integer.
- `canonicalBundleSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the frozen canonical execution bundle.
- `envelope` — object; required. Per-claim execution identity, fence, lease, and harness-attestation fields excluded from the bundle hash.
- `envelope.executionId` — string; required. External-execution identifier returned by a successful execution claim or status lookup.
- `envelope.fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. The value must be an integer.
- `envelope.leaseExpiresAt` — string; required. RFC 3339 lease expiration timestamp; null means no active lease exists.
- `envelope.heartbeatRecommendedSeconds` — integer; required. Recommended maximum interval between heartbeats, in seconds. The value must be an integer.
- `envelope.harnessDescriptor` — object; required. Self-declared harness, agent, model, and supported-protocol metadata recorded on the execution claim for compatibility and audit.
- `envelope.harnessDescriptor.harness` — string; required; minimum length 1; maximum length 200. Harness product name declared by the caller; Semel does not independently verify it. Accepted length or value is 1 through 200, inclusive.
- `envelope.harnessDescriptor.harnessVersion` — string; optional; minimum length 1; maximum length 100. Optional harness version declared by the caller. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `envelope.harnessDescriptor.agent` — string; optional; minimum length 1; maximum length 200. Optional agent product name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `envelope.harnessDescriptor.agentVersion` — string; optional; minimum length 1; maximum length 100. Optional agent version declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `envelope.harnessDescriptor.model` — string; optional; minimum length 1; maximum length 200. Optional model name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `envelope.harnessDescriptor.modelProvider` — string; optional; minimum length 1; maximum length 100. Optional model provider declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `activeSkill` — JSON value; required. Currently active pinned skill role and cursor; null means activation has not begun. A null value explicitly means no current value is available.
- `activeSkill (anyOf branch 1)` — object; required.
- `activeSkill (anyOf branch 1).role` — string; required. Pinned reviewer or artifact role used by the execution bundle.
- `activeSkill (anyOf branch 1).cursor` — string; required. Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning.
- `activeSkill (anyOf branch 2)` — null; required.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"bundle": {
"type": "object",
"properties": {
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"instructions": {
"type": "string",
"description": "Pinned executable runbook instructions for this external execution."
},
"schemaHashes": {
"type": "object",
"additionalProperties": {
"type": "string"
},
"description": "Map from frozen schema name to its SHA-256 identity."
},
"session": {
"type": "object",
"properties": {
"reviewSessionId": {
"type": "string",
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status."
},
"runId": {
"type": "string",
"description": "Review-run identifier returned by a review start, status, or cascade handoff result."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"briefId": {
"type": "string",
"description": "Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary."
},
"reviewMode": {
"type": "string",
"description": "Project review interaction mode configured in Semel."
},
"reviewerSet": {
"type": "array",
"items": {
"type": "string"
},
"description": "Ordered reviewer roles configured for this cascade. An empty array explicitly means no matching items."
},
"cascadeStepId": {
"type": [
"string",
"null"
],
"description": "Identifier of the configured reviewer-cascade step associated with this run. A null value explicitly means no current value is available."
}
},
"required": [
"reviewSessionId",
"runId",
"projectId",
"briefId",
"reviewMode",
"reviewerSet",
"cascadeStepId"
],
"additionalProperties": false,
"description": "Frozen review-session and run identity plus reviewer position for the claimed external execution."
},
"briefBase": {
"type": "object",
"properties": {
"versionId": {
"type": "string",
"description": "Immutable brief version identifier returned by the brief or claim contract."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
},
"sha256": {
"type": "string",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"versionId",
"versionNum",
"sha256"
],
"additionalProperties": false,
"description": "Frozen brief identity, version, and content snapshot against which this external execution must produce its result."
},
"skills": {
"type": "array",
"items": {
"type": "object",
"properties": {
"role": {
"type": "string",
"minLength": 1,
"description": "Pinned reviewer or artifact role used by the execution bundle. Minimum accepted length or value is 1."
},
"version": {
"type": "string",
"minLength": 1,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 1."
},
"sha256": {
"type": "string",
"minLength": 1,
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes. Minimum accepted length or value is 1."
},
"framingHash": {
"type": "string",
"description": "SHA-256 identity of the shared framing artifact; null or omission means none is pinned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"role",
"version",
"sha256"
],
"additionalProperties": false
},
"description": "Ordered pinned reviewer-skill manifests required for this execution; fetch each artifact by its returned identifiers before use. An empty array explicitly means no matching items."
},
"evidencePolicy": {
"type": "object",
"additionalProperties": {},
"description": "Frozen evidence policy map for this execution bundle; keys are versioned by the bundle contract."
},
"requiredCheckpoints": {
"type": "array",
"items": {
"type": "string"
},
"description": "Milestone names that must be checkpointed before final submission. An empty array explicitly means no matching items."
},
"limits": {
"type": "object",
"properties": {
"checkpointMaxBytes": {
"type": "integer",
"description": "Maximum serialized checkpoint receipt size in bytes. The value must be an integer."
},
"summaryMaxBytes": {
"type": "integer",
"description": "Maximum safe progress-summary size in UTF-8 bytes. The value must be an integer."
},
"sessionEventBudgetBytes": {
"type": "integer",
"description": "Maximum total persisted external-event payload for one session, in bytes. The value must be an integer."
}
},
"required": [
"checkpointMaxBytes",
"summaryMaxBytes",
"sessionEventBudgetBytes"
],
"additionalProperties": false,
"description": "Server-issued byte, count, timeout, and polling limits that the external harness must obey for this execution."
}
},
"required": [
"protocolVersion",
"instructions",
"schemaHashes",
"session",
"briefBase",
"skills",
"evidencePolicy",
"requiredCheckpoints",
"limits"
],
"additionalProperties": false,
"description": "Frozen canonical execution bundle returned at claim time."
},
"canonicalBundleSha256": {
"type": "string",
"description": "Lowercase hexadecimal SHA-256 digest of the frozen canonical execution bundle."
},
"envelope": {
"type": "object",
"properties": {
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup."
},
"fenceGeneration": {
"type": "integer",
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. The value must be an integer."
},
"leaseExpiresAt": {
"type": "string",
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists."
},
"heartbeatRecommendedSeconds": {
"type": "integer",
"description": "Recommended maximum interval between heartbeats, in seconds. The value must be an integer."
},
"harnessDescriptor": {
"type": "object",
"properties": {
"harness": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Harness product name declared by the caller; Semel does not independently verify it. Accepted length or value is 1 through 200, inclusive."
},
"harnessVersion": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional harness version declared by the caller. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive."
},
"agent": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional agent product name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"agentVersion": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional agent version declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"modelProvider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional model provider declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"harness"
],
"additionalProperties": false,
"description": "Self-declared harness, agent, model, and supported-protocol metadata recorded on the execution claim for compatibility and audit."
}
},
"required": [
"executionId",
"fenceGeneration",
"leaseExpiresAt",
"heartbeatRecommendedSeconds",
"harnessDescriptor"
],
"additionalProperties": false,
"description": "Per-claim execution identity, fence, lease, and harness-attestation fields excluded from the bundle hash."
},
"activeSkill": {
"anyOf": [
{
"type": "object",
"properties": {
"role": {
"type": "string",
"description": "Pinned reviewer or artifact role used by the execution bundle."
},
"cursor": {
"type": "string",
"description": "Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning."
}
},
"required": [
"role",
"cursor"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Currently active pinned skill role and cursor; null means activation has not begun. A null value explicitly means no current value is available."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"bundle",
"canonicalBundleSha256",
"envelope",
"activeSkill",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (claimed)**
```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
}
}
}
```
Bindings: executionId from structuredContent.envelope.executionId; canonicalBundleSha256 from structuredContent.canonicalBundleSha256.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}}"
}
],
"structuredContent": {
"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
}
}
}
}
```
Next permitted action: Persist executionId, fenceGeneration, bundle hash, lease guidance, and activeSkill from structuredContent.
**Example requests**
- “/semel continue the session I paused”
Errors: `GRANT_EXPIRED`, `PROTOCOL_VERSION_UNSUPPORTED`, `STALE_FENCE`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_grant_request`, `review_execution_status`.
---
### review_execution_grant_request
Discover or request the operator-issued execution grant that authorizes this harness to claim a review session.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: operator_grant
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `reviewSessionId` — string; required; minimum length 1. Review-session identifier returned by review_start, review_new_pass, or execution status. Minimum accepted length or value is 1.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"reviewSessionId": {
"type": "string",
"minLength": 1,
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. Minimum accepted length or value is 1."
}
},
"required": [
"reviewSessionId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"reviewSessionId": "rs_fixture_engineering"
}
```
**Binding template**
```json
{
"reviewSessionId": "{{reviewSessionId}}"
}
```
**Returns**
- `value (anyOf branch 1)` — object; optional.
- `value (anyOf branch 1).status` — constant "ready"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "ready".
- `value (anyOf branch 1).grant` — object; required. Current human-approved execution grant summary.
- `value (anyOf branch 1).grant.grantId` — string; required. Execution-grant identifier returned when the human approval boundary is satisfied.
- `value (anyOf branch 1).grant.state` — string; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 1).grant.intent` — string; required. Human-approved execution intent bound to the grant.
- `value (anyOf branch 1).grant.expiresAt` — string; required. RFC 3339 expiration timestamp.
- `value (anyOf branch 1).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 1).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 1).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 1).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 1).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 1).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 1).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 1).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 1).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 1).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 1).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 1).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 1).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 1).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 1).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 1).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 1).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 1).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 1).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 1).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 1).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 1).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
- `value (anyOf branch 2)` — object; optional.
- `value (anyOf branch 2).status` — constant "approval_required"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "approval_required".
- `value (anyOf branch 2).approvalUri` — string; required. Semel URI where a human can inspect and approve the execution grant.
- `value (anyOf branch 2).pollHandle` — string; required. Opaque handle used to poll while human grant approval is pending.
- `value (anyOf branch 2).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 2).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 2).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 2).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 2).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 2).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 2).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 2).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 2).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 2).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 2).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 2).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 2).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 2).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 2).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 2).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 2).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 2).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 2).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 2).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 2).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 2).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 2).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 2).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "ready",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"ready\"."
},
"grant": {
"type": "object",
"properties": {
"grantId": {
"type": "string",
"description": "Execution-grant identifier returned when the human approval boundary is satisfied."
},
"state": {
"type": "string",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"intent": {
"type": "string",
"description": "Human-approved execution intent bound to the grant."
},
"expiresAt": {
"type": "string",
"description": "RFC 3339 expiration timestamp."
}
},
"required": [
"grantId",
"state",
"intent",
"expiresAt"
],
"additionalProperties": false,
"description": "Current human-approved execution grant summary."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"grant",
"controlBlock"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "approval_required",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"approval_required\"."
},
"approvalUri": {
"type": "string",
"description": "Semel URI where a human can inspect and approve the execution grant."
},
"pollHandle": {
"type": "string",
"description": "Opaque handle used to poll while human grant approval is pending."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"approvalUri",
"pollHandle",
"controlBlock"
],
"additionalProperties": false
}
]
}
```
**Example structured result (approval-required)**
```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"
}
}
}
```
Bindings: approvalUri from structuredContent.approvalUri.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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\"}}}"
}
],
"structuredContent": {
"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"
}
}
}
}
```
Next permitted action: Show approvalUri to the human and poll only as instructed.
**Example requests**
- “/semel run the checkout brief review locally”
Errors: `GRANT_REQUIRED`, `GRANT_EXPIRED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_claim`, `review_execution_status`.
---
### review_execution_heartbeat
Renew the current fenced epoch lease.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"idempotencyKey": "recipe-execution-heartbeat-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `leaseExpiresAt` — string; required. RFC 3339 lease expiration timestamp; null means no active lease exists.
- `heartbeatRecommendedSeconds` — integer; required. Recommended maximum interval between heartbeats, in seconds. The value must be an integer.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"leaseExpiresAt": {
"type": "string",
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists."
},
"heartbeatRecommendedSeconds": {
"type": "integer",
"description": "Recommended maximum interval between heartbeats, in seconds. The value must be an integer."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"leaseExpiresAt",
"heartbeatRecommendedSeconds",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (lease-renewed)**
```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
}
}
}
```
Bindings: leaseExpiresAt from structuredContent.leaseExpiresAt.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}}"
}
],
"structuredContent": {
"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
}
}
}
}
```
Next permitted action: Schedule the next heartbeat from heartbeatRecommendedSeconds.
**Example requests**
- “keep my claim alive while the reviewer skill works”
Errors: `STALE_FENCE`, `LEASE_EXPIRED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_sync`, `review_execution_release`.
---
### review_execution_release
Yield the current fenced epoch for handoff or operator stop.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `reason` — "handoff" | "stop"; required. Typed or human-readable reason for the current outcome; omission means no reason is required. Allowed values: "handoff", "stop".
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"reason": {
"type": "string",
"enum": [
"handoff",
"stop"
],
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Allowed values: \"handoff\", \"stop\"."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"reason",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"reason": "handoff",
"idempotencyKey": "recipe-execution-release-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"reason": "handoff",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `released` — constant true; required. Confirms that the execution lease was released. This branch always uses true.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"released": {
"type": "boolean",
"const": true,
"description": "Confirms that the execution lease was released. This branch always uses true."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"released",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (released)**
```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
}
}
}
```
Bindings: released from structuredContent.released.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}}"
}
],
"structuredContent": {
"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
}
}
}
}
```
Next permitted action: Stop; the next harness must claim a fresh epoch and repeat local evidence confirmation.
**Example requests**
- “hand this session off to Codex”
Errors: `STALE_FENCE`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_claim`, `review_execution_status`.
---
### review_execution_skill_get
Load the byte-exact active reviewer rubric (its shared framing, and the shared local-execution QA addendum when pinned) from an execution's frozen content-addressed pins without exposing upcoming reviewer skills.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `role` — string; required; minimum length 1; maximum length 200. Pinned reviewer or artifact role used by the execution bundle. Accepted length or value is 1 through 200, inclusive.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"role": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Pinned reviewer or artifact role used by the execution bundle. Accepted length or value is 1 through 200, inclusive."
}
},
"required": [
"executionId",
"role"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"role": "engineering"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"role": "engineering"
}
```
**Returns**
- `artifact` — object; required. Exact content-addressed skill artifact selected from the frozen execution bundle.
- `artifact.role` — string; required; minimum length 1. Pinned reviewer or artifact role used by the execution bundle. Minimum accepted length or value is 1.
- `artifact.version` — string; required; minimum length 1. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 1.
- `artifact.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `artifact.framingHash` — JSON value; required. SHA-256 identity of the shared framing artifact; null or omission means none is pinned. A null value explicitly means no current value is available.
- `artifact.framingHash (anyOf branch 1)` — string; required.
- `artifact.framingHash (anyOf branch 2)` — null; required.
- `artifact.contentType` — string; required; minimum length 1. Internet media type of the exact skill artifact bytes, such as text/markdown; use it when loading the artifact. Minimum accepted length or value is 1.
- `artifact.bytes` — string; required. Exact UTF-8 skill artifact body; verify its SHA-256 before activation.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"artifact": {
"type": "object",
"properties": {
"role": {
"type": "string",
"minLength": 1,
"description": "Pinned reviewer or artifact role used by the execution bundle. Minimum accepted length or value is 1."
},
"version": {
"type": "string",
"minLength": 1,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 1."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
},
"framingHash": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
{
"type": "null"
}
],
"description": "SHA-256 identity of the shared framing artifact; null or omission means none is pinned. A null value explicitly means no current value is available."
},
"contentType": {
"type": "string",
"minLength": 1,
"description": "Internet media type of the exact skill artifact bytes, such as text/markdown; use it when loading the artifact. Minimum accepted length or value is 1."
},
"bytes": {
"type": "string",
"description": "Exact UTF-8 skill artifact body; verify its SHA-256 before activation."
}
},
"required": [
"role",
"version",
"sha256",
"framingHash",
"contentType",
"bytes"
],
"additionalProperties": false,
"description": "Exact content-addressed skill artifact selected from the frozen execution bundle."
}
},
"required": [
"artifact"
],
"additionalProperties": false
}
```
**Example structured result (active-skill)**
```json
{
"artifact": {
"role": "engineering",
"version": "1",
"sha256": "182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7",
"framingHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"contentType": "text/markdown",
"bytes": "# Engineering review\n\nValidate the brief against the repository evidence."
}
}
```
Bindings: skillSha256 from structuredContent.artifact.sha256.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"artifact\":{\"role\":\"engineering\",\"version\":\"1\",\"sha256\":\"182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7\",\"framingHash\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"contentType\":\"text/markdown\",\"bytes\":\"# Engineering review\\n\\nValidate the brief against the repository evidence.\"}}"
}
],
"structuredContent": {
"artifact": {
"role": "engineering",
"version": "1",
"sha256": "182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7",
"framingHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"contentType": "text/markdown",
"bytes": "# Engineering review\n\nValidate the brief against the repository evidence."
}
}
}
```
Next permitted action: Verify exact pinned hash/framing and execute only the active skill bytes.
**Example requests**
- “/semel load the exact pinned rubric for this local review”
- “/semel fetch the shared framing for the active reviewer lens”
- “/semel fetch the local-execution addendum pinned in this bundle”
Errors: `PROTOCOL_VERSION_UNSUPPORTED`, `LEASE_EXPIRED`, `STALE_FENCE`, `CANCELLED`, `PAYLOAD_REJECTED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_claim`, `review_execution_checkpoint_append`, `review_execution_status`.
---
### review_execution_status
Return the authoritative execution state — always callable, the documented fail-safe.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `reviewSessionId` — string; optional; minimum length 1. Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
- `executionId` — string; optional; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"reviewSessionId": {
"type": "string",
"minLength": 1,
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1."
},
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1."
}
},
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}"
}
```
**Returns**
- `execution` — JSON value; required. Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available.
- `execution (anyOf branch 1)` — object; required.
- `execution (anyOf branch 1).executionId` — string; required. External-execution identifier returned by a successful execution claim or status lookup.
- `execution (anyOf branch 1).reviewSessionId` — string; required. Review-session identifier returned by review_start, review_new_pass, or execution status.
- `execution (anyOf branch 1).state` — string; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `execution (anyOf branch 1).currentFenceGeneration` — integer; required. Active execution fence generation; refresh local state to this integer before attempting another fenced write. The value must be an integer.
- `execution (anyOf branch 1).activeSkillCursor` — string | null; required. Opaque cursor naming the active pinned skill; null means no skill is currently active. A null value explicitly means no current value is available.
- `execution (anyOf branch 2)` — null; required.
- `epoch` — JSON value; required. Execution fence generation associated with the current control-block state; omit before an epoch exists. A null value explicitly means no current value is available.
- `epoch (anyOf branch 1)` — object; required.
- `epoch (anyOf branch 1).fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. The value must be an integer.
- `epoch (anyOf branch 1).leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `epoch (anyOf branch 1).heartbeatAt` — string | null; required. RFC 3339 timestamp of the most recent accepted heartbeat; null means none was recorded. A null value explicitly means no current value is available.
- `epoch (anyOf branch 1).claimedByPrincipal` — string; required. Agent principal identifier that claimed this execution epoch.
- `epoch (anyOf branch 1).startedAt` — string; required. RFC 3339 timestamp when the execution epoch started.
- `epoch (anyOf branch 1).endedAt` — string | null; required. RFC 3339 timestamp when the execution epoch ended; null means it remains active. A null value explicitly means no current value is available.
- `epoch (anyOf branch 2)` — null; required.
- `checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `certificateReference` — JSON value; required. Reference to the terminal execution certificate when finalization has produced one; null means no certificate exists yet. A null value explicitly means no current value is available.
- `certificateReference (anyOf branch 1)` — object; required.
- `certificateReference (anyOf branch 1).certificateId` — string; required. Execution-certificate identifier assigned after successful finalization.
- `certificateReference (anyOf branch 1).state` — string; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `certificateReference (anyOf branch 2)` — null; required.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"execution": {
"anyOf": [
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup."
},
"reviewSessionId": {
"type": "string",
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status."
},
"state": {
"type": "string",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"currentFenceGeneration": {
"type": "integer",
"description": "Active execution fence generation; refresh local state to this integer before attempting another fenced write. The value must be an integer."
},
"activeSkillCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor naming the active pinned skill; null means no skill is currently active. A null value explicitly means no current value is available."
}
},
"required": [
"executionId",
"reviewSessionId",
"state",
"currentFenceGeneration",
"activeSkillCursor"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available."
},
"epoch": {
"anyOf": [
{
"type": "object",
"properties": {
"fenceGeneration": {
"type": "integer",
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"heartbeatAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp of the most recent accepted heartbeat; null means none was recorded. A null value explicitly means no current value is available."
},
"claimedByPrincipal": {
"type": "string",
"description": "Agent principal identifier that claimed this execution epoch."
},
"startedAt": {
"type": "string",
"description": "RFC 3339 timestamp when the execution epoch started."
},
"endedAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp when the execution epoch ended; null means it remains active. A null value explicitly means no current value is available."
}
},
"required": [
"fenceGeneration",
"leaseExpiresAt",
"heartbeatAt",
"claimedByPrincipal",
"startedAt",
"endedAt"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. A null value explicitly means no current value is available."
},
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"certificateReference": {
"anyOf": [
{
"type": "object",
"properties": {
"certificateId": {
"type": "string",
"description": "Execution-certificate identifier assigned after successful finalization."
},
"state": {
"type": "string",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
}
},
"required": [
"certificateId",
"state"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Reference to the terminal execution certificate when finalization has produced one; null means no certificate exists yet. A null value explicitly means no current value is available."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"execution",
"epoch",
"checkpointHighWaterMark",
"openQuestionCount",
"certificateReference",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (execution-status)**
```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
}
}
}
```
Bindings: controlBlock from structuredContent.controlBlock.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}}"
}
],
"structuredContent": {
"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
}
}
}
}
```
Next permitted action: Follow allowedNextOperations and the authoritative fence/lease/question counts.
**Example requests**
- “what is the current state of my claimed session”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_sync`.
---
### review_execution_submit
Submit a revision of the final typed reviewer result for validation and idempotent finalization; the completed response returns the next cascade step handoff.
- Mode: write
- Risk: high
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `submissionRevision` — integer; required. Monotonic final-submission attempt number for this execution, starting at 1. Minimum accepted length or value is 0. The value must be an integer.
- `canonicalBundleSha256` — string; required; minimum length 1. Lowercase hexadecimal SHA-256 digest of the frozen canonical execution bundle. Minimum accepted length or value is 1.
- `result` — object; required. Complete typed reviewer submission produced against the frozen execution bundle.
- `result.reviewer` — "product" | "engineering" | "design" | "security" | "test"; required. Reviewer role responsible for this submitted result. Allowed values: "product", "engineering", "design", "security", "test".
- `result.findings` — array; optional; default []; maximum items 50. Reviewer findings associated with the selected brief version. Omission uses the schema default []. An empty array explicitly means no matching items.
- `result.findings[]` — object; required.
- `result.findings[].section` — "goal" | "userPersonaContext" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief section key associated with the question, finding, proposal, or decision entry. Allowed values: "goal", "userPersonaContext", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result.findings[].note` — string; required; maximum length 4000. Reviewer-facing finding detail that explains the observed issue and the evidence-based change requested. Maximum accepted length or value is 4000.
- `result.findings[].severity` — "info" | "warn" | "block"; required. Finding impact level: info is advisory, warn requires attention, and block prevents approval or completion. Allowed values: "info", "warn", "block".
- `result.findings[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.findings[].citations[]` — JSON value; required.
- `result.findings[].citations[] (anyOf branch 1)` — object; required.
- `result.findings[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result.findings[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: "goal", "userPersonaContext", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result.findings[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result.findings[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.findings[].citations[] (anyOf branch 2)` — object; required.
- `result.findings[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result.findings[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result.findings[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.findings[].citations[] (anyOf branch 3)` — object; required.
- `result.findings[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result.findings[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result.findings[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.questions` — array; optional; default []; maximum items 50. Durable decision questions raised by the reviewer; omission defaults to no questions and each supplied question must be actionable. Omission uses the schema default []. An empty array explicitly means no matching items.
- `result.questions[]` — object; required.
- `result.questions[].section` — "goal" | "userPersonaContext" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief section key associated with the question, finding, proposal, or decision entry. Allowed values: "goal", "userPersonaContext", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result.questions[].decisionKey` — string; required; minimum length 1; maximum length 200. Caller-stable semantic key for one decision question; keep it unchanged across idempotent retries and review passes. Accepted length or value is 1 through 200, inclusive.
- `result.questions[].text` — string; required; maximum length 4000. Human-authored or model-produced text for this typed record. Maximum accepted length or value is 4000.
- `result.questions[].context_excerpt` — string; optional; maximum length 2000. Optional bounded context stored with the reviewer decision question. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 2000.
- `result.questions[].recommendation` — string; required; minimum length 1; maximum length 1200. Reviewer-recommended answer to the decision question, supplied so the respondent can accept or override it. Accepted length or value is 1 through 1200, inclusive.
- `result.questions[].recommendationRationale` — string; required; minimum length 1; maximum length 1200. Evidence-based explanation of why the reviewer recommends the proposed answer. Accepted length or value is 1 through 1200, inclusive.
- `result.questions[].consequenceOfDeferring` — string; required; minimum length 1; maximum length 1200. Concrete product or engineering consequence of postponing the requested decision. Accepted length or value is 1 through 1200, inclusive.
- `result.questions[].options` — array; optional; minimum items 2; maximum items 5. Explicit answer choices for a decision question; omission means the respondent may provide free-form text. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.questions[].options[]` — string; required; maximum length 1000.
- `result.questions[].suggestedRespondentId` — string; required; minimum length 1; maximum length 160. Optional Semel user identifier suggested to answer the question. Accepted length or value is 1 through 160, inclusive.
- `result.questions[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.questions[].citations[]` — JSON value; required.
- `result.questions[].citations[] (anyOf branch 1)` — object; required.
- `result.questions[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result.questions[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: "goal", "userPersonaContext", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result.questions[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result.questions[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.questions[].citations[] (anyOf branch 2)` — object; required.
- `result.questions[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result.questions[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result.questions[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.questions[].citations[] (anyOf branch 3)` — object; required.
- `result.questions[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result.questions[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result.questions[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.codeClaims` — array; optional; maximum items 50. Repository-behavior claims proposed by the reviewer; each claim requires bounded citations and is verified before durable publication. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.codeClaims[]` — object; required.
- `result.codeClaims[].claim` — string; required; minimum length 1; maximum length 4000. Concise factual assertion about repository behavior that the evidence checker must verify before publication. Accepted length or value is 1 through 4000, inclusive.
- `result.codeClaims[].citations` — array; required; minimum items 1; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. An empty array explicitly means no matching items.
- `result.codeClaims[].citations[]` — JSON value; required.
- `result.codeClaims[].citations[] (anyOf branch 1)` — object; required.
- `result.codeClaims[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result.codeClaims[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: "goal", "userPersonaContext", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result.codeClaims[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result.codeClaims[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.codeClaims[].citations[] (anyOf branch 2)` — object; required.
- `result.codeClaims[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result.codeClaims[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result.codeClaims[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.codeClaims[].citations[] (anyOf branch 3)` — object; required.
- `result.codeClaims[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result.codeClaims[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result.codeClaims[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.codeClaims[].consequence` — string; optional; minimum length 1; maximum length 4000. Concrete impact if the finding is left unresolved, used to explain its severity and required follow-up. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive.
- `result.codeClaims[].uncertainty` — string; optional; minimum length 1; maximum length 4000. Bounded explanation of any residual uncertainty in a repository claim after examining the cited evidence. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive.
- `result.codeClaims[].recommendation` — string; optional; minimum length 1; maximum length 4000. Reviewer-recommended answer to the decision question, supplied so the respondent can accept or override it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive.
- `result.sectionEdits` — object; optional. Complete replacements for supplied brief sections; omitted sections remain unchanged and supplied empty values intentionally clear them. Omit the field when it does not apply; omission is distinct from an empty value.
- `result.sectionEdits.goal` — string; optional; maximum length 4000. Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result.sectionEdits.userPersonaContext` — string; optional; maximum length 4000. User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result.sectionEdits.scope` — string; optional; maximum length 4000. Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result.sectionEdits.outOfScope` — string; optional; maximum length 4000. Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result.sectionEdits.requirements` — array; optional; maximum items 50. Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.requirements[]` — string; required; minimum length 1; maximum length 1000.
- `result.sectionEdits.edgeCases` — array; optional; maximum items 50. Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.edgeCases[]` — string; required; minimum length 1; maximum length 1000.
- `result.sectionEdits.acceptanceCriteria` — array; optional; maximum items 50. Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.acceptanceCriteria[]` — object; required.
- `result.sectionEdits.acceptanceCriteria[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result.sectionEdits.acceptanceCriteria[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `result.sectionEdits.acceptanceCriteria[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `result.sectionEdits.acceptanceCriteria[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `result.sectionEdits.acceptanceCriteria[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `result.sectionEdits.acceptanceCriteria[].id` — string; optional; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result.sectionEdits.acceptanceCriteria[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.acceptanceCriteria[].citations[]` — JSON value; required.
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1)` — object; required.
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: "goal", "userPersonaContext", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2)` — object; required.
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3)` — object; required.
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result.sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.sectionEdits.rolesPermissions` — array; optional; maximum items 50. Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.rolesPermissions[]` — string; required; minimum length 1; maximum length 1000.
- `result.sectionEdits.states` — array; optional; maximum items 50. User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.states[]` — string; required; minimum length 1; maximum length 1000.
- `result.sectionEdits.productSolution` — string; optional; maximum length 4000. Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result.sectionEdits.technicalSolution` — string; optional; maximum length 4000. Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result.sectionEdits.dataModelImplications` — string; optional; maximum length 4000. Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result.sectionEdits.architectureAssumptions` — string; optional; maximum length 4000. Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result.sectionEdits.design` — string; optional; maximum length 4000. Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result.sectionEdits.testingQaChecklist` — array; optional; maximum items 50. Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.testingQaChecklist[]` — object; required.
- `result.sectionEdits.testingQaChecklist[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result.sectionEdits.testPlanUnit` — array; optional; maximum items 50. Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.testPlanUnit[]` — string; required; minimum length 1; maximum length 1000.
- `result.sectionEdits.testPlanIntegration` — array; optional; maximum items 50. Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.testPlanIntegration[]` — string; required; minimum length 1; maximum length 1000.
- `result.sectionEdits.testPlanUiUx` — array; optional; maximum items 50. Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.testPlanUiUx[]` — string; required; minimum length 1; maximum length 1000.
- `result.sectionEdits.openQuestions` — array; optional; maximum items 50. Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.openQuestions[]` — string; required; minimum length 1; maximum length 1000.
- `result.sectionEdits.generatedTickets` — array; optional; maximum items 50. Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.generatedTickets[]` — object; required.
- `result.sectionEdits.generatedTickets[].id` — string; optional; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result.sectionEdits.generatedTickets[].title` — string; required; minimum length 1; maximum length 500. Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
- `result.sectionEdits.generatedTickets[].description` — JSON value; optional. Human-readable explanatory text; null or omission means no description was supplied. Omit the field when it does not apply; omission is distinct from an empty value. A null value explicitly means no current value is available. Maximum accepted length or value is 10000.
- `result.sectionEdits.generatedTickets[].description (anyOf branch 1)` — string; optional; maximum length 10000.
- `result.sectionEdits.generatedTickets[].description (anyOf branch 2)` — null; optional.
- `result.sectionEdits.generatedTickets[].boundCriteria` — array; optional; maximum items 50. Stable acceptance-criterion IDs implemented by this work order. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.generatedTickets[].boundCriteria[]` — string; required; minimum length 1; maximum length 200.
- `result.sectionEdits.generatedTickets[].boundRequirements` — array; optional; maximum items 50. Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.generatedTickets[].boundRequirements[]` — string; required; minimum length 1; maximum length 200.
- `result.sectionEdits.requiredEvidence` — array; optional; maximum items 50. Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.requiredEvidence[]` — object; required.
- `result.sectionEdits.requiredEvidence[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result.sectionEdits.requiredEvidence[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `result.sectionEdits.requiredEvidence[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `result.sectionEdits.requiredEvidence[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `result.sectionEdits.requiredEvidence[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `result.sectionEdits.requiredEvidence[].id` — string; optional; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result.sectionEdits.requiredEvidence[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.requiredEvidence[].citations[]` — JSON value; required.
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 1)` — object; required.
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: "goal", "userPersonaContext", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 2)` — object; required.
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 3)` — object; required.
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result.sectionEdits.requiredEvidence[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result.sectionEdits.decisions` — array; optional; maximum items 50. Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.decisions[]` — object; required.
- `result.sectionEdits.decisions[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result.sectionEdits.decisions[].source` — string; optional; maximum length 1000. Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000.
- `result.sectionEdits.sourceArtifactLinks` — array; optional; maximum items 50. Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result.sectionEdits.sourceArtifactLinks[]` — object; required.
- `result.sectionEdits.sourceArtifactLinks[].label` — string; required; minimum length 1; maximum length 1000. Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive.
- `result.sectionEdits.sourceArtifactLinks[].kind` — string; optional; maximum length 200. Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `result.summaryOfChanges` — string; optional; maximum length 4000. Bounded reviewer summary of the submitted section changes for user review and durable history. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"submissionRevision": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Monotonic final-submission attempt number for this execution, starting at 1. Minimum accepted length or value is 0. The value must be an integer."
},
"canonicalBundleSha256": {
"type": "string",
"minLength": 1,
"description": "Lowercase hexadecimal SHA-256 digest of the frozen canonical execution bundle. Minimum accepted length or value is 1."
},
"result": {
"type": "object",
"properties": {
"reviewer": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Reviewer role responsible for this submitted result. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
},
"findings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"section": {
"type": "string",
"enum": [
"goal",
"userPersonaContext",
"scope",
"outOfScope",
"requirements",
"edgeCases",
"acceptanceCriteria",
"rolesPermissions",
"states",
"productSolution",
"technicalSolution",
"dataModelImplications",
"architectureAssumptions",
"design",
"testingQaChecklist",
"testPlanUnit",
"testPlanIntegration",
"testPlanUiUx",
"openQuestions",
"generatedTickets",
"requiredEvidence",
"decisions",
"sourceArtifactLinks"
],
"description": "Canonical brief section key associated with the question, finding, proposal, or decision entry. Allowed values: \"goal\", \"userPersonaContext\", \"scope\", \"outOfScope\", \"requirements\", \"edgeCases\", \"acceptanceCriteria\", \"rolesPermissions\", \"states\", \"productSolution\", \"technicalSolution\", \"dataModelImplications\", \"architectureAssumptions\", \"design\", \"testingQaChecklist\", \"testPlanUnit\", \"testPlanIntegration\", \"testPlanUiUx\", \"openQuestions\", \"generatedTickets\", \"requiredEvidence\", \"decisions\", \"sourceArtifactLinks\"."
},
"note": {
"type": "string",
"maxLength": 4000,
"description": "Reviewer-facing finding detail that explains the observed issue and the evidence-based change requested. Maximum accepted length or value is 4000."
},
"severity": {
"type": "string",
"enum": [
"info",
"warn",
"block"
],
"description": "Finding impact level: info is advisory, warn requires attention, and block prevents approval or completion. Allowed values: \"info\", \"warn\", \"block\"."
},
"citations": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "brief-section",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"brief-section\"."
},
"sectionKey": {
"type": "string",
"enum": [
"goal",
"userPersonaContext",
"scope",
"outOfScope",
"requirements",
"edgeCases",
"acceptanceCriteria",
"rolesPermissions",
"states",
"productSolution",
"technicalSolution",
"dataModelImplications",
"architectureAssumptions",
"design",
"testingQaChecklist",
"testPlanUnit",
"testPlanIntegration",
"testPlanUiUx",
"openQuestions",
"generatedTickets",
"requiredEvidence",
"decisions",
"sourceArtifactLinks"
],
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: \"goal\", \"userPersonaContext\", \"scope\", \"outOfScope\", \"requirements\", \"edgeCases\", \"acceptanceCriteria\", \"rolesPermissions\", \"states\", \"productSolution\", \"technicalSolution\", \"dataModelImplications\", \"architectureAssumptions\", \"design\", \"testingQaChecklist\", \"testPlanUnit\", \"testPlanIntegration\", \"testPlanUiUx\", \"openQuestions\", \"generatedTickets\", \"requiredEvidence\", \"decisions\", \"sourceArtifactLinks\"."
},
"statementId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"sectionKey",
"verbatim"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "artifact",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"artifact\"."
},
"artifactId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"artifactId",
"verbatim"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "repository-code",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"repository-code\"."
},
"citationKey": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"citationKey",
"verbatim"
],
"additionalProperties": false
}
]
},
"maxItems": 5,
"description": "Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"required": [
"section",
"note",
"severity"
],
"additionalProperties": false
},
"maxItems": 50,
"default": [],
"description": "Reviewer findings associated with the selected brief version. Omission uses the schema default []. An empty array explicitly means no matching items."
},
"questions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"section": {
"type": "string",
"enum": [
"goal",
"userPersonaContext",
"scope",
"outOfScope",
"requirements",
"edgeCases",
"acceptanceCriteria",
"rolesPermissions",
"states",
"productSolution",
"technicalSolution",
"dataModelImplications",
"architectureAssumptions",
"design",
"testingQaChecklist",
"testPlanUnit",
"testPlanIntegration",
"testPlanUiUx",
"openQuestions",
"generatedTickets",
"requiredEvidence",
"decisions",
"sourceArtifactLinks"
],
"description": "Canonical brief section key associated with the question, finding, proposal, or decision entry. Allowed values: \"goal\", \"userPersonaContext\", \"scope\", \"outOfScope\", \"requirements\", \"edgeCases\", \"acceptanceCriteria\", \"rolesPermissions\", \"states\", \"productSolution\", \"technicalSolution\", \"dataModelImplications\", \"architectureAssumptions\", \"design\", \"testingQaChecklist\", \"testPlanUnit\", \"testPlanIntegration\", \"testPlanUiUx\", \"openQuestions\", \"generatedTickets\", \"requiredEvidence\", \"decisions\", \"sourceArtifactLinks\"."
},
"decisionKey": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)*$",
"description": "Caller-stable semantic key for one decision question; keep it unchanged across idempotent retries and review passes. Accepted length or value is 1 through 200, inclusive."
},
"text": {
"type": "string",
"maxLength": 4000,
"description": "Human-authored or model-produced text for this typed record. Maximum accepted length or value is 4000."
},
"context_excerpt": {
"type": "string",
"maxLength": 2000,
"description": "Optional bounded context stored with the reviewer decision question. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 2000."
},
"recommendation": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Reviewer-recommended answer to the decision question, supplied so the respondent can accept or override it. Accepted length or value is 1 through 1200, inclusive."
},
"recommendationRationale": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Evidence-based explanation of why the reviewer recommends the proposed answer. Accepted length or value is 1 through 1200, inclusive."
},
"consequenceOfDeferring": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Concrete product or engineering consequence of postponing the requested decision. Accepted length or value is 1 through 1200, inclusive."
},
"options": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1000
},
"minItems": 2,
"maxItems": 5,
"description": "Explicit answer choices for a decision question; omission means the respondent may provide free-form text. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"suggestedRespondentId": {
"type": "string",
"minLength": 1,
"maxLength": 160,
"description": "Optional Semel user identifier suggested to answer the question. Accepted length or value is 1 through 160, inclusive."
},
"citations": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "brief-section",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"brief-section\"."
},
"sectionKey": {
"type": "string",
"enum": [
"goal",
"userPersonaContext",
"scope",
"outOfScope",
"requirements",
"edgeCases",
"acceptanceCriteria",
"rolesPermissions",
"states",
"productSolution",
"technicalSolution",
"dataModelImplications",
"architectureAssumptions",
"design",
"testingQaChecklist",
"testPlanUnit",
"testPlanIntegration",
"testPlanUiUx",
"openQuestions",
"generatedTickets",
"requiredEvidence",
"decisions",
"sourceArtifactLinks"
],
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: \"goal\", \"userPersonaContext\", \"scope\", \"outOfScope\", \"requirements\", \"edgeCases\", \"acceptanceCriteria\", \"rolesPermissions\", \"states\", \"productSolution\", \"technicalSolution\", \"dataModelImplications\", \"architectureAssumptions\", \"design\", \"testingQaChecklist\", \"testPlanUnit\", \"testPlanIntegration\", \"testPlanUiUx\", \"openQuestions\", \"generatedTickets\", \"requiredEvidence\", \"decisions\", \"sourceArtifactLinks\"."
},
"statementId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"sectionKey",
"verbatim"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "artifact",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"artifact\"."
},
"artifactId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"artifactId",
"verbatim"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "repository-code",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"repository-code\"."
},
"citationKey": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"citationKey",
"verbatim"
],
"additionalProperties": false
}
]
},
"maxItems": 5,
"description": "Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"required": [
"section",
"decisionKey",
"text",
"recommendation",
"recommendationRationale",
"consequenceOfDeferring",
"suggestedRespondentId"
],
"additionalProperties": false
},
"maxItems": 50,
"default": [],
"description": "Durable decision questions raised by the reviewer; omission defaults to no questions and each supplied question must be actionable. Omission uses the schema default []. An empty array explicitly means no matching items."
},
"codeClaims": {
"type": "array",
"items": {
"type": "object",
"properties": {
"claim": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Concise factual assertion about repository behavior that the evidence checker must verify before publication. Accepted length or value is 1 through 4000, inclusive."
},
"citations": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "brief-section",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"brief-section\"."
},
"sectionKey": {
"type": "string",
"enum": [
"goal",
"userPersonaContext",
"scope",
"outOfScope",
"requirements",
"edgeCases",
"acceptanceCriteria",
"rolesPermissions",
"states",
"productSolution",
"technicalSolution",
"dataModelImplications",
"architectureAssumptions",
"design",
"testingQaChecklist",
"testPlanUnit",
"testPlanIntegration",
"testPlanUiUx",
"openQuestions",
"generatedTickets",
"requiredEvidence",
"decisions",
"sourceArtifactLinks"
],
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: \"goal\", \"userPersonaContext\", \"scope\", \"outOfScope\", \"requirements\", \"edgeCases\", \"acceptanceCriteria\", \"rolesPermissions\", \"states\", \"productSolution\", \"technicalSolution\", \"dataModelImplications\", \"architectureAssumptions\", \"design\", \"testingQaChecklist\", \"testPlanUnit\", \"testPlanIntegration\", \"testPlanUiUx\", \"openQuestions\", \"generatedTickets\", \"requiredEvidence\", \"decisions\", \"sourceArtifactLinks\"."
},
"statementId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"sectionKey",
"verbatim"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "artifact",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"artifact\"."
},
"artifactId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"artifactId",
"verbatim"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "repository-code",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"repository-code\"."
},
"citationKey": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"citationKey",
"verbatim"
],
"additionalProperties": false
}
]
},
"minItems": 1,
"maxItems": 5,
"description": "Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. An empty array explicitly means no matching items."
},
"consequence": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Concrete impact if the finding is left unresolved, used to explain its severity and required follow-up. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive."
},
"uncertainty": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Bounded explanation of any residual uncertainty in a repository claim after examining the cited evidence. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive."
},
"recommendation": {
"type": "string",
"maxLength": 4000,
"minLength": 1,
"description": "Reviewer-recommended answer to the decision question, supplied so the respondent can accept or override it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive."
}
},
"required": [
"claim",
"citations"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Repository-behavior claims proposed by the reviewer; each claim requires bounded citations and is verified before durable publication. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"sectionEdits": {
"type": "object",
"properties": {
"goal": {
"type": "string",
"maxLength": 4000,
"description": "Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"userPersonaContext": {
"type": "string",
"maxLength": 4000,
"description": "User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"scope": {
"type": "string",
"maxLength": 4000,
"description": "Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"outOfScope": {
"type": "string",
"maxLength": 4000,
"description": "Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"requirements": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"edgeCases": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"acceptanceCriteria": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"implementation": {
"type": "boolean",
"description": "Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value."
},
"manualEvidence": {
"type": "object",
"properties": {
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive."
},
"evidencePath": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive."
}
},
"required": [
"rationale",
"evidencePath"
],
"additionalProperties": false,
"description": "Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value."
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"citations": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "brief-section",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"brief-section\"."
},
"sectionKey": {
"type": "string",
"enum": [
"goal",
"userPersonaContext",
"scope",
"outOfScope",
"requirements",
"edgeCases",
"acceptanceCriteria",
"rolesPermissions",
"states",
"productSolution",
"technicalSolution",
"dataModelImplications",
"architectureAssumptions",
"design",
"testingQaChecklist",
"testPlanUnit",
"testPlanIntegration",
"testPlanUiUx",
"openQuestions",
"generatedTickets",
"requiredEvidence",
"decisions",
"sourceArtifactLinks"
],
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: \"goal\", \"userPersonaContext\", \"scope\", \"outOfScope\", \"requirements\", \"edgeCases\", \"acceptanceCriteria\", \"rolesPermissions\", \"states\", \"productSolution\", \"technicalSolution\", \"dataModelImplications\", \"architectureAssumptions\", \"design\", \"testingQaChecklist\", \"testPlanUnit\", \"testPlanIntegration\", \"testPlanUiUx\", \"openQuestions\", \"generatedTickets\", \"requiredEvidence\", \"decisions\", \"sourceArtifactLinks\"."
},
"statementId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"sectionKey",
"verbatim"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "artifact",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"artifact\"."
},
"artifactId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"artifactId",
"verbatim"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "repository-code",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"repository-code\"."
},
"citationKey": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"citationKey",
"verbatim"
],
"additionalProperties": false
}
]
},
"maxItems": 5,
"description": "Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"required": [
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"rolesPermissions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"states": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"productSolution": {
"type": "string",
"maxLength": 4000,
"description": "Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"technicalSolution": {
"type": "string",
"maxLength": 4000,
"description": "Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"dataModelImplications": {
"type": "string",
"maxLength": 4000,
"description": "Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"architectureAssumptions": {
"type": "string",
"maxLength": 4000,
"description": "Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"design": {
"type": "string",
"maxLength": 4000,
"description": "Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"testingQaChecklist": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
}
},
"required": [
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanUnit": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanIntegration": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanUiUx": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"openQuestions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"generatedTickets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive."
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 10000
},
{
"type": "null"
}
],
"description": "Human-readable explanatory text; null or omission means no description was supplied. Omit the field when it does not apply; omission is distinct from an empty value. A null value explicitly means no current value is available. Maximum accepted length or value is 10000."
},
"boundCriteria": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
},
"maxItems": 50,
"description": "Stable acceptance-criterion IDs implemented by this work order. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"boundRequirements": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
},
"maxItems": 50,
"description": "Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"required": [
"title"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"requiredEvidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"implementation": {
"type": "boolean",
"description": "Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value."
},
"manualEvidence": {
"type": "object",
"properties": {
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive."
},
"evidencePath": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive."
}
},
"required": [
"rationale",
"evidencePath"
],
"additionalProperties": false,
"description": "Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value."
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"citations": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "brief-section",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"brief-section\"."
},
"sectionKey": {
"type": "string",
"enum": [
"goal",
"userPersonaContext",
"scope",
"outOfScope",
"requirements",
"edgeCases",
"acceptanceCriteria",
"rolesPermissions",
"states",
"productSolution",
"technicalSolution",
"dataModelImplications",
"architectureAssumptions",
"design",
"testingQaChecklist",
"testPlanUnit",
"testPlanIntegration",
"testPlanUiUx",
"openQuestions",
"generatedTickets",
"requiredEvidence",
"decisions",
"sourceArtifactLinks"
],
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: \"goal\", \"userPersonaContext\", \"scope\", \"outOfScope\", \"requirements\", \"edgeCases\", \"acceptanceCriteria\", \"rolesPermissions\", \"states\", \"productSolution\", \"technicalSolution\", \"dataModelImplications\", \"architectureAssumptions\", \"design\", \"testingQaChecklist\", \"testPlanUnit\", \"testPlanIntegration\", \"testPlanUiUx\", \"openQuestions\", \"generatedTickets\", \"requiredEvidence\", \"decisions\", \"sourceArtifactLinks\"."
},
"statementId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"sectionKey",
"verbatim"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "artifact",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"artifact\"."
},
"artifactId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"artifactId",
"verbatim"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "repository-code",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"repository-code\"."
},
"citationKey": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
}
},
"required": [
"sourceType",
"citationKey",
"verbatim"
],
"additionalProperties": false
}
]
},
"maxItems": 5,
"description": "Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"required": [
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"decisions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"source": {
"type": "string",
"maxLength": 1000,
"description": "Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000."
}
},
"required": [
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"sourceArtifactLinks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive."
},
"kind": {
"type": "string",
"maxLength": 200,
"description": "Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
}
},
"required": [
"label"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"additionalProperties": false,
"description": "Complete replacements for supplied brief sections; omitted sections remain unchanged and supplied empty values intentionally clear them. Omit the field when it does not apply; omission is distinct from an empty value."
},
"summaryOfChanges": {
"type": "string",
"maxLength": 4000,
"description": "Bounded reviewer summary of the submitted section changes for user review and durable history. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
}
},
"required": [
"reviewer"
],
"additionalProperties": false,
"description": "Complete typed reviewer submission produced against the frozen execution bundle."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"submissionRevision",
"canonicalBundleSha256",
"result",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"submissionRevision": 1,
"canonicalBundleSha256": "c45cacf945339d19f0d3f1f4a7e7977071f9555780cdd79b0ce1768decdfbd90",
"result": {
"reviewer": "engineering",
"findings": [],
"questions": [],
"summaryOfChanges": "Validated retry-safe payment intent reuse."
},
"idempotencyKey": "recipe-execution-submit-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"submissionRevision": 1,
"canonicalBundleSha256": "{{canonicalBundleSha256}}",
"result": {
"reviewer": "engineering",
"findings": [],
"questions": [],
"summaryOfChanges": "Validated retry-safe payment intent reuse."
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `value (anyOf branch 1)` — object; optional.
- `value (anyOf branch 1).status` — constant "completed"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "completed".
- `value (anyOf branch 1).outcome` — "version_created" | "no_change"; required. Typed result of this operation; union branches define the follow-up action for each value. Allowed values: "version_created", "no_change".
- `value (anyOf branch 1).briefVersionId` — string | null; required. Immutable brief-version identifier created or selected by finalization; null means no version was produced. A null value explicitly means no current value is available.
- `value (anyOf branch 1).briefVersionNum` — JSON value; required. Monotonic brief-version number created or selected by finalization; null means no version was produced. A null value explicitly means no current value is available. The value must be an integer.
- `value (anyOf branch 1).briefVersionNum (anyOf branch 1)` — integer; required.
- `value (anyOf branch 1).briefVersionNum (anyOf branch 2)` — null; required.
- `value (anyOf branch 1).certificateReference` — JSON value; required. Reference to the terminal execution certificate when finalization has produced one; null means no certificate exists yet. A null value explicitly means no current value is available.
- `value (anyOf branch 1).certificateReference (anyOf branch 1)` — object; required.
- `value (anyOf branch 1).certificateReference (anyOf branch 1).certificateId` — string; required. Execution-certificate identifier assigned after successful finalization.
- `value (anyOf branch 1).certificateReference (anyOf branch 1).state` — string; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 1).certificateReference (anyOf branch 2)` — null; required.
- `value (anyOf branch 1).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 1).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 1).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 1).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 1).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 1).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 1).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 1).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 1).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 1).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 1).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 1).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 1).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 1).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 1).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 1).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 1).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 1).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 1).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 1).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 1).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 1).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
- `value (anyOf branch 1).cascade` — JSON value; optional. Observed next-step cascade handoff after submission or review admission. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 1).status` — constant "awaiting_local_claim"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "awaiting_local_claim".
- `value (anyOf branch 1).cascade (anyOf branch 1).runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `value (anyOf branch 1).cascade (anyOf branch 1).reviewSessionId` — string | null; required. Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available.
- `value (anyOf branch 1).cascade (anyOf branch 1).cascadeStepId` — string; required. Identifier of the configured reviewer-cascade step associated with this run.
- `value (anyOf branch 1).cascade (anyOf branch 1).grantApprovalUri` — string; optional. Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
- `value (anyOf branch 1).cascade (anyOf branch 2)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 2).status` — constant "in_progress"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "in_progress".
- `value (anyOf branch 1).cascade (anyOf branch 2).runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `value (anyOf branch 1).cascade (anyOf branch 2).reviewSessionId` — string | null; required. Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available.
- `value (anyOf branch 1).cascade (anyOf branch 2).cascadeStepId` — string; required. Identifier of the configured reviewer-cascade step associated with this run.
- `value (anyOf branch 1).cascade (anyOf branch 2).execution` — JSON value; required. Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available. Allowed values: "hosted", "local".
- `value (anyOf branch 1).cascade (anyOf branch 2).execution (anyOf branch 1)` — "hosted" | "local"; required.
- `value (anyOf branch 1).cascade (anyOf branch 2).execution (anyOf branch 2)` — null; required.
- `value (anyOf branch 1).cascade (anyOf branch 3)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 3).status` — constant "settled"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "settled".
- `value (anyOf branch 1).cascade (anyOf branch 3).runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `value (anyOf branch 1).cascade (anyOf branch 3).cascadeStepId` — string; required. Identifier of the configured reviewer-cascade step associated with this run.
- `value (anyOf branch 1).cascade (anyOf branch 3).runStatus` — string; required. Terminal or current review-run status returned by finalization when no additional cascade dispatch is required.
- `value (anyOf branch 1).cascade (anyOf branch 4)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 4).status` — constant "gate_wait"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "gate_wait".
- `value (anyOf branch 1).cascade (anyOf branch 4).cascadeStepId` — string; required. Identifier of the configured reviewer-cascade step associated with this run.
- `value (anyOf branch 1).cascade (anyOf branch 5)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 5).status` — constant "blocked"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "blocked".
- `value (anyOf branch 1).cascade (anyOf branch 5).cascadeStepId` — string; required. Identifier of the configured reviewer-cascade step associated with this run.
- `value (anyOf branch 1).cascade (anyOf branch 5).reason` — constant "cap_exceeded"; required. Typed or human-readable reason for the current outcome; omission means no reason is required. This branch always uses "cap_exceeded".
- `value (anyOf branch 1).cascade (anyOf branch 5).hardCapCents` — integer; required. Workspace hard spending cap in integer US-dollar cents. The value must be an integer.
- `value (anyOf branch 1).cascade (anyOf branch 5).spentThisMonthCents` — integer; required. Workspace spend in integer US-dollar cents for the current billing month. The value must be an integer.
- `value (anyOf branch 1).cascade (anyOf branch 6)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 6).status` — constant "cascade_complete"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "cascade_complete".
- `value (anyOf branch 1).cascade (anyOf branch 7)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 7).status` — constant "none"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "none".
- `value (anyOf branch 1).cascade (anyOf branch 8)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 8).status` — constant "pending"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "pending".
- `value (anyOf branch 1).cascade (anyOf branch 8).reason` — string; required. Typed or human-readable reason for the current outcome; omission means no reason is required.
- `value (anyOf branch 2)` — object; optional.
- `value (anyOf branch 2).status` — constant "repair_required"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "repair_required".
- `value (anyOf branch 2).submissionRevision` — integer; required. Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer.
- `value (anyOf branch 2).payloadSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the canonical submitted payload.
- `value (anyOf branch 2).violations` — array; required; minimum items 1. Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items.
- `value (anyOf branch 2).violations[]` — object; required.
- `value (anyOf branch 2).violations[].pointer` — string; required. RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root.
- `value (anyOf branch 2).violations[].ruleId` — string; required. Stable validation-rule identifier for this violation.
- `value (anyOf branch 2).violations[].remediationCategory` — string; required. Machine-readable category describing the required correction.
- `value (anyOf branch 2).violations[].message` — string; required. User-facing validation or remediation message that contains no secret material.
- `value (anyOf branch 2).remainingRepairAttempts` — integer; required; minimum 0. Distinct corrected submissions still allowed before operator attention is required. Minimum accepted length or value is 0. The value must be an integer.
- `value (anyOf branch 2).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 2).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 2).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 2).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 2).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 2).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 2).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 2).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 2).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 2).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 2).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 2).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 2).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 2).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 2).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 2).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 2).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 2).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 2).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 2).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 2).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 2).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 2).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 2).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
- `value (anyOf branch 3)` — object; optional.
- `value (anyOf branch 3).status` — constant "needs_attention"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "needs_attention".
- `value (anyOf branch 3).reason` — "repair_budget_exhausted" | "non_repairable"; required. Typed or human-readable reason for the current outcome; omission means no reason is required. Allowed values: "repair_budget_exhausted", "non_repairable".
- `value (anyOf branch 3).submissionRevision` — integer; required. Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer.
- `value (anyOf branch 3).violations` — array; required. Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items.
- `value (anyOf branch 3).violations[]` — object; required.
- `value (anyOf branch 3).violations[].pointer` — string; required. RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root.
- `value (anyOf branch 3).violations[].ruleId` — string; required. Stable validation-rule identifier for this violation.
- `value (anyOf branch 3).violations[].remediationCategory` — string; required. Machine-readable category describing the required correction.
- `value (anyOf branch 3).violations[].message` — string; required. User-facing validation or remediation message that contains no secret material.
- `value (anyOf branch 3).history` — array; required. Complete safe submission-validation history, oldest attempt first. An empty array explicitly means no matching items.
- `value (anyOf branch 3).history[]` — object; required.
- `value (anyOf branch 3).history[].submissionRevision` — integer; required. Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer.
- `value (anyOf branch 3).history[].payloadSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the canonical submitted payload.
- `value (anyOf branch 3).history[].outcome` — "repair_required" | "needs_attention" | "version_conflict" | "completed"; required. Typed result of this operation; union branches define the follow-up action for each value. Allowed values: "repair_required", "needs_attention", "version_conflict", "completed".
- `value (anyOf branch 3).history[].violations` — array; required. Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items.
- `value (anyOf branch 3).history[].violations[]` — object; required.
- `value (anyOf branch 3).history[].violations[].pointer` — string; required. RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root.
- `value (anyOf branch 3).history[].violations[].ruleId` — string; required. Stable validation-rule identifier for this violation.
- `value (anyOf branch 3).history[].violations[].remediationCategory` — string; required. Machine-readable category describing the required correction.
- `value (anyOf branch 3).history[].violations[].message` — string; required. User-facing validation or remediation message that contains no secret material.
- `value (anyOf branch 3).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 3).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 3).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 3).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 3).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 3).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 3).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 3).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 3).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 3).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 3).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 3).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 3).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 3).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 3).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 3).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 3).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 3).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 3).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 3).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 3).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 3).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 3).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 3).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 3).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 3).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 3).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 3).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 3).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 3).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
- `value (anyOf branch 4)` — object; optional.
- `value (anyOf branch 4).status` — constant "version_conflict"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "version_conflict".
- `value (anyOf branch 4).pinnedBriefBaseVersionId` — string; required. Immutable brief-version identifier frozen when the execution began and used for stale-base detection.
- `value (anyOf branch 4).pinnedBriefBaseVersionNum` — integer; required. Monotonic brief-version number frozen when the execution began and used for stale-base detection. The value must be an integer.
- `value (anyOf branch 4).currentBriefVersionId` — string; required. Immutable identifier of the current canonical brief version reported after a stale-base rejection.
- `value (anyOf branch 4).currentBriefVersionNum` — integer; required. Monotonic number of the current canonical brief version reported after a stale-base rejection. The value must be an integer.
- `value (anyOf branch 4).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 4).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 4).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 4).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 4).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 4).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 4).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 4).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 4).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 4).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 4).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 4).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 4).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 4).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 4).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 4).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 4).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 4).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 4).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 4).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 4).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 4).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 4).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 4).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 4).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 4).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 4).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 4).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 4).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 4).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "completed",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"completed\"."
},
"outcome": {
"type": "string",
"enum": [
"version_created",
"no_change"
],
"description": "Typed result of this operation; union branches define the follow-up action for each value. Allowed values: \"version_created\", \"no_change\"."
},
"briefVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable brief-version identifier created or selected by finalization; null means no version was produced. A null value explicitly means no current value is available."
},
"briefVersionNum": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Monotonic brief-version number created or selected by finalization; null means no version was produced. A null value explicitly means no current value is available. The value must be an integer."
},
"certificateReference": {
"anyOf": [
{
"type": "object",
"properties": {
"certificateId": {
"type": "string",
"description": "Execution-certificate identifier assigned after successful finalization."
},
"state": {
"type": "string",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
}
},
"required": [
"certificateId",
"state"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Reference to the terminal execution certificate when finalization has produced one; null means no certificate exists yet. A null value explicitly means no current value is available."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
},
"cascade": {
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "awaiting_local_claim",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"awaiting_local_claim\"."
},
"runId": {
"type": "string",
"description": "Review-run identifier returned by a review start, status, or cascade handoff result."
},
"reviewSessionId": {
"type": [
"string",
"null"
],
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available."
},
"cascadeStepId": {
"type": "string",
"description": "Identifier of the configured reviewer-cascade step associated with this run."
},
"grantApprovalUri": {
"type": "string",
"description": "Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"runId",
"reviewSessionId",
"cascadeStepId",
"controlBlock"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "in_progress",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"in_progress\"."
},
"runId": {
"type": "string",
"description": "Review-run identifier returned by a review start, status, or cascade handoff result."
},
"reviewSessionId": {
"type": [
"string",
"null"
],
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available."
},
"cascadeStepId": {
"type": "string",
"description": "Identifier of the configured reviewer-cascade step associated with this run."
},
"execution": {
"anyOf": [
{
"type": "string",
"enum": [
"hosted",
"local"
]
},
{
"type": "null"
}
],
"description": "Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available. Allowed values: \"hosted\", \"local\"."
}
},
"required": [
"status",
"runId",
"reviewSessionId",
"cascadeStepId",
"execution"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "settled",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"settled\"."
},
"runId": {
"type": "string",
"description": "Review-run identifier returned by a review start, status, or cascade handoff result."
},
"cascadeStepId": {
"type": "string",
"description": "Identifier of the configured reviewer-cascade step associated with this run."
},
"runStatus": {
"type": "string",
"description": "Terminal or current review-run status returned by finalization when no additional cascade dispatch is required."
}
},
"required": [
"status",
"runId",
"cascadeStepId",
"runStatus"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "gate_wait",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"gate_wait\"."
},
"cascadeStepId": {
"type": "string",
"description": "Identifier of the configured reviewer-cascade step associated with this run."
}
},
"required": [
"status",
"cascadeStepId"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "blocked",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"blocked\"."
},
"cascadeStepId": {
"type": "string",
"description": "Identifier of the configured reviewer-cascade step associated with this run."
},
"reason": {
"type": "string",
"const": "cap_exceeded",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. This branch always uses \"cap_exceeded\"."
},
"hardCapCents": {
"type": "integer",
"description": "Workspace hard spending cap in integer US-dollar cents. The value must be an integer."
},
"spentThisMonthCents": {
"type": "integer",
"description": "Workspace spend in integer US-dollar cents for the current billing month. The value must be an integer."
}
},
"required": [
"status",
"cascadeStepId",
"reason",
"hardCapCents",
"spentThisMonthCents"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "cascade_complete",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"cascade_complete\"."
}
},
"required": [
"status"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "none",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"none\"."
}
},
"required": [
"status"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "pending",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"pending\"."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required."
}
},
"required": [
"status",
"reason"
],
"additionalProperties": false
}
],
"description": "Observed next-step cascade handoff after submission or review admission. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"status",
"outcome",
"briefVersionId",
"briefVersionNum",
"certificateReference",
"controlBlock"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "repair_required",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"repair_required\"."
},
"submissionRevision": {
"type": "integer",
"description": "Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer."
},
"payloadSha256": {
"type": "string",
"description": "Lowercase hexadecimal SHA-256 digest of the canonical submitted payload."
},
"violations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pointer": {
"type": "string",
"description": "RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root."
},
"ruleId": {
"type": "string",
"description": "Stable validation-rule identifier for this violation."
},
"remediationCategory": {
"type": "string",
"description": "Machine-readable category describing the required correction."
},
"message": {
"type": "string",
"description": "User-facing validation or remediation message that contains no secret material."
}
},
"required": [
"pointer",
"ruleId",
"remediationCategory",
"message"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items."
},
"remainingRepairAttempts": {
"type": "integer",
"minimum": 0,
"description": "Distinct corrected submissions still allowed before operator attention is required. Minimum accepted length or value is 0. The value must be an integer."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"submissionRevision",
"payloadSha256",
"violations",
"remainingRepairAttempts",
"controlBlock"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "needs_attention",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"needs_attention\"."
},
"reason": {
"type": "string",
"enum": [
"repair_budget_exhausted",
"non_repairable"
],
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Allowed values: \"repair_budget_exhausted\", \"non_repairable\"."
},
"submissionRevision": {
"type": "integer",
"description": "Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer."
},
"violations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pointer": {
"type": "string",
"description": "RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root."
},
"ruleId": {
"type": "string",
"description": "Stable validation-rule identifier for this violation."
},
"remediationCategory": {
"type": "string",
"description": "Machine-readable category describing the required correction."
},
"message": {
"type": "string",
"description": "User-facing validation or remediation message that contains no secret material."
}
},
"required": [
"pointer",
"ruleId",
"remediationCategory",
"message"
],
"additionalProperties": false
},
"description": "Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items."
},
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"submissionRevision": {
"type": "integer",
"description": "Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer."
},
"payloadSha256": {
"type": "string",
"description": "Lowercase hexadecimal SHA-256 digest of the canonical submitted payload."
},
"outcome": {
"type": "string",
"enum": [
"repair_required",
"needs_attention",
"version_conflict",
"completed"
],
"description": "Typed result of this operation; union branches define the follow-up action for each value. Allowed values: \"repair_required\", \"needs_attention\", \"version_conflict\", \"completed\"."
},
"violations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pointer": {
"type": "string",
"description": "RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root."
},
"ruleId": {
"type": "string",
"description": "Stable validation-rule identifier for this violation."
},
"remediationCategory": {
"type": "string",
"description": "Machine-readable category describing the required correction."
},
"message": {
"type": "string",
"description": "User-facing validation or remediation message that contains no secret material."
}
},
"required": [
"pointer",
"ruleId",
"remediationCategory",
"message"
],
"additionalProperties": false
},
"description": "Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items."
}
},
"required": [
"submissionRevision",
"payloadSha256",
"outcome",
"violations"
],
"additionalProperties": false
},
"description": "Complete safe submission-validation history, oldest attempt first. An empty array explicitly means no matching items."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"reason",
"submissionRevision",
"violations",
"history",
"controlBlock"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "version_conflict",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"version_conflict\"."
},
"pinnedBriefBaseVersionId": {
"type": "string",
"description": "Immutable brief-version identifier frozen when the execution began and used for stale-base detection."
},
"pinnedBriefBaseVersionNum": {
"type": "integer",
"description": "Monotonic brief-version number frozen when the execution began and used for stale-base detection. The value must be an integer."
},
"currentBriefVersionId": {
"type": "string",
"description": "Immutable identifier of the current canonical brief version reported after a stale-base rejection."
},
"currentBriefVersionNum": {
"type": "integer",
"description": "Monotonic number of the current canonical brief version reported after a stale-base rejection. The value must be an integer."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"pinnedBriefBaseVersionId",
"pinnedBriefBaseVersionNum",
"currentBriefVersionId",
"currentBriefVersionNum",
"controlBlock"
],
"additionalProperties": false
}
]
}
```
**Example structured result (completed)**
```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
}
}
}
}
```
Bindings: cascade from structuredContent.cascade.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}}}"
}
],
"structuredContent": {
"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
}
}
}
}
}
```
Next permitted action: Follow cascade.status; request the next grant only for awaiting_local_claim and never wait for certificate signing.
**Example requests**
- “submit my completed review for this session”
Errors: `VALIDATION_FAILED`, `BRIEF_VERSION_CONFLICT`, `QUESTION_OPEN`, `STALE_FENCE`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_status`, `review_execution_checkpoint_append`, `review_execution_grant_request`, `review_status`.
---
### review_execution_sync
Cursor-poll for recorded answers, cancellation, handoff, and lease state.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `cursor` — string; optional; minimum length 1. Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; optional. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 0. The value must be an integer.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"executionId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"cursor": "sync_fixture_next",
"fenceGeneration": 1
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"cursor": "{{syncCursor}}",
"fenceGeneration": 1
}
```
**Returns**
- `answers` — array; required. Accepted durable answers emitted since the requested synchronization cursor, in causal order. An empty array explicitly means no matching items.
- `answers[]` — object; required.
- `answers[].questionId` — string; required. Durable question identifier returned by review_question_open or execution sync.
- `answers[].answerId` — string; required. Immutable answer identifier assigned by Semel when an answer attempt is recorded.
- `answers[].channel` — string; required. Typed delivery or answer channel recorded as provenance.
- `answers[].answerText` — string; required. Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit.
- `answers[].answeredAt` — string; required. RFC 3339 timestamp when the active answer was recorded.
- `cancellationRequested` — boolean; required. Whether a cancellation request is pending for this execution.
- `serverCommands` — array; required. Ordered server commands issued since the supplied synchronization cursor. An empty array explicitly means no matching items.
- `serverCommands[]` — object; required.
- `serverCommands[].command` — string; required. Server-issued synchronization command the harness must process in order.
- `serverCommands[].issuedAt` — string; required. RFC 3339 timestamp when the server command was issued.
- `handoff` — object; required. Execution handoff state relative to the caller’s remembered epoch.
- `handoff.occurred` — boolean; required. Whether an execution handoff occurred since the supplied cursor or epoch.
- `handoff.currentFenceGeneration` — integer; required. Active execution fence generation; refresh local state to this integer before attempting another fenced write. The value must be an integer.
- `lease` — object; required. Current lease identity and expiry as observed during synchronization.
- `lease.fenceGeneration` — JSON value; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. A null value explicitly means no current value is available. The value must be an integer.
- `lease.fenceGeneration (anyOf branch 1)` — integer; required.
- `lease.fenceGeneration (anyOf branch 2)` — null; required.
- `lease.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `lease.current` — boolean; required. Whether the caller-provided fence generation is still the active execution epoch.
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `suggestedNextPollAt` — string; required. RFC 3339 timestamp for the next recommended sync or status poll.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"answers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"questionId": {
"type": "string",
"description": "Durable question identifier returned by review_question_open or execution sync."
},
"answerId": {
"type": "string",
"description": "Immutable answer identifier assigned by Semel when an answer attempt is recorded."
},
"channel": {
"type": "string",
"description": "Typed delivery or answer channel recorded as provenance."
},
"answerText": {
"type": "string",
"description": "Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit."
},
"answeredAt": {
"type": "string",
"description": "RFC 3339 timestamp when the active answer was recorded."
}
},
"required": [
"questionId",
"answerId",
"channel",
"answerText",
"answeredAt"
],
"additionalProperties": false
},
"description": "Accepted durable answers emitted since the requested synchronization cursor, in causal order. An empty array explicitly means no matching items."
},
"cancellationRequested": {
"type": "boolean",
"description": "Whether a cancellation request is pending for this execution."
},
"serverCommands": {
"type": "array",
"items": {
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "Server-issued synchronization command the harness must process in order."
},
"issuedAt": {
"type": "string",
"description": "RFC 3339 timestamp when the server command was issued."
}
},
"required": [
"command",
"issuedAt"
],
"additionalProperties": false
},
"description": "Ordered server commands issued since the supplied synchronization cursor. An empty array explicitly means no matching items."
},
"handoff": {
"type": "object",
"properties": {
"occurred": {
"type": "boolean",
"description": "Whether an execution handoff occurred since the supplied cursor or epoch."
},
"currentFenceGeneration": {
"type": "integer",
"description": "Active execution fence generation; refresh local state to this integer before attempting another fenced write. The value must be an integer."
}
},
"required": [
"occurred",
"currentFenceGeneration"
],
"additionalProperties": false,
"description": "Execution handoff state relative to the caller’s remembered epoch."
},
"lease": {
"type": "object",
"properties": {
"fenceGeneration": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. A null value explicitly means no current value is available. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"current": {
"type": "boolean",
"description": "Whether the caller-provided fence generation is still the active execution epoch."
}
},
"required": [
"fenceGeneration",
"leaseExpiresAt",
"current"
],
"additionalProperties": false,
"description": "Current lease identity and expiry as observed during synchronization."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
},
"suggestedNextPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended sync or status poll."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"answers",
"cancellationRequested",
"serverCommands",
"handoff",
"lease",
"nextCursor",
"suggestedNextPollAt",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (sync)**
```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
}
}
}
```
Bindings: nextCursor from structuredContent.nextCursor.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}}"
}
],
"structuredContent": {
"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
}
}
}
}
```
Next permitted action: Apply answers, cancellation, handoff, lease, and server commands before more work.
**Example requests**
- “check whether the operator answered my open question yet”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `review_question_answer`, `review_execution_status`.
---
### review_new_pass
Start a repeat AI review pass for a brief, re-reviewing the current draft; anchor on a prior run from review_status. Hosted by default, or `execution:'local'` to leave it queued for a BYO harness to claim (requires review:execute).
- Mode: write
- Risk: high
- Scopes: `brief:read`, `review:run`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1.
- `anchorRunId` — string; required; minimum length 1. Completed review-run identifier used as the starting point for a new pass; obtain it from review_status or review_start. Minimum accepted length or value is 1.
- `execution` — "hosted" | "local"; optional. Requested or observed execution lane: hosted Semel execution or local external execution. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: "hosted", "local".
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1."
},
"anchorRunId": {
"type": "string",
"minLength": 1,
"description": "Completed review-run identifier used as the starting point for a new pass; obtain it from review_status or review_start. Minimum accepted length or value is 1."
},
"execution": {
"type": "string",
"enum": [
"hosted",
"local"
],
"description": "Requested or observed execution lane: hosted Semel execution or local external execution. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: \"hosted\", \"local\"."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"briefId",
"anchorRunId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"anchorRunId": "run_fixture_review",
"execution": "local",
"idempotencyKey": "recipe-review-new-pass-v1"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"anchorRunId": "{{anchorRunId}}",
"execution": "local",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `run` — object; required. Newly created review run and its queue position.
- `run.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `run.status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `run.position` — integer; required; minimum 0. Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer.
- `cascade` — object; required. Observed next-step cascade handoff after submission or review admission.
- `cascade.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `cascade.phase` — string; required. Current cascade phase reported by Semel.
- `dispatch` — object; optional. Post-commit admission and dispatch result for the newly created review run. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.status` — "invoking" | "queued" | "evidence_wait" | "settled" | "awaiting_local_claim"; required. Current typed status; the schema enum or union branch lists every allowed value. Allowed values: "invoking", "queued", "evidence_wait", "settled", "awaiting_local_claim".
- `dispatch.admitted` — boolean; required. Whether the review run was admitted for execution.
- `dispatch.softCapWarning` — boolean; required. Optional nonblocking workspace spending warning attached to admission.
- `dispatch.evidenceWait` — object; optional. Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.evidenceWait.manifestId` — string; required. Evidence manifest identifier whose readiness is being reported.
- `dispatch.evidenceWait.state` — constant "pending"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "pending".
- `dispatch.evidenceWait.deadlineAt` — string; required. RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision.
- `dispatch.evidenceWait.requiredRepositoryCount` — integer; required; minimum 0. Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer.
- `dispatch.evidenceWait.unavailableRepositoryCount` — integer; required; minimum 0. Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer.
- `dispatch.evidenceWait.statusPath` — string; required. Relative Semel API path for polling evidence readiness.
- `dispatch.evidenceWait.decisionPath` — string; required. Relative Semel API path for the human evidence-wait decision.
- `dispatch.evidenceWait.actions` — array; required. User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items.
- `dispatch.evidenceWait.actions[]` — string; required.
- `dispatch.reviewSessionId` — string; optional. Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.grantApprovalUri` — string; optional. Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock` — object; optional. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `dispatch.controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `dispatch.controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `dispatch.controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `dispatch.controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `dispatch.controlBlock.allowedNextOperations[]` — object; required.
- `dispatch.controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `dispatch.controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `dispatch.controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `dispatch.controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `dispatch.controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `dispatch.controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `dispatch.controlBlock.completion.unmetRequirements[]` — string; required.
- `dispatch.controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `dispatch.controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `dispatch.controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `dispatch.controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `dispatch.controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `dispatch.controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `dispatch.controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `dispatch.controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `dispatch.controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `dispatch.controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `dispatch.controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `dispatch.controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `dispatch.controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `dispatch.controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `dispatch.controlBlock.error.permittedNextOperations[]` — string; required.
- `dispatch.controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"run": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"status": {
"type": "string",
"description": "Current typed status; the schema enum or union branch lists every allowed value."
},
"position": {
"type": "integer",
"minimum": 0,
"description": "Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"id",
"status",
"position"
],
"additionalProperties": false,
"description": "Newly created review run and its queue position."
},
"cascade": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"phase": {
"type": "string",
"description": "Current cascade phase reported by Semel."
}
},
"required": [
"projectId",
"phase"
],
"additionalProperties": false,
"description": "Observed next-step cascade handoff after submission or review admission."
},
"dispatch": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"invoking",
"queued",
"evidence_wait",
"settled",
"awaiting_local_claim"
],
"description": "Current typed status; the schema enum or union branch lists every allowed value. Allowed values: \"invoking\", \"queued\", \"evidence_wait\", \"settled\", \"awaiting_local_claim\"."
},
"admitted": {
"type": "boolean",
"description": "Whether the review run was admitted for execution."
},
"softCapWarning": {
"type": "boolean",
"description": "Optional nonblocking workspace spending warning attached to admission."
},
"evidenceWait": {
"type": "object",
"properties": {
"manifestId": {
"type": "string",
"description": "Evidence manifest identifier whose readiness is being reported."
},
"state": {
"type": "string",
"const": "pending",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"pending\"."
},
"deadlineAt": {
"type": "string",
"description": "RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision."
},
"requiredRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer."
},
"unavailableRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer."
},
"statusPath": {
"type": "string",
"description": "Relative Semel API path for polling evidence readiness."
},
"decisionPath": {
"type": "string",
"description": "Relative Semel API path for the human evidence-wait decision."
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items."
}
},
"required": [
"manifestId",
"state",
"deadlineAt",
"requiredRepositoryCount",
"unavailableRepositoryCount",
"statusPath",
"decisionPath",
"actions"
],
"additionalProperties": false,
"description": "Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reviewSessionId": {
"type": "string",
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value."
},
"grantApprovalUri": {
"type": "string",
"description": "Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"status",
"admitted",
"softCapWarning"
],
"additionalProperties": false,
"description": "Post-commit admission and dispatch result for the newly created review run. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"run",
"cascade"
],
"additionalProperties": false
}
```
**Example structured result (local-start)**
```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
}
}
```
Bindings: newRunId from structuredContent.run.id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}"
}
],
"structuredContent": {
"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
}
}
}
```
Next permitted action: Request the returned local session grant; do not claim without approval.
**Example requests**
- “/semel re-run the review now that I updated the brief”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `review_start`, `review_status`, `review_execution_status`.
---
### review_question_answer
Record a local_harness answer; first valid terminal answer wins.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `questionId` — string; required; minimum length 1. Durable question identifier returned by review_question_open or execution sync. Minimum accepted length or value is 1.
- `answerText` — string; required; minimum length 1; maximum length 20000. Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit. Accepted length or value is 1 through 20000, inclusive.
- `transmittingAgent` — string; optional; maximum length 200. Optional harness-declared agent identity that transmitted the answer. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `humanAttribution` — object; optional. Optional harness-attested human identity; it is not verified identity. Omit the field when it does not apply; omission is distinct from an empty value.
- `humanAttribution.claimedName` — string; optional; maximum length 200. Optional human name claimed by the harness; it is not verified by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `humanAttribution.claimedEmail` — string; optional; format email. Optional human email claimed by the harness; it is not verified by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Use a syntactically valid email address.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"questionId": {
"type": "string",
"minLength": 1,
"description": "Durable question identifier returned by review_question_open or execution sync. Minimum accepted length or value is 1."
},
"answerText": {
"type": "string",
"minLength": 1,
"maxLength": 20000,
"description": "Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit. Accepted length or value is 1 through 20000, inclusive."
},
"transmittingAgent": {
"type": "string",
"maxLength": 200,
"description": "Optional harness-declared agent identity that transmitted the answer. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"humanAttribution": {
"type": "object",
"properties": {
"claimedName": {
"type": "string",
"maxLength": 200,
"description": "Optional human name claimed by the harness; it is not verified by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"claimedEmail": {
"type": "string",
"format": "email",
"description": "Optional human email claimed by the harness; it is not verified by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Use a syntactically valid email address."
}
},
"additionalProperties": false,
"description": "Optional harness-attested human identity; it is not verified identity. Omit the field when it does not apply; omission is distinct from an empty value."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"questionId",
"answerText",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"questionId": "q_fixture_database",
"answerText": "Use online expand/contract.",
"transmittingAgent": "codex",
"humanAttribution": {
"claimedName": "Repository owner"
},
"idempotencyKey": "recipe-question-answer-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"questionId": "{{questionId}}",
"answerText": "Use online expand/contract.",
"transmittingAgent": "codex",
"humanAttribution": {
"claimedName": "Repository owner"
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `outcome` — "accepted" | "conflict"; required. Typed result of this operation; union branches define the follow-up action for each value. Allowed values: "accepted", "conflict".
- `answerId` — string; required. Immutable answer identifier assigned by Semel when an answer attempt is recorded.
- `questionId` — string; required. Durable question identifier returned by review_question_open or execution sync.
- `activeAnswer` — object; required. Question’s current winning immutable answer, including conflict responses.
- `activeAnswer.answerId` — string; required. Immutable answer identifier assigned by Semel when an answer attempt is recorded.
- `activeAnswer.channel` — string; required. Typed delivery or answer channel recorded as provenance.
- `activeAnswer.answerText` — string; required. Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit.
- `activeAnswer.answeredAt` — string; required. RFC 3339 timestamp when the active answer was recorded.
- `roundResumed` — boolean; required. Whether this accepted answer closed the question round and resumed the run.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"outcome": {
"type": "string",
"enum": [
"accepted",
"conflict"
],
"description": "Typed result of this operation; union branches define the follow-up action for each value. Allowed values: \"accepted\", \"conflict\"."
},
"answerId": {
"type": "string",
"description": "Immutable answer identifier assigned by Semel when an answer attempt is recorded."
},
"questionId": {
"type": "string",
"description": "Durable question identifier returned by review_question_open or execution sync."
},
"activeAnswer": {
"type": "object",
"properties": {
"answerId": {
"type": "string",
"description": "Immutable answer identifier assigned by Semel when an answer attempt is recorded."
},
"channel": {
"type": "string",
"description": "Typed delivery or answer channel recorded as provenance."
},
"answerText": {
"type": "string",
"description": "Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit."
},
"answeredAt": {
"type": "string",
"description": "RFC 3339 timestamp when the active answer was recorded."
}
},
"required": [
"answerId",
"channel",
"answerText",
"answeredAt"
],
"additionalProperties": false,
"description": "Question’s current winning immutable answer, including conflict responses."
},
"roundResumed": {
"type": "boolean",
"description": "Whether this accepted answer closed the question round and resumed the run."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"outcome",
"answerId",
"questionId",
"activeAnswer",
"roundResumed",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (accepted-answer)**
```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
}
}
}
```
Bindings: activeAnswer from structuredContent.activeAnswer.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}}"
}
],
"structuredContent": {
"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
}
}
}
}
```
Next permitted action: Resume dependent work only when this answer is accepted or matches the existing winner.
**Example requests**
- “the operator just told me the answer locally”
Errors: `STALE_FENCE`, `CANCELLED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_question_open`, `review_execution_sync`.
---
### review_question_answer_supersede
Verified-operator correction of an already-accepted answer.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:execute`
- Confirmation: operator_grant
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `questionId` — string; required; minimum length 1. Durable question identifier returned by review_question_open or execution sync. Minimum accepted length or value is 1.
- `correctedAnswerText` — string; required; minimum length 1; maximum length 20000. Replacement answer text supplied by a verified operator while preserving answer history. Accepted length or value is 1 through 20000, inclusive.
- `reason` — string; optional; maximum length 2000. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 2000.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"questionId": {
"type": "string",
"minLength": 1,
"description": "Durable question identifier returned by review_question_open or execution sync. Minimum accepted length or value is 1."
},
"correctedAnswerText": {
"type": "string",
"minLength": 1,
"maxLength": 20000,
"description": "Replacement answer text supplied by a verified operator while preserving answer history. Accepted length or value is 1 through 20000, inclusive."
},
"reason": {
"type": "string",
"maxLength": 2000,
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 2000."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"questionId",
"correctedAnswerText",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"questionId": "q_fixture_database",
"correctedAnswerText": "Use an online expand/contract migration with a compatibility window.",
"reason": "Owner clarified rollback requirements.",
"idempotencyKey": "recipe-question-supersede-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"questionId": "{{questionId}}",
"correctedAnswerText": "Use an online expand/contract migration with a compatibility window.",
"reason": "Owner clarified rollback requirements.",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `outcome` — constant "accepted"; required. Typed result of this operation; union branches define the follow-up action for each value. This branch always uses "accepted".
- `newAnswerId` — string; required. Immutable identifier of the corrected answer created by a successful supersede operation.
- `supersededAnswerId` — string; required. Immutable identifier of the prior answer replaced by a successful supersede operation.
- `recoveryCursor` — object; required. Causal boundary the harness must use after an operator corrects an answer.
- `recoveryCursor.invalidatedFromSeq` — integer; required; minimum 0. First checkpoint sequence considered downstream of the corrected answer. Minimum accepted length or value is 0. The value must be an integer.
- `recoveryCursor.activeSkillCursor` — string | null; required. Opaque cursor naming the active pinned skill; null means no skill is currently active. A null value explicitly means no current value is available.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"outcome": {
"type": "string",
"const": "accepted",
"description": "Typed result of this operation; union branches define the follow-up action for each value. This branch always uses \"accepted\"."
},
"newAnswerId": {
"type": "string",
"description": "Immutable identifier of the corrected answer created by a successful supersede operation."
},
"supersededAnswerId": {
"type": "string",
"description": "Immutable identifier of the prior answer replaced by a successful supersede operation."
},
"recoveryCursor": {
"type": "object",
"properties": {
"invalidatedFromSeq": {
"type": "integer",
"minimum": 0,
"description": "First checkpoint sequence considered downstream of the corrected answer. Minimum accepted length or value is 0. The value must be an integer."
},
"activeSkillCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor naming the active pinned skill; null means no skill is currently active. A null value explicitly means no current value is available."
}
},
"required": [
"invalidatedFromSeq",
"activeSkillCursor"
],
"additionalProperties": false,
"description": "Causal boundary the harness must use after an operator corrects an answer."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"outcome",
"newAnswerId",
"supersededAnswerId",
"recoveryCursor",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (superseded)**
```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
}
}
}
```
Bindings: recoveryCursor from structuredContent.recoveryCursor.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}}"
}
],
"structuredContent": {
"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
}
}
}
}
```
Next permitted action: Rework from recoveryCursor before final submission.
**Example requests**
- “the operator corrected an earlier answer”
Errors: `VALIDATION_FAILED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_question_answer`, `review_execution_status`.
---
### review_question_open
Durably create a question before displaying or delivering it anywhere.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `clientQuestionId` — string; required; minimum length 1; maximum length 200. Caller-stable logical question identifier; it must equal the MCP idempotency key for this call. Accepted length or value is 1 through 200, inclusive.
- `text` — string; required; minimum length 1; maximum length 20000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 20000, inclusive.
- `reviewerRole` — "product" | "engineering" | "design" | "security" | "test"; optional. Reviewer role attributed to this question, finding, or version. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: "product", "engineering", "design", "security", "test".
- `contextExcerpt` — string; optional; maximum length 20000. Optional bounded context shown with the question; omit when the question is self-contained. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 20000.
- `section` — string; optional; maximum length 200. Canonical brief section key associated with the question, finding, proposal, or decision entry. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `options` — array; optional; minimum items 2; maximum items 5. Explicit answer choices for a decision question; omission means the respondent may provide free-form text. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `options[]` — string; required; minimum length 1; maximum length 500.
- `citations` — array; optional. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `citations[]` — JSON value; required.
- `citations[] (anyOf branch 1)` — object; required.
- `citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: "goal", "userPersonaContext", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `citations[] (anyOf branch 1).briefId` — string; required. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary.
- `citations[] (anyOf branch 1).contractVersionId` — string; required. Immutable brief contract-version identifier resolved by Semel.
- `citations[] (anyOf branch 1).versionNum` — integer; optional. Monotonic brief contract version number assigned by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 0. The value must be an integer.
- `citations[] (anyOf branch 1).reviewers` — array; required; minimum items 1. Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
- `citations[] (anyOf branch 1).reviewers[]` — "product" | "engineering" | "design" | "security" | "test"; required.
- `citations[] (anyOf branch 1).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `citations[] (anyOf branch 2)` — object; required.
- `citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `citations[] (anyOf branch 2).extractedTextHash` — string; required. Hash of the normalized text extracted from the cited artifact, used to bind the citation to exact processed content.
- `citations[] (anyOf branch 2).reviewers` — array; required; minimum items 1. Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
- `citations[] (anyOf branch 2).reviewers[]` — "product" | "engineering" | "design" | "security" | "test"; required.
- `citations[] (anyOf branch 2).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `citations[] (anyOf branch 3)` — object; required.
- `citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `citations[] (anyOf branch 3).evidenceManifestId` — string; required; minimum length 1. Immutable evidence-manifest identifier captured for the review run. Minimum accepted length or value is 1.
- `citations[] (anyOf branch 3).evidenceManifestItemId` — string; required; minimum length 1. Identifier of the exact item inside the immutable evidence manifest. Minimum accepted length or value is 1.
- `citations[] (anyOf branch 3).workspaceRepositoryId` — string; required; minimum length 1. Workspace-scoped connected repository identifier recorded in evidence provenance. Minimum accepted length or value is 1.
- `citations[] (anyOf branch 3).revisionId` — string; required; minimum length 1. Immutable indexed repository revision identifier. Minimum accepted length or value is 1.
- `citations[] (anyOf branch 3).commitSha` — string; required. Git commit SHA pinned by the evidence manifest.
- `citations[] (anyOf branch 3).blobSha` — string; required. Git blob SHA for the cited file contents.
- `citations[] (anyOf branch 3).path` — string; required; minimum length 1. Repository-relative source path; it never denotes an arbitrary local filesystem path. Minimum accepted length or value is 1.
- `citations[] (anyOf branch 3).startLine` — integer; required. One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `citations[] (anyOf branch 3).endLine` — integer; required. One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `citations[] (anyOf branch 3).excerptSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the exact cited excerpt.
- `citations[] (anyOf branch 3).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `citations[] (anyOf branch 3).coverage` — object; required. Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence.
- `citations[] (anyOf branch 3).coverage{key}` — JSON value; optional.
- `citations[] (anyOf branch 3).reviewers` — array; required; minimum items 1. Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
- `citations[] (anyOf branch 3).reviewers[]` — "product" | "engineering" | "design" | "security" | "test"; required.
- `citations[] (anyOf branch 3).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `responseDeadlineHint` — string; optional; format date-time. Optional RFC 3339 requested deadline; Semel clamps it to the documented server bounds. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"clientQuestionId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Caller-stable logical question identifier; it must equal the MCP idempotency key for this call. Accepted length or value is 1 through 200, inclusive."
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 20000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 20000, inclusive."
},
"reviewerRole": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Reviewer role attributed to this question, finding, or version. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
},
"contextExcerpt": {
"type": "string",
"maxLength": 20000,
"description": "Optional bounded context shown with the question; omit when the question is self-contained. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 20000."
},
"section": {
"type": "string",
"maxLength": 200,
"description": "Canonical brief section key associated with the question, finding, proposal, or decision entry. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"options": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 500
},
"minItems": 2,
"maxItems": 5,
"description": "Explicit answer choices for a decision question; omission means the respondent may provide free-form text. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"citations": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "brief-section",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"brief-section\"."
},
"sectionKey": {
"type": "string",
"enum": [
"goal",
"userPersonaContext",
"scope",
"outOfScope",
"requirements",
"edgeCases",
"acceptanceCriteria",
"rolesPermissions",
"states",
"productSolution",
"technicalSolution",
"dataModelImplications",
"architectureAssumptions",
"design",
"testingQaChecklist",
"testPlanUnit",
"testPlanIntegration",
"testPlanUiUx",
"openQuestions",
"generatedTickets",
"requiredEvidence",
"decisions",
"sourceArtifactLinks"
],
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result. Allowed values: \"goal\", \"userPersonaContext\", \"scope\", \"outOfScope\", \"requirements\", \"edgeCases\", \"acceptanceCriteria\", \"rolesPermissions\", \"states\", \"productSolution\", \"technicalSolution\", \"dataModelImplications\", \"architectureAssumptions\", \"design\", \"testingQaChecklist\", \"testPlanUnit\", \"testPlanIntegration\", \"testPlanUiUx\", \"openQuestions\", \"generatedTickets\", \"requiredEvidence\", \"decisions\", \"sourceArtifactLinks\"."
},
"statementId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
},
"briefId": {
"type": "string",
"description": "Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary."
},
"contractVersionId": {
"type": "string",
"description": "Immutable brief contract-version identifier resolved by Semel."
},
"versionNum": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Monotonic brief contract version number assigned by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 0. The value must be an integer."
},
"reviewers": {
"type": "array",
"items": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
"minItems": 1,
"description": "Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items."
},
"verification": {
"type": "string",
"enum": [
"exact",
"canonical",
"unverified"
],
"description": "Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: \"exact\", \"canonical\", \"unverified\"."
}
},
"required": [
"sourceType",
"sectionKey",
"verbatim",
"briefId",
"contractVersionId",
"reviewers",
"verification"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "artifact",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"artifact\"."
},
"artifactId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
},
"extractedTextHash": {
"type": "string",
"description": "Hash of the normalized text extracted from the cited artifact, used to bind the citation to exact processed content."
},
"reviewers": {
"type": "array",
"items": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
"minItems": 1,
"description": "Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items."
},
"verification": {
"type": "string",
"enum": [
"exact",
"canonical",
"unverified"
],
"description": "Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: \"exact\", \"canonical\", \"unverified\"."
}
},
"required": [
"sourceType",
"artifactId",
"verbatim",
"extractedTextHash",
"reviewers",
"verification"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "repository-code",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"repository-code\"."
},
"citationKey": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
},
"evidenceManifestId": {
"type": "string",
"minLength": 1,
"description": "Immutable evidence-manifest identifier captured for the review run. Minimum accepted length or value is 1."
},
"evidenceManifestItemId": {
"type": "string",
"minLength": 1,
"description": "Identifier of the exact item inside the immutable evidence manifest. Minimum accepted length or value is 1."
},
"workspaceRepositoryId": {
"type": "string",
"minLength": 1,
"description": "Workspace-scoped connected repository identifier recorded in evidence provenance. Minimum accepted length or value is 1."
},
"revisionId": {
"type": "string",
"minLength": 1,
"description": "Immutable indexed repository revision identifier. Minimum accepted length or value is 1."
},
"commitSha": {
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$",
"description": "Git commit SHA pinned by the evidence manifest."
},
"blobSha": {
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$",
"description": "Git blob SHA for the cited file contents."
},
"path": {
"type": "string",
"minLength": 1,
"description": "Repository-relative source path; it never denotes an arbitrary local filesystem path. Minimum accepted length or value is 1."
},
"startLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
},
"endLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
},
"excerptSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest of the exact cited excerpt."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"coverage": {
"type": "object",
"additionalProperties": {},
"description": "Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence."
},
"reviewers": {
"type": "array",
"items": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
"minItems": 1,
"description": "Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items."
},
"verification": {
"type": "string",
"enum": [
"exact",
"canonical",
"unverified"
],
"description": "Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: \"exact\", \"canonical\", \"unverified\"."
}
},
"required": [
"sourceType",
"citationKey",
"verbatim",
"evidenceManifestId",
"evidenceManifestItemId",
"workspaceRepositoryId",
"revisionId",
"commitSha",
"blobSha",
"path",
"startLine",
"endLine",
"excerptSha256",
"route",
"coverage",
"reviewers",
"verification"
],
"additionalProperties": false
}
]
},
"description": "Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"responseDeadlineHint": {
"type": "string",
"format": "date-time",
"description": "Optional RFC 3339 requested deadline; Semel clamps it to the documented server bounds. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"clientQuestionId",
"text",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"clientQuestionId": "recipe-question-open-v1",
"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": "recipe-question-open-v1"
}
```
**Binding template**
```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}}"
}
```
**Returns**
- `questionId` — string; required. Durable question identifier returned by review_question_open or execution sync.
- `deduped` — boolean; required. Whether the existing durable question was returned for an idempotent replay.
- `responseDeadline` — string; required. RFC 3339 timestamp after which the unanswered question requires recovery.
- `deliveryState` — array; required. Per-channel best-effort question notification outcomes. An empty array explicitly means no matching items.
- `deliveryState[]` — object; required.
- `deliveryState[].channel` — "in_app" | "slack"; required. Typed delivery or answer channel recorded as provenance. Allowed values: "in_app", "slack".
- `deliveryState[].state` — "delivered" | "degraded" | "not_configured"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "delivered", "degraded", "not_configured".
- `deliveryState[].providerRef` — string; optional. Optional opaque delivery-provider receipt for the question notification; it is provenance, not a question identifier. Omit the field when it does not apply; omission is distinct from an empty value.
- `deliveryState[].safeError` — string; optional. Sanitized provider error category; omission means no safe delivery error was recorded. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"questionId": {
"type": "string",
"description": "Durable question identifier returned by review_question_open or execution sync."
},
"deduped": {
"type": "boolean",
"description": "Whether the existing durable question was returned for an idempotent replay."
},
"responseDeadline": {
"type": "string",
"description": "RFC 3339 timestamp after which the unanswered question requires recovery."
},
"deliveryState": {
"type": "array",
"items": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": [
"in_app",
"slack"
],
"description": "Typed delivery or answer channel recorded as provenance. Allowed values: \"in_app\", \"slack\"."
},
"state": {
"type": "string",
"enum": [
"delivered",
"degraded",
"not_configured"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"delivered\", \"degraded\", \"not_configured\"."
},
"providerRef": {
"type": "string",
"description": "Optional opaque delivery-provider receipt for the question notification; it is provenance, not a question identifier. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeError": {
"type": "string",
"description": "Sanitized provider error category; omission means no safe delivery error was recorded. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"channel",
"state"
],
"additionalProperties": false
},
"description": "Per-channel best-effort question notification outcomes. An empty array explicitly means no matching items."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"questionId",
"deduped",
"responseDeadline",
"deliveryState",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (question-opened)**
```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
}
}
}
```
Bindings: questionId from structuredContent.questionId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"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}}}"
}
],
"structuredContent": {
"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
}
}
}
}
```
Next permitted action: Display the durable question and its options only after this call succeeds.
**Example requests**
- “ask the operator whether this endpoint should require auth”
Errors: `STALE_FENCE`, `CANCELLED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_question_answer`, `review_execution_sync`.
---
### review_start
Start the first AI review cascade (product → engineering → design → security → test) for a brief's project — hosted by default, or `execution:'local'` to leave it queued for a BYO harness to claim (requires review:execute).
- Mode: write
- Risk: high
- Scopes: `brief:read`, `review:run`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1.
- `execution` — "hosted" | "local"; optional. Requested or observed execution lane: hosted Semel execution or local external execution. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: "hosted", "local".
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1."
},
"execution": {
"type": "string",
"enum": [
"hosted",
"local"
],
"description": "Requested or observed execution lane: hosted Semel execution or local external execution. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: \"hosted\", \"local\"."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"briefId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"execution": "hosted",
"idempotencyKey": "recipe-review-start-v1"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"execution": "hosted",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `run` — object; required. Newly created review run and its queue position.
- `run.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `run.status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `run.position` — integer; required; minimum 0. Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer.
- `cascade` — object; required. Observed next-step cascade handoff after submission or review admission.
- `cascade.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `cascade.phase` — string; required. Current cascade phase reported by Semel.
- `dispatch` — object; optional. Post-commit admission and dispatch result for the newly created review run. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.status` — "invoking" | "queued" | "evidence_wait" | "settled" | "awaiting_local_claim"; required. Current typed status; the schema enum or union branch lists every allowed value. Allowed values: "invoking", "queued", "evidence_wait", "settled", "awaiting_local_claim".
- `dispatch.admitted` — boolean; required. Whether the review run was admitted for execution.
- `dispatch.softCapWarning` — boolean; required. Optional nonblocking workspace spending warning attached to admission.
- `dispatch.evidenceWait` — object; optional. Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.evidenceWait.manifestId` — string; required. Evidence manifest identifier whose readiness is being reported.
- `dispatch.evidenceWait.state` — constant "pending"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "pending".
- `dispatch.evidenceWait.deadlineAt` — string; required. RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision.
- `dispatch.evidenceWait.requiredRepositoryCount` — integer; required; minimum 0. Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer.
- `dispatch.evidenceWait.unavailableRepositoryCount` — integer; required; minimum 0. Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer.
- `dispatch.evidenceWait.statusPath` — string; required. Relative Semel API path for polling evidence readiness.
- `dispatch.evidenceWait.decisionPath` — string; required. Relative Semel API path for the human evidence-wait decision.
- `dispatch.evidenceWait.actions` — array; required. User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items.
- `dispatch.evidenceWait.actions[]` — string; required.
- `dispatch.reviewSessionId` — string; optional. Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.grantApprovalUri` — string; optional. Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock` — object; optional. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `dispatch.controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `dispatch.controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `dispatch.controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `dispatch.controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `dispatch.controlBlock.allowedNextOperations[]` — object; required.
- `dispatch.controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `dispatch.controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `dispatch.controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `dispatch.controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `dispatch.controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `dispatch.controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `dispatch.controlBlock.completion.unmetRequirements[]` — string; required.
- `dispatch.controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `dispatch.controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `dispatch.controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `dispatch.controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `dispatch.controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `dispatch.controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `dispatch.controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `dispatch.controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `dispatch.controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `dispatch.controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `dispatch.controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `dispatch.controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `dispatch.controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `dispatch.controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `dispatch.controlBlock.error.permittedNextOperations[]` — string; required.
- `dispatch.controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"run": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"status": {
"type": "string",
"description": "Current typed status; the schema enum or union branch lists every allowed value."
},
"position": {
"type": "integer",
"minimum": 0,
"description": "Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"id",
"status",
"position"
],
"additionalProperties": false,
"description": "Newly created review run and its queue position."
},
"cascade": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"phase": {
"type": "string",
"description": "Current cascade phase reported by Semel."
}
},
"required": [
"projectId",
"phase"
],
"additionalProperties": false,
"description": "Observed next-step cascade handoff after submission or review admission."
},
"dispatch": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"invoking",
"queued",
"evidence_wait",
"settled",
"awaiting_local_claim"
],
"description": "Current typed status; the schema enum or union branch lists every allowed value. Allowed values: \"invoking\", \"queued\", \"evidence_wait\", \"settled\", \"awaiting_local_claim\"."
},
"admitted": {
"type": "boolean",
"description": "Whether the review run was admitted for execution."
},
"softCapWarning": {
"type": "boolean",
"description": "Optional nonblocking workspace spending warning attached to admission."
},
"evidenceWait": {
"type": "object",
"properties": {
"manifestId": {
"type": "string",
"description": "Evidence manifest identifier whose readiness is being reported."
},
"state": {
"type": "string",
"const": "pending",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"pending\"."
},
"deadlineAt": {
"type": "string",
"description": "RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision."
},
"requiredRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer."
},
"unavailableRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer."
},
"statusPath": {
"type": "string",
"description": "Relative Semel API path for polling evidence readiness."
},
"decisionPath": {
"type": "string",
"description": "Relative Semel API path for the human evidence-wait decision."
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items."
}
},
"required": [
"manifestId",
"state",
"deadlineAt",
"requiredRepositoryCount",
"unavailableRepositoryCount",
"statusPath",
"decisionPath",
"actions"
],
"additionalProperties": false,
"description": "Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reviewSessionId": {
"type": "string",
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value."
},
"grantApprovalUri": {
"type": "string",
"description": "Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"status",
"admitted",
"softCapWarning"
],
"additionalProperties": false,
"description": "Post-commit admission and dispatch result for the newly created review run. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"run",
"cascade"
],
"additionalProperties": false
}
```
**Example structured result (hosted-start)**
```json
{
"run": {
"id": "run_fixture_review",
"status": "queued",
"position": 0
},
"cascade": {
"projectId": "prj_fixture_checkout",
"phase": "reviewing"
},
"dispatch": {
"status": "invoking",
"admitted": true,
"softCapWarning": false
}
}
```
Bindings: runId from structuredContent.run.id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"run\":{\"id\":\"run_fixture_review\",\"status\":\"queued\",\"position\":0},\"cascade\":{\"projectId\":\"prj_fixture_checkout\",\"phase\":\"reviewing\"},\"dispatch\":{\"status\":\"invoking\",\"admitted\":true,\"softCapWarning\":false}}"
}
],
"structuredContent": {
"run": {
"id": "run_fixture_review",
"status": "queued",
"position": 0
},
"cascade": {
"projectId": "prj_fixture_checkout",
"phase": "reviewing"
},
"dispatch": {
"status": "invoking",
"admitted": true,
"softCapWarning": false
}
}
}
```
Next permitted action: Poll review_status and respect configless, cap, evidence-wait, or in-flight outcomes.
**Example requests**
- “/semel run the review for the checkout brief”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `review_new_pass`, `review_status`, `review_execution_status`.
---
### review_status
Report the current review cascade state for a brief — steps, in-flight status, and the run id to anchor a new pass on.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:run`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1."
}
},
"required": [
"briefId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}"
}
```
**Returns**
- `projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `phase` — string; required. Current cascade phase reported by Semel.
- `inFlight` — boolean; required. Whether the cascade currently has an unsettled run.
- `execution` — JSON value; required. Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available. Allowed values: "hosted", "local".
- `execution (anyOf branch 1)` — "hosted" | "local"; required.
- `execution (anyOf branch 2)` — null; required.
- `awaitingLocalClaim` — boolean; required. Whether the next external run is waiting for a harness claim.
- `steps` — array; required. Configured cascade steps in execution order with their latest run state. An empty array explicitly means no matching items.
- `steps[]` — object; required.
- `steps[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `steps[].position` — integer; required. Stable zero-based or configured ordering position returned by Semel. The value must be an integer.
- `steps[].kind` — string; required. Discriminator identifying the typed variant represented by this object.
- `steps[].status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `steps[].latestRun` — JSON value; required. Latest run for this cascade step; null means the step has not run. A null value explicitly means no current value is available.
- `steps[].latestRun (anyOf branch 1)` — object; required.
- `steps[].latestRun (anyOf branch 1).id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `steps[].latestRun (anyOf branch 1).status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `steps[].latestRun (anyOf branch 1).createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `steps[].latestRun (anyOf branch 1).reviewSessionId` — string | null; required. Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available.
- `steps[].latestRun (anyOf branch 2)` — null; required.
- `latestRunId` — string | null; required. Most recent run identifier in the cascade; null means no run exists. A null value explicitly means no current value is available.
- `latestTerminalRunId` — string | null; required. Most recent terminal run identifier; null means none has settled. A null value explicitly means no current value is available.
- `evidenceWait` — object; optional. Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value.
- `evidenceWait.manifestId` — string; required. Evidence manifest identifier whose readiness is being reported.
- `evidenceWait.state` — constant "pending"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "pending".
- `evidenceWait.deadlineAt` — string; required. RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision.
- `evidenceWait.requiredRepositoryCount` — integer; required; minimum 0. Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer.
- `evidenceWait.unavailableRepositoryCount` — integer; required; minimum 0. Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer.
- `evidenceWait.statusPath` — string; required. Relative Semel API path for polling evidence readiness.
- `evidenceWait.decisionPath` — string; required. Relative Semel API path for the human evidence-wait decision.
- `evidenceWait.actions` — array; required. User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items.
- `evidenceWait.actions[]` — string; required.
- `blocked` — JSON value; required. Non-null spending or configuration condition currently blocking review progress. A null value explicitly means no current value is available.
- `blocked (anyOf branch 1)` — object; required.
- `blocked (anyOf branch 1).reason` — constant "cap_exceeded"; required. Typed or human-readable reason for the current outcome; omission means no reason is required. This branch always uses "cap_exceeded".
- `blocked (anyOf branch 1).hardCapCents` — integer; required. Workspace hard spending cap in integer US-dollar cents. The value must be an integer.
- `blocked (anyOf branch 1).spentThisMonthCents` — integer; required. Workspace spend in integer US-dollar cents for the current billing month. The value must be an integer.
- `blocked (anyOf branch 2)` — null; required.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"phase": {
"type": "string",
"description": "Current cascade phase reported by Semel."
},
"inFlight": {
"type": "boolean",
"description": "Whether the cascade currently has an unsettled run."
},
"execution": {
"anyOf": [
{
"type": "string",
"enum": [
"hosted",
"local"
]
},
{
"type": "null"
}
],
"description": "Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available. Allowed values: \"hosted\", \"local\"."
},
"awaitingLocalClaim": {
"type": "boolean",
"description": "Whether the next external run is waiting for a harness claim."
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"position": {
"type": "integer",
"description": "Stable zero-based or configured ordering position returned by Semel. The value must be an integer."
},
"kind": {
"type": "string",
"description": "Discriminator identifying the typed variant represented by this object."
},
"status": {
"type": "string",
"description": "Current typed status; the schema enum or union branch lists every allowed value."
},
"latestRun": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"status": {
"type": "string",
"description": "Current typed status; the schema enum or union branch lists every allowed value."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
},
"reviewSessionId": {
"type": [
"string",
"null"
],
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available."
}
},
"required": [
"id",
"status",
"createdAt",
"reviewSessionId"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Latest run for this cascade step; null means the step has not run. A null value explicitly means no current value is available."
}
},
"required": [
"id",
"position",
"kind",
"status",
"latestRun"
],
"additionalProperties": false
},
"description": "Configured cascade steps in execution order with their latest run state. An empty array explicitly means no matching items."
},
"latestRunId": {
"type": [
"string",
"null"
],
"description": "Most recent run identifier in the cascade; null means no run exists. A null value explicitly means no current value is available."
},
"latestTerminalRunId": {
"type": [
"string",
"null"
],
"description": "Most recent terminal run identifier; null means none has settled. A null value explicitly means no current value is available."
},
"evidenceWait": {
"type": "object",
"properties": {
"manifestId": {
"type": "string",
"description": "Evidence manifest identifier whose readiness is being reported."
},
"state": {
"type": "string",
"const": "pending",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"pending\"."
},
"deadlineAt": {
"type": "string",
"description": "RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision."
},
"requiredRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer."
},
"unavailableRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer."
},
"statusPath": {
"type": "string",
"description": "Relative Semel API path for polling evidence readiness."
},
"decisionPath": {
"type": "string",
"description": "Relative Semel API path for the human evidence-wait decision."
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items."
}
},
"required": [
"manifestId",
"state",
"deadlineAt",
"requiredRepositoryCount",
"unavailableRepositoryCount",
"statusPath",
"decisionPath",
"actions"
],
"additionalProperties": false,
"description": "Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value."
},
"blocked": {
"anyOf": [
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"const": "cap_exceeded",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. This branch always uses \"cap_exceeded\"."
},
"hardCapCents": {
"type": "integer",
"description": "Workspace hard spending cap in integer US-dollar cents. The value must be an integer."
},
"spentThisMonthCents": {
"type": "integer",
"description": "Workspace spend in integer US-dollar cents for the current billing month. The value must be an integer."
}
},
"required": [
"reason",
"hardCapCents",
"spentThisMonthCents"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Non-null spending or configuration condition currently blocking review progress. A null value explicitly means no current value is available."
}
},
"required": [
"projectId",
"phase",
"inFlight",
"execution",
"awaitingLocalClaim",
"steps",
"latestRunId",
"latestTerminalRunId",
"blocked"
],
"additionalProperties": false
}
```
**Example structured result (review-status)**
```json
{
"projectId": "prj_fixture_checkout",
"phase": "complete",
"inFlight": false,
"execution": "hosted",
"awaitingLocalClaim": false,
"steps": [],
"latestRunId": "run_fixture_review",
"latestTerminalRunId": "run_fixture_review",
"blocked": null
}
```
Bindings: latestRunId from structuredContent.latestRunId; anchorRunId from structuredContent.latestTerminalRunId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"projectId\":\"prj_fixture_checkout\",\"phase\":\"complete\",\"inFlight\":false,\"execution\":\"hosted\",\"awaitingLocalClaim\":false,\"steps\":[],\"latestRunId\":\"run_fixture_review\",\"latestTerminalRunId\":\"run_fixture_review\",\"blocked\":null}"
}
],
"structuredContent": {
"projectId": "prj_fixture_checkout",
"phase": "complete",
"inFlight": false,
"execution": "hosted",
"awaitingLocalClaim": false,
"steps": [],
"latestRunId": "run_fixture_review",
"latestTerminalRunId": "run_fixture_review",
"blocked": null
}
}
```
Next permitted action: Use latestTerminalRunId as the anchor for a later pass only when the user asks.
**Example requests**
- “what is the status of the review for this brief”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `review_start`, `review_new_pass`, `review_execution_status`.
## Calling a tool correctly
Validate the whole advertised input shape, including nested objects and enums, before calling. All tools require `brief:read`; writes add the scopes shown below and an `idempotencyKey`. Bind IDs, hashes, fence tokens, sequence values, and cursors from the previous response’s `structuredContent`. Do not parse display text. Responses may also include an MCP `resource_link`; fetch only a link returned for the active operation and principal.
> **Note:** An unchanged retry is safe only when the response says it is retryable or when you reuse the same idempotency key with identical arguments. After a timeout with no authoritative response, read status before deciding whether to replay.
## What is deliberately not here
Human-only actions do not appear as MCP tools: gate approval/rejection; proposal decision, commit, rebase, or revert; grant mint/approval; destructive review clear/restart; billing/spend; workspace or credential administration; connecting Slack/GitHub/a tracker; provider/BYOK consent; public share links; Brain writes; Done Check; and `/runs/:id/continue`. The codebase exception is `project_codebase_link`, which only links a repository already connected by a person. REST-only web reads and controls also stay outside MCP. If a tool expected by a recipe is missing, request only the needed capability or scope; see [Troubleshooting](https://docs.semel.ai/troubleshooting#missing-tools).
Canonical page: https://docs.semel.ai/tools