Tool reference

Every customer-visible Semel MCP tool — purpose, required scopes, idempotency, common errors, and related tools — generated from the live operation registry.

View as Markdown

On this page

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

write · idempotent (needs idempotencyKey)

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 · low risk
Scopes: brief:read, brief:write
Confirmation: implicit
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/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: brief_update, brief_get_full

Arguments

indexinteger · required: 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.
minimum: 0
expectedTextstring · required: Expected current checklist text at index; a mismatch fails instead of updating the wrong row. Accepted length or value is 1 through 262144, inclusive.
minimum length: 1 · maximum length: 262144
checkedboolean · required: Whether this QA checklist item is currently complete.
ifVersionNuminteger · 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.
briefIdstring · required: Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
minimum length: 1
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Safely update a versioned brief

{
  "briefId": "brf_fixture_checkout",
  "index": 0,
  "expectedText": "API contract reviewed",
  "checked": true,
  "ifVersionNum": 4,
  "idempotencyKey": "recipe-brief-checklist-update-v1"
}

Binding template

{
  "briefId": "{{briefId}}",
  "index": 0,
  "expectedText": "API contract reviewed",
  "checked": true,
  "ifVersionNum": 4,
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

briefobject · required

Current brief record returned by the operation.

brief.idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
brief.projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project.
brief.titlestring · 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.currentVersionHashstring | 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.contentobject · required: Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
Map values · any JSON value
brief.versionNuminteger · required: Monotonic brief contract version number assigned by Semel. The value must be an integer.
brief.createdNewVersionboolean · required: Whether the write changed canonical content and minted a new immutable brief version.
brief.staledApprovalsinteger · required: Number of prior approval rows made stale by this content change. The value must be an integer.

Example structured result · checklist-toggled

{
  "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
  }
}

MCP wire envelope

{
  "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
    }
  }
}

checklistVersionCreated ← structuredContent.brief.createdNewVersion

Next permitted action: Use this atomic result instead of replacing the full checklist.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIED, BRIEF_VERSION_CONFLICTRelated: brief_update, brief_get_full

brief_collection_list

read

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 · low risk
Scopes: brief:read
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel list the version history for this brief”
“/semel show the decision history of the checkout brief”
Errors: PROJECT_ACCESS_DENIED
Related: brief_list, brief_get_full

Arguments

briefIdstring · required: Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
minimum length: 1
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.
cursorstring · optional: Opaque keyset cursor returned as nextCursor by the preceding page for this same brief and collection. Omit to read the first page.
minimum length: 1
limitinteger · optional: Maximum records to return, as an integer from 1 through 200. Omit to use the server default.
minimum: 1 · maximum: 200

Runnable arguments · Locate and inspect a complete brief

{
  "briefId": "brf_fixture_checkout",
  "collection": "decisionHistory",
  "limit": 50
}

Binding template

{
  "briefId": "{{briefId}}",
  "collection": "decisionHistory",
  "limit": 50
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

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".
itemsarray · required: Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
Array item · object
Map values · any JSON value
nextCursorstring | 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.

Example structured result · collection-page

{
  "collection": "decisionHistory",
  "items": [],
  "nextCursor": null
}

MCP wire envelope

{
  "content": [
    {
      "type": "text",
      "text": "{\"collection\":\"decisionHistory\",\"items\":[],\"nextCursor\":null}"
    }
  ],
  "structuredContent": {
    "collection": "decisionHistory",
    "items": [],
    "nextCursor": null
  }
}

nextCursor ← structuredContent.nextCursor

Next permitted action: Repeat with the returned cursor until nextCursor is null.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: brief_list, brief_get_full

brief_create

write · idempotent (needs idempotencyKey)

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 · medium risk
Scopes: brief:read, brief:write
Confirmation: explicit
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel create a brief for the checkout flow”
“/semel start a new brief in the billing project”
Errors: PROJECT_ACCESS_DENIED
Related: brief_update, brief_get_full

Arguments

projectIdstring · required

Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.

minimum length: 1

titlestring · required

Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.

minimum length: 1 · maximum length: 500

contentobject · 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.goalstring · optional

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.

maximum length: 4000

content.userPersonaContextstring · optional

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.

maximum length: 4000

content.scopestring · optional

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.

maximum length: 4000

content.outOfScopestring · optional

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.

maximum length: 4000

content.requirementsarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.edgeCasesarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.acceptanceCriteriaarray · optional

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.

maximum items: 50

Array item · object

content.acceptanceCriteria[].idstring · required

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.

minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

content.acceptanceCriteria[].textstring · required

Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.

minimum length: 1 · maximum length: 1000

content.acceptanceCriteria[].implementationboolean · 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[].manualEvidenceobject · 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.rationalestring · required: Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
content.acceptanceCriteria[].manualEvidence.evidencePathstring · required: Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000

content.rolesPermissionsarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.statesarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.productSolutionstring · optional

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.

maximum length: 4000

content.technicalSolutionstring · optional

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.

maximum length: 4000

content.dataModelImplicationsstring · optional

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.

maximum length: 4000

content.architectureAssumptionsstring · optional

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.

maximum length: 4000

content.designstring · optional

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.

maximum length: 4000

content.testingQaChecklistarray · optional

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.

maximum items: 50

Array item · object

content.testingQaChecklist[].textstring · required: Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
content.testingQaChecklist[].checkedboolean · required: Whether this QA checklist item is currently complete.
content.testingQaChecklist[].addedBystring · optional: 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.
maximum length: 200
content.testingQaChecklist[].checkedBystring · optional: 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.
maximum length: 200
content.testingQaChecklist[].checkedAtstring · optional: 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.
format: date-time

content.testPlanUnitarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.testPlanIntegrationarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.testPlanUiUxarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.openQuestionsarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.generatedTicketsarray · optional

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.

maximum items: 50

Array item · object

content.generatedTickets[].idstring · required: 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.
minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
content.generatedTickets[].titlestring · required: Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
minimum length: 1 · maximum length: 500
content.generatedTickets[].descriptionany of · 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.
any of
Branch 1
maximum length: 10000
Branch 2
content.generatedTickets[].boundCriteriaarray · required: Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items.
maximum items: 50
Array item · string
minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
content.generatedTickets[].boundRequirementsarray · optional: 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.
maximum items: 50
Array item · string
minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

content.requiredEvidencearray · optional

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.

maximum items: 50

Array item · object

content.requiredEvidence[].idstring · required

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.

minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

content.requiredEvidence[].textstring · required

Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.

minimum length: 1 · maximum length: 1000

content.requiredEvidence[].implementationboolean · 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[].manualEvidenceobject · 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.rationalestring · required: Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
content.requiredEvidence[].manualEvidence.evidencePathstring · required: Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000

content.decisionsarray · optional

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.

maximum items: 50

Array item · object

content.decisions[].textstring · required: Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
content.decisions[].sourcestring · optional: 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.
maximum length: 1000
content.decisions[].statedboolean · 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.sourceArtifactLinksarray · optional

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.

maximum items: 50

Array item · object

content.sourceArtifactLinks[].labelstring · required: Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
content.sourceArtifactLinks[].kindstring · optional: 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.
maximum length: 200
content.sourceArtifactLinks[].readboolean · 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.

idempotencyKeystring · required

Caller-unique key making this mutation exactly-once (see the receipt contract).

minimum length: 1

Runnable arguments · Create a brief from Linear issue text

{
  "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

{
  "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}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

briefobject · required

Current brief record returned by the operation.

brief.idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
brief.projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project.
brief.titlestring · 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.currentVersionHashstring | 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.contentobject · required: Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
Map values · any JSON value
brief.versionNuminteger · required: Monotonic brief contract version number assigned by Semel. The value must be an integer.

Example structured result · brief-created

{
  "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
  }
}

MCP wire envelope

{
  "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
    }
  }
}

briefId ← structuredContent.brief.id

Next permitted action: Load the complete persisted aggregate by the returned brief id.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: brief_update, brief_get_full

brief_export_markdown

read

DEPRECATED compatibility export that renders a brief to Markdown only. It is not a verified implementation handoff; use brief_export_package instead.

Mode: read · low risk
Scopes: brief:read
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel export this brief as markdown”
“/semel give me the markdown for the checkout brief”
Errors: PROJECT_ACCESS_DENIED
Related: brief_export_package, brief_get_full

Arguments

briefIdstring · required: Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
minimum length: 1

Runnable arguments · Export a verified implementation package

{
  "briefId": "brf_fixture_checkout"
}

Binding template

{
  "briefId": "{{briefId}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

filenamestring · required

Safe suggested filename for the downloaded export.

resourceany of · 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.

any of

Branch 1

resource.uristring · required: Absolute or same-origin URI for the referenced resource or required operator action.
resource.namestring · required: Human-readable name displayed in Semel.
resource.mimeTypestring · required: Internet media type of the artifact or exported resource; null means the producer did not record one.

Branch 2

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

markdownstring | null · required

Complete Markdown export of the selected brief snapshot. A null value explicitly means no current value is available.

Example structured result · legacy-markdown

{
  "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"
}

MCP wire envelope

{
  "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"
  }
}

legacyResource ← structuredContent.resource

Next permitted action: Label the result deprecated and do not treat it as a verified handoff.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: brief_export_package, brief_get_full

brief_export_package

write · idempotent (needs idempotencyKey)

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 · medium risk
Scopes: brief:read, brief:write
Confirmation: explicit
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel export the checkout brief as an implementation package”
“/semel build the handoff package for this brief”
Errors: PROJECT_ACCESS_DENIED
Related: brief_get_full, brief_export_markdown

Arguments

briefIdstring · required: Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
minimum length: 1
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Export a verified implementation package

{
  "briefId": "brf_fixture_checkout",
  "idempotencyKey": "recipe-brief-export-package-v1"
}

Binding template

{
  "briefId": "{{briefId}}",
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

exportIdstring · required: Opaque identifier assigned to this deterministic export package; use returned download metadata rather than constructing it. Minimum accepted length or value is 1.
minimum length: 1
status"ready" · required: Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "ready".
filenamestring · required: Safe suggested filename for the downloaded export. Minimum accepted length or value is 1.
minimum length: 1
downloadUrlstring · required: 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.
minimum length: 1
manifestSha256string · required: Lowercase hexadecimal SHA-256 digest of the export manifest.
pattern: ^[a-f0-9]{64}$
implementationReadytrue · required: Whether the exported brief satisfies Semel implementation-readiness checks. This branch always uses true.
expiresAtstring · required: RFC 3339 expiration timestamp. Use an RFC 3339 date-time string.
format: date-time
snapshotIdstring · required: Immutable export snapshot identifier used to reproduce the exported brief state. Minimum accepted length or value is 1.
minimum length: 1
contractVersionIdstring · required: Immutable brief contract-version identifier resolved by Semel. Minimum accepted length or value is 1.
minimum length: 1

Example structured result · ready

{
  "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"
}

MCP wire envelope

{
  "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"
  }
}

downloadUrl ← structuredContent.downloadUrl

Next permitted action: Fetch the bearer-authenticated resource before expiresAt and verify the manifest/hash.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: brief_get_full, brief_export_markdown

brief_get_full

read

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 · low risk
Scopes: brief:read
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel show me everything in the checkout brief”
“/semel open the full brief for the billing project”
Errors: PROJECT_ACCESS_DENIED
Related: brief_list, brief_collection_list, brief_export_package

Arguments

briefIdstring · required: Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
minimum length: 1

Runnable arguments · Safely update a versioned brief

{
  "briefId": "brf_fixture_checkout"
}

Binding template

{
  "briefId": "{{briefId}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

briefobject · required

Current brief record returned by the operation.

brief.idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
brief.projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project.
brief.titlestring · 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.currentVersionHashstring | 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.contentobject · required: Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
Map values · any JSON value
brief.versionNuminteger · required: Monotonic brief contract version number assigned by Semel. The value must be an integer.

collectionsobject · required

First page of each durable collection associated with the brief.

collections.versionsobject · required

Immutable brief version summaries, newest first.

collections.versions.itemsarray · required

Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.

Array item · object

collections.versions.items[].idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
collections.versions.items[].versionNuminteger · required: Monotonic brief contract version number assigned by Semel. The value must be an integer.
collections.versions.items[].contentHashstring · required: Hash of the immutable brief content snapshot.
collections.versions.items[].aiReviewerRolestring | 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[].sourceRunIdstring | 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[].isRevertboolean · required: Whether this immutable version was created by reverting to prior content.
collections.versions.items[].createdByIdstring · required: Semel user identifier recorded as the initiating creator.
collections.versions.items[].createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

collections.versions.nextCursorstring | 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.decisionHistoryobject · required

Durable question and decision history for the brief.

collections.decisionHistory.itemsarray · required

Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.

Array item · object

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[].sourceIdstring · required: Opaque source identifier returned by project_context_sources_list; pass it back unchanged.
collections.decisionHistory.items[].textstring · required: Human-authored or model-produced text for this typed record.
collections.decisionHistory.items[].answerstring | 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[].statusstring | 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[].reviewerRolestring | null · required: Reviewer role attributed to this question, finding, or version. A null value explicitly means no current value is available.
collections.decisionHistory.items[].sectionstring | 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[].iterationRoundany of · 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.
any of
Branch 1
Branch 2
collections.decisionHistory.items[].sessionIdstring | 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[].runIdstring | 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[].actorUserIdstring | null · required: Accountable Semel user identifier recorded on the event. A null value explicitly means no current value is available.
collections.decisionHistory.items[].createdAtstring | 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[].answeredAtstring | null · required: RFC 3339 timestamp when the active answer was recorded. A null value explicitly means no current value is available.

collections.decisionHistory.nextCursorstring | 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.findingsobject · required

Reviewer findings associated with the selected brief version.

collections.findings.itemsarray · required

Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.

Array item · object

collections.findings.items[].sectionstring · required

Canonical brief section key associated with the question, finding, proposal, or decision entry.

collections.findings.items[].notestring · 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[].citationsarray · 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.

Array item · any of

any of

Branch 1

collections.findings.items[].citations[].sourceType"brief-section" · required: Discriminator identifying the evidence source variant. This branch always uses "brief-section".
collections.findings.items[].citations[].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[].statementIdstring · optional: 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.
minimum length: 1 · maximum length: 200
collections.findings.items[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200
collections.findings.items[].citations[].briefIdstring · required: Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary.
collections.findings.items[].citations[].contractVersionIdstring · required: Immutable brief contract-version identifier resolved by Semel.
collections.findings.items[].citations[].versionNuminteger · 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[].reviewersarray · required: Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
minimum items: 1
Array item · "product" | "engineering" | "design" | "security" | "test"
collections.findings.items[].citations[].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".

Branch 2

collections.findings.items[].citations[].sourceType"artifact" · required: Discriminator identifying the evidence source variant. This branch always uses "artifact".
collections.findings.items[].citations[].artifactIdstring · required: Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
collections.findings.items[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200
collections.findings.items[].citations[].extractedTextHashstring · required: Hash of the normalized text extracted from the cited artifact, used to bind the citation to exact processed content.
collections.findings.items[].citations[].reviewersarray · required: Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
minimum items: 1
Array item · "product" | "engineering" | "design" | "security" | "test"
collections.findings.items[].citations[].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".

Branch 3

collections.findings.items[].citations[].sourceType"repository-code" · required: Discriminator identifying the evidence source variant. This branch always uses "repository-code".
collections.findings.items[].citations[].citationKeystring · required: Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
collections.findings.items[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200
collections.findings.items[].citations[].evidenceManifestIdstring · required: Immutable evidence-manifest identifier captured for the review run. Minimum accepted length or value is 1.
minimum length: 1
collections.findings.items[].citations[].evidenceManifestItemIdstring · required: Identifier of the exact item inside the immutable evidence manifest. Minimum accepted length or value is 1.
minimum length: 1
collections.findings.items[].citations[].workspaceRepositoryIdstring · required: Workspace-scoped connected repository identifier recorded in evidence provenance. Minimum accepted length or value is 1.
minimum length: 1
collections.findings.items[].citations[].revisionIdstring · required: Immutable indexed repository revision identifier. Minimum accepted length or value is 1.
minimum length: 1
collections.findings.items[].citations[].commitShastring · required: Git commit SHA pinned by the evidence manifest.
pattern: ^(?:[a-f0-9]{40}|[a-f0-9]{64})$
collections.findings.items[].citations[].blobShastring · required: Git blob SHA for the cited file contents.
pattern: ^(?:[a-f0-9]{40}|[a-f0-9]{64})$
collections.findings.items[].citations[].pathstring · required: Repository-relative source path; it never denotes an arbitrary local filesystem path. Minimum accepted length or value is 1.
minimum length: 1
collections.findings.items[].citations[].startLineinteger · 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[].endLineinteger · 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[].excerptSha256string · required: Lowercase hexadecimal SHA-256 digest of the exact cited excerpt.
pattern: ^[a-f0-9]{64}$
collections.findings.items[].citations[].route"exact" | "lexical" | "hybrid" · required: Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
collections.findings.items[].citations[].coverageobject · required: Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence.
Map values · any JSON value
collections.findings.items[].citations[].reviewersarray · required: Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
minimum items: 1
Array item · "product" | "engineering" | "design" | "security" | "test"
collections.findings.items[].citations[].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[].evidenceUnavailableboolean · 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.nextCursorstring | 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.proposalsobject · required

Reviewer proposals and their decision/commit state.

collections.proposals.itemsarray · required

Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.

Array item · object

collections.proposals.items[].idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
collections.proposals.items[].sessionIdstring · required: Review-session identifier associated with this historical record; null means legacy provenance is unavailable.
collections.proposals.items[].sectionstring · required: Canonical brief section key associated with the question, finding, proposal, or decision entry.
collections.proposals.items[].summarystring | null · required: Concise safe summary intended for users and logs. A null value explicitly means no current value is available.
collections.proposals.items[].statusstring · required: Current typed status; the schema enum or union branch lists every allowed value.
collections.proposals.items[].decidedByIdstring | 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[].decidedAtstring | 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[].decisionSourcestring | 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[].committedAtstring | 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[].sourceRoundany of · 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.
any of
Branch 1
Branch 2
collections.proposals.items[].createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

collections.proposals.nextCursorstring | 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.approvalsobject · required

Append-only human approval records for brief versions.

collections.approvals.itemsarray · required

Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.

Array item · object

collections.approvals.items[].idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
collections.approvals.items[].contractVersionIdstring · required: Immutable brief contract-version identifier resolved by Semel.
collections.approvals.items[].approverIdstring · required: Semel user identifier for the human who recorded this approval decision.
collections.approvals.items[].actionstring · required: Typed human approval action recorded in the append-only approval ledger.
collections.approvals.items[].isStaleboolean · required: Whether this historical approval no longer targets the current brief version.
collections.approvals.items[].reRequestReasonstring | 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[].createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

collections.approvals.nextCursorstring | 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.commentsobject · required

Human comments attached to brief sections or anchors.

collections.comments.itemsarray · required

Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.

Array item · object

collections.comments.items[].idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
collections.comments.items[].sectionKeystring · required: Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result.
collections.comments.items[].anchorstring | 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[].textstring · required: Human-authored or model-produced text for this typed record.
collections.comments.items[].authorIdstring · required: Semel user identifier for the comment or content author.
collections.comments.items[].resolvedAtstring | 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[].resolvedBystring | 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[].createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

collections.comments.nextCursorstring | 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.artifactsobject · required

Source artifacts attached to the brief.

collections.artifacts.itemsarray · required

Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.

Array item · object

collections.artifacts.items[].idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
collections.artifacts.items[].artifactTypestring · required: Semel artifact classification used to select ingestion and display behavior for this source material.
collections.artifacts.items[].labelstring | null · required: Human-readable label displayed for this record. A null value explicitly means no current value is available.
collections.artifacts.items[].sourceUrlstring | 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[].mimeTypestring | 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[].sizeBytesany of · required: Artifact size in bytes. A null value explicitly means no current value is available. The value must be an integer.
any of
Branch 1
Branch 2
collections.artifacts.items[].ingestionStatusstring · required: Current artifact ingestion lifecycle state; only ready artifacts may supply reviewed evidence.
collections.artifacts.items[].createdByIdstring | null · required: Semel user identifier recorded as the initiating creator. A null value explicitly means no current value is available.
collections.artifacts.items[].createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

collections.artifacts.nextCursorstring | 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.workOrdersobject · required

Materialized implementation work orders for the brief.

collections.workOrders.itemsarray · required

Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.

Array item · object

collections.workOrders.items[].idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
collections.workOrders.items[].titlestring · required: Human-readable title displayed in Semel.
collections.workOrders.items[].descriptionstring | 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[].positioninteger · required: Stable zero-based or configured ordering position returned by Semel. The value must be an integer.
collections.workOrders.items[].boundCriteriaarray · required: Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items.
Array item · string
collections.workOrders.items[].boundRequirementsarray · required: Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. An empty array explicitly means no matching items.
Array item · string
collections.workOrders.items[].externalTrackerstring | 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[].externalUrlstring | 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[].exportStatestring · required: Current external-tracker export lifecycle state for this generated work order.
collections.workOrders.items[].createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

collections.workOrders.nextCursorstring | 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.reviewSessionsobject · required

Review session summaries associated with the brief.

collections.reviewSessions.itemsarray · required

Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.

Array item · object

collections.reviewSessions.items[].idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
collections.reviewSessions.items[].runIdstring · required: Review-run identifier returned by a review start, status, or cascade handoff result.
collections.reviewSessions.items[].statusstring · required: Current typed status; the schema enum or union branch lists every allowed value.
collections.reviewSessions.items[].reviewerSetarray · required: Ordered reviewer roles configured for this cascade. An empty array explicitly means no matching items.
Array item · string
collections.reviewSessions.items[].reviewedContractVersionIdstring | 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[].createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

collections.reviewSessions.nextCursorstring | 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.sharesobject · required

Share-link records associated with the brief.

collections.shares.itemsarray · required

Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.

Array item · object

collections.shares.items[].idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
collections.shares.items[].accessLevelstring · required: Share-link access policy assigned by Semel; the enum identifies whether the recipient may only view or may also interact.
collections.shares.items[].sharedByIdstring · required: Semel user identifier for the person who created the share.
collections.shares.items[].isActiveboolean · required: Whether this share link remains active.
collections.shares.items[].expiresAtstring | null · required: RFC 3339 expiration timestamp. A null value explicitly means no current value is available.
collections.shares.items[].createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

collections.shares.nextCursorstring | 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.

gateNotificationStatusany of · required

Latest human gate notification status; null means no notification request exists. A null value explicitly means no current value is available.

any of

Branch 1

gateNotificationStatus.requestIdstring · required: Server request identifier used for support correlation; it is not an idempotency key.
gateNotificationStatus.assignmentIdstring | null · required: Human gate assignment identifier created by Semel. A null value explicitly means no current value is available.
gateNotificationStatus.contentHashstring | null · required: Hash of the immutable brief content snapshot. A null value explicitly means no current value is available.
gateNotificationStatus.notifiedAtstring | 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.createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

Branch 2

Example structured result · full-brief

{
  "brief": {
    "id": "brf_fixture_checkout",
    "projectId": "prj_fixture_checkout",
    "title": "Retry-safe checkout",
    "state": "drafting",
    "currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "content": {
      "goal": "Prevent duplicate charges when checkout retries.",
      "requirements": [
        "Reuse one payment intent for retried submissions."
      ],
      "acceptanceCriteria": [
        {
          "id": "AC-01",
          "text": "A retried request returns the original successful result."
        }
      ],
      "sourceArtifactLinks": [
        {
          "label": "Linear ENG-42",
          "kind": "linear"
        }
      ],
      "checklist": [
        {
          "text": "API contract reviewed",
          "checked": false
        }
      ]
    },
    "versionNum": 3
  },
  "collections": {
    "versions": {
      "items": [],
      "nextCursor": null
    },
    "decisionHistory": {
      "items": [],
      "nextCursor": null
    },
    "findings": {
      "items": [],
      "nextCursor": null
    },
    "proposals": {
      "items": [],
      "nextCursor": null
    },
    "approvals": {
      "items": [],
      "nextCursor": null
    },
    "comments": {
      "items": [],
      "nextCursor": null
    },
    "artifacts": {
      "items": [],
      "nextCursor": null
    },
    "workOrders": {
      "items": [],
      "nextCursor": null
    },
    "reviewSessions": {
      "items": [],
      "nextCursor": null
    },
    "shares": {
      "items": [],
      "nextCursor": null
    }
  },
  "gateNotificationStatus": null
}

MCP wire envelope

{
  "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\"}],\"checklist\":[{\"text\":\"API contract reviewed\",\"checked\":false}]},\"versionNum\":3},\"collections\":{\"versions\":{\"items\":[],\"nextCursor\":null},\"decisionHistory\":{\"items\":[],\"nextCursor\":null},\"findings\":{\"items\":[],\"nextCursor\":null},\"proposals\":{\"items\":[],\"nextCursor\":null},\"approvals\":{\"items\":[],\"nextCursor\":null},\"comments\":{\"items\":[],\"nextCursor\":null},\"artifacts\":{\"items\":[],\"nextCursor\":null},\"workOrders\":{\"items\":[],\"nextCursor\":null},\"reviewSessions\":{\"items\":[],\"nextCursor\":null},\"shares\":{\"items\":[],\"nextCursor\":null}},\"gateNotificationStatus\":null}"
    }
  ],
  "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"
          }
        ],
        "checklist": [
          {
            "text": "API contract reviewed",
            "checked": false
          }
        ]
      },
      "versionNum": 3
    },
    "collections": {
      "versions": {
        "items": [],
        "nextCursor": null
      },
      "decisionHistory": {
        "items": [],
        "nextCursor": null
      },
      "findings": {
        "items": [],
        "nextCursor": null
      },
      "proposals": {
        "items": [],
        "nextCursor": null
      },
      "approvals": {
        "items": [],
        "nextCursor": null
      },
      "comments": {
        "items": [],
        "nextCursor": null
      },
      "artifacts": {
        "items": [],
        "nextCursor": null
      },
      "workOrders": {
        "items": [],
        "nextCursor": null
      },
      "reviewSessions": {
        "items": [],
        "nextCursor": null
      },
      "shares": {
        "items": [],
        "nextCursor": null
      }
    },
    "gateNotificationStatus": null
  }
}

currentContent ← structuredContent.brief.content

Next permitted action: Apply the requested edit locally while preserving every untouched key.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: brief_list, brief_collection_list, brief_export_package

brief_list

read

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 · low risk
Scopes: brief:read
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel list my briefs”
“/semel what briefs are there in progress?”
Related: brief_get_full, brief_collection_list

Arguments

cursorstring · optional: Opaque keyset cursor returned as nextCursor by the preceding brief_list response. Omit to read the first page.
minimum length: 1
limitinteger · optional: Maximum briefs to return, as an integer from 1 through 200. Omit to use the server default.
minimum: 1 · maximum: 200

Runnable arguments · Locate and inspect a complete brief

{
  "limit": 50
}

Binding template

{
  "limit": 50
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

briefsarray · required

Brief summaries reachable by the authenticated principal. An empty array explicitly means no matching items.

Array item · object

briefs[].idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
briefs[].projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project.
briefs[].titlestring · required: Human-readable title displayed in Semel.
briefs[].statestring · required: Current typed lifecycle state; the schema enum or union branch defines allowed values.
briefs[].versionNuminteger · required: Monotonic brief contract version number assigned by Semel. The value must be an integer.
briefs[].updatedAtstring · required: RFC 3339 timestamp when this record was last updated.

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

Example structured result · brief-list

{
  "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
}

MCP wire envelope

{
  "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
  }
}

briefId ← structuredContent.briefs[0].id

Next permitted action: Select an exact brief or ask the human to disambiguate.

Complete raw result schema

Output

{
  "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
}

brief_update

write · idempotent (needs idempotencyKey)

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 · medium risk
Scopes: brief:read, brief:write
Confirmation: explicit
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/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: brief_create, brief_get_full, brief_checklist_update

Arguments

contentobject · 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.goalstring · optional

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.

maximum length: 4000

content.userPersonaContextstring · optional

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.

maximum length: 4000

content.scopestring · optional

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.

maximum length: 4000

content.outOfScopestring · optional

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.

maximum length: 4000

content.requirementsarray · optional

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.edgeCasesarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.acceptanceCriteriaarray · optional

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.

maximum items: 50

Array item · object

content.acceptanceCriteria[].idstring · required

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.

minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

content.acceptanceCriteria[].textstring · required

Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.

minimum length: 1 · maximum length: 1000

content.acceptanceCriteria[].implementationboolean · 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[].manualEvidenceobject · 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.rationalestring · required: Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
content.acceptanceCriteria[].manualEvidence.evidencePathstring · required: Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000

content.rolesPermissionsarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.statesarray · optional

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.productSolutionstring · optional

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.

maximum length: 4000

content.technicalSolutionstring · optional

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.

maximum length: 4000

content.dataModelImplicationsstring · optional

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.

maximum length: 4000

content.architectureAssumptionsstring · optional

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.

maximum length: 4000

content.designstring · optional

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.

maximum length: 4000

content.testingQaChecklistarray · optional

maximum items: 50

Array item · object

content.testingQaChecklist[].textstring · required: Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
content.testingQaChecklist[].checkedboolean · required: Whether this QA checklist item is currently complete.
content.testingQaChecklist[].addedBystring · optional: 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.
maximum length: 200
content.testingQaChecklist[].checkedBystring · optional: 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.
maximum length: 200
content.testingQaChecklist[].checkedAtstring · optional: 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.
format: date-time

content.testPlanUnitarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.testPlanIntegrationarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.testPlanUiUxarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.openQuestionsarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

content.generatedTicketsarray · optional

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.

maximum items: 50

Array item · object

content.generatedTickets[].idstring · required: 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.
minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
content.generatedTickets[].titlestring · required: Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
minimum length: 1 · maximum length: 500
content.generatedTickets[].descriptionany of · 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.
any of
Branch 1
maximum length: 10000
Branch 2
content.generatedTickets[].boundCriteriaarray · required: Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items.
maximum items: 50
Array item · string
minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
content.generatedTickets[].boundRequirementsarray · optional: 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.
maximum items: 50
Array item · string
minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

content.requiredEvidencearray · optional

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.

maximum items: 50

Array item · object

content.requiredEvidence[].idstring · required

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.

minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

content.requiredEvidence[].textstring · required

Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.

minimum length: 1 · maximum length: 1000

content.requiredEvidence[].implementationboolean · 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[].manualEvidenceobject · 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.rationalestring · required: Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
content.requiredEvidence[].manualEvidence.evidencePathstring · required: Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000

content.decisionsarray · optional

maximum items: 50

Array item · object

content.decisions[].textstring · required: Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
content.decisions[].sourcestring · optional: 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.
maximum length: 1000
content.decisions[].statedboolean · 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.sourceArtifactLinksarray · optional

maximum items: 50

Array item · object

content.sourceArtifactLinks[].labelstring · required: Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
content.sourceArtifactLinks[].kindstring · optional: 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.
maximum length: 200
content.sourceArtifactLinks[].readboolean · 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.

titlestring · optional

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.

minimum length: 1 · maximum length: 500

ifVersionNuminteger · 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.

clearDraftboolean · 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.

briefIdstring · required

Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.

minimum length: 1

idempotencyKeystring · required

Caller-unique key making this mutation exactly-once (see the receipt contract).

minimum length: 1

Runnable arguments · Safely update a versioned brief

{
  "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

{
  "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}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

briefobject · required

Current brief record returned by the operation.

brief.idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
brief.projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project.
brief.titlestring · 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.currentVersionHashstring | 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.contentobject · required: Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
Map values · any JSON value
brief.versionNuminteger · required: Monotonic brief contract version number assigned by Semel. The value must be an integer.
brief.createdNewVersionboolean · required: Whether the write changed canonical content and minted a new immutable brief version.
brief.staledApprovalsinteger · required: Number of prior approval rows made stale by this content change. The value must be an integer.

Example structured result · brief-updated

{
  "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
  }
}

MCP wire envelope

{
  "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
    }
  }
}

versionNum ← structuredContent.brief.versionNum

Next permitted action: Inspect createdNewVersion and the returned current version.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIED, BRIEF_VERSION_CONFLICTRelated: brief_create, brief_get_full, brief_checklist_update

project_codebase_link

write · idempotent (needs idempotencyKey)

Turn on one already-connected codebase for a project after the agent inventories plausible repositories and the user confirms the proposed scope.

Mode: write · medium risk
Scopes: brief:read, brief:write
Confirmation: explicit
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel add the throughlineos codebase to this project”
“/semel use this connected repository as project evidence”
Errors: PROJECT_ACCESS_DENIED
Related: project_codebases_list, project_context_sources_list, brief_create

Arguments

projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
minimum length: 1
repositoryIdstring · required: Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
minimum length: 1
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Resolve, create, inspect, and rename a project

{
  "projectId": "prj_fixture_checkout",
  "repositoryId": "repo_fixture_throughline",
  "idempotencyKey": "recipe-project-codebase-link-v1"
}

Binding template

{
  "projectId": "{{projectId}}",
  "repositoryId": "{{repositoryId}}",
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

projectCodebaseobject · required

Project-to-repository link returned by the operation.

projectCodebase.projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
minimum length: 1
projectCodebase.repositoryIdstring · required: Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
minimum length: 1
projectCodebase.linkedtrue · required: Whether the repository is currently linked to the project. This branch always uses true.
projectCodebase.newlyLinkedboolean · required: Whether this call created the project-to-repository link instead of replaying an existing link.

Example structured result · codebase-linked

{
  "projectCodebase": {
    "projectId": "prj_fixture_checkout",
    "repositoryId": "repo_fixture_throughline",
    "linked": true,
    "newlyLinked": true
  }
}

MCP wire envelope

{
  "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
    }
  }
}

linked ← structuredContent.projectCodebase.linked

Next permitted action: Proceed with the confirmed repository in project scope.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: project_codebases_list, project_context_sources_list, brief_create

project_codebases_list

read

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 · low risk
Scopes: brief:read
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/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: project_get, project_codebase_link, brief_create

Arguments

projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
minimum length: 1
cursorstring · optional: 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.
minimum length: 1
limitinteger · optional: 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.
minimum: 1 · maximum: 200

Runnable arguments · Resolve, create, inspect, and rename a project

{
  "projectId": "prj_fixture_checkout",
  "limit": 50
}

Binding template

{
  "projectId": "{{projectId}}",
  "limit": 50
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

projectIdstring · required

Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.

minimum length: 1

codebasesarray · required

Connected repository options visible to this project actor. An empty array explicitly means no matching items.

Array item · object

codebases[].repositoryIdstring · required: Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
minimum length: 1
codebases[].ownerstring · required: Repository owner or organization slug returned by the connected source provider; pair it with repository name. Minimum accepted length or value is 1.
minimum length: 1
codebases[].namestring · required: Human-readable name displayed in Semel. Minimum accepted length or value is 1.
minimum length: 1
codebases[].trackingBranchstring · required: Repository branch configured for indexing and review evidence. Minimum accepted length or value is 1.
minimum length: 1
codebases[].selectedboolean · 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".

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

Example structured result · codebase-inventory

{
  "projectId": "prj_fixture_checkout",
  "codebases": [
    {
      "repositoryId": "repo_fixture_throughline",
      "owner": "throughline",
      "name": "throughlineos",
      "trackingBranch": "main",
      "selected": false,
      "selectionStatus": "available"
    }
  ],
  "nextCursor": null
}

MCP wire envelope

{
  "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
  }
}

codebases ← structuredContent.codebases

Next permitted action: Follow nextCursor until null before proposing repository scope.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: project_get, project_codebase_link, brief_create

project_context_evidence_get

read

Fetch the bounded excerpt or statement a search result cited, preserving its source/version/provenance.

Mode: read · low risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “show me the code that matched that last search result”
Errors: AUTHORIZATION_SCOPE_MISSING PROJECT_ACCESS_DENIED
Related: project_context_search

Arguments

projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
minimum length: 1
citationHandlestring · required: Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.
minimum length: 1

Runnable arguments · Retrieve bounded project evidence

{
  "projectId": "prj_fixture_checkout",
  "citationHandle": "ctx1.repository.fixture"
}

Binding template

{
  "projectId": "{{projectId}}",
  "citationHandle": "{{citationHandle}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

citationany of · required

Durable citation metadata for the returned evidence excerpt.

any of

Branch 1

citation.citationHandlestring · required

Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.

minimum length: 1

citation.sourceIdstring · required

Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.

minimum length: 1

citation.provenance"semel_indexed" | "local_harness" · required

Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".

citation.route"exact" | "lexical" | "hybrid" · required

Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".

citation.scorenumber · required

Retrieval relevance score used to order evidence results.

citation.kind"repository" · required

Discriminator identifying the typed variant represented by this object. This branch always uses "repository".

citation.repositoryobject · required

Connected repository identity and provider metadata.

citation.repository.ownerstring · required: Repository owner or organization slug returned by the connected source provider; pair it with repository name.
citation.repository.namestring · required: Human-readable name displayed in Semel.

citation.revisionobject · required

Indexed repository revision used for this evidence result.

citation.revision.commitShastring · required: Git commit SHA pinned by the evidence manifest.
citation.revision.revisionIdstring · required: Immutable indexed repository revision identifier.

citation.pathstring · required

Repository-relative source path; it never denotes an arbitrary local filesystem path.

citation.startLineinteger · 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.endLineinteger · required

One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.

Branch 2

citation.citationHandlestring · required

Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.

minimum length: 1

citation.sourceIdstring · required

Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.

minimum length: 1

citation.provenance"semel_indexed" | "local_harness" · required

Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".

citation.route"exact" | "lexical" | "hybrid" · required

Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".

citation.scorenumber · required

Retrieval relevance score used to order evidence results.

citation.kind"knowledge_collection" · required

Discriminator identifying the typed variant represented by this object. This branch always uses "knowledge_collection".

citation.collectionobject · required

Named durable brief collection to page; use one of the documented enum values.

citation.collection.scopeKind"workspace" | "project" | "repository" · required: Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: "workspace", "project", "repository".
citation.collection.scopeIdstring · required: Stable identifier of the repository scope that produced this evidence.
citation.collection.snapshotIdstring · required: Immutable export snapshot identifier used to reproduce the exported brief state.
citation.collection.versioninteger · required: 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.
minimum: 0

citation.sectionKeystring · required

Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result.

citation.statementIndexinteger · required

Zero-based statement position within the cited brief section. Minimum accepted length or value is 0. The value must be an integer.

minimum: 0

excerptstring · required

Bounded source excerpt authorized for this result; an empty string means no excerpt text was returned.

truncatedboolean · required

Whether the returned excerpt was shortened to the response limit.

Example structured result · bounded-evidence

{
  "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
}

MCP wire envelope

{
  "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
  }
}

excerpt ← structuredContent.excerpt

Next permitted action: Cite the returned provenance/revision/path and disclose truncated when true.

Complete raw result schema

Output

{
  "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
}

Recovery: AUTHORIZATION_SCOPE_MISSING, PROJECT_ACCESS_DENIEDRelated: project_context_search

project_context_search

read

Search one or more already-listed context sources for evidence relevant to the active reviewer skill’s question.

Mode: read · low risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “search the indexed repository for the retry handler”
“have we recorded any prior decisions about pricing?”
Errors: AUTHORIZATION_SCOPE_MISSING PROJECT_ACCESS_DENIED
Related: project_context_sources_list, project_context_evidence_get

Arguments

projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
minimum length: 1
sourceIdsarray · required: Source identifiers returned by project_context_sources_list that bound this search. An empty array explicitly means no matching items.
minimum items: 1 · maximum items: 5
Array item · string
minimum length: 1
querystring · required: Natural-language or code search query evaluated only against the selected project context sources. Accepted length or value is 1 through 500, inclusive.
minimum length: 1 · maximum length: 500
limitinteger · optional: 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.
minimum: 1 · maximum: 200

Runnable arguments · Retrieve bounded project evidence

{
  "projectId": "prj_fixture_checkout",
  "sourceIds": [
    "src_fixture_repository"
  ],
  "query": "payment retry idempotency",
  "limit": 20
}

Binding template

{
  "projectId": "{{projectId}}",
  "sourceIds": [
    "{{sourceId}}"
  ],
  "query": "payment retry idempotency",
  "limit": 20
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

resultsarray · required

Ranked evidence matches for the requested sources and query. An empty array explicitly means no matching items.

Array item · object

results[].citationany of · required

Durable citation metadata for the returned evidence excerpt.

any of

Branch 1

results[].citation.citationHandlestring · required

Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.

minimum length: 1

results[].citation.sourceIdstring · required

Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.

minimum length: 1

results[].citation.provenance"semel_indexed" | "local_harness" · required

Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".

results[].citation.route"exact" | "lexical" | "hybrid" · required

Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".

results[].citation.scorenumber · required

Retrieval relevance score used to order evidence results.

results[].citation.kind"repository" · required

Discriminator identifying the typed variant represented by this object. This branch always uses "repository".

results[].citation.repositoryobject · required

Connected repository identity and provider metadata.

results[].citation.repository.ownerstring · required: Repository owner or organization slug returned by the connected source provider; pair it with repository name.
results[].citation.repository.namestring · required: Human-readable name displayed in Semel.

results[].citation.revisionobject · required

Indexed repository revision used for this evidence result.

results[].citation.revision.commitShastring · required: Git commit SHA pinned by the evidence manifest.
results[].citation.revision.revisionIdstring · required: Immutable indexed repository revision identifier.

results[].citation.pathstring · required

Repository-relative source path; it never denotes an arbitrary local filesystem path.

results[].citation.startLineinteger · 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.endLineinteger · required

One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.

Branch 2

results[].citation.citationHandlestring · required

Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.

minimum length: 1

results[].citation.sourceIdstring · required

Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.

minimum length: 1

results[].citation.provenance"semel_indexed" | "local_harness" · required

Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".

results[].citation.route"exact" | "lexical" | "hybrid" · required

Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".

results[].citation.scorenumber · required

Retrieval relevance score used to order evidence results.

results[].citation.kind"knowledge_collection" · required

Discriminator identifying the typed variant represented by this object. This branch always uses "knowledge_collection".

results[].citation.collectionobject · required

Named durable brief collection to page; use one of the documented enum values.

results[].citation.collection.scopeKind"workspace" | "project" | "repository" · required: Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: "workspace", "project", "repository".
results[].citation.collection.scopeIdstring · required: Stable identifier of the repository scope that produced this evidence.
results[].citation.collection.snapshotIdstring · required: Immutable export snapshot identifier used to reproduce the exported brief state.
results[].citation.collection.versioninteger · required: 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.
minimum: 0

results[].citation.sectionKeystring · required

Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result.

results[].citation.statementIndexinteger · required

Zero-based statement position within the cited brief section. Minimum accepted length or value is 0. The value must be an integer.

minimum: 0

searchedSourcesarray · required

Source identifiers actually searched after authorization and availability checks. An empty array explicitly means no matching items.

Array item · object

searchedSources[].sourceIdstring · required: Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
minimum length: 1
searchedSources[].route"exact" | "lexical" | "hybrid" · required: Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
searchedSources[].resultCountinteger · required: Number of evidence matches returned in this response. Minimum accepted length or value is 0. The value must be an integer.
minimum: 0
searchedSources[].abstainedboolean · required: Whether search deliberately returned no evidence because trust or relevance requirements were unmet.
searchedSources[].abstentionReasonstring · 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.

Example structured result · search-results

{
  "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
    }
  ]
}

MCP wire envelope

{
  "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
      }
    ]
  }
}

citationHandle ← structuredContent.results[0].citation.citationHandle

Next permitted action: Preserve the returned citationHandle exactly; inspect abstention metadata when no result exists.

Complete raw result schema

Output

{
  "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
}

Recovery: AUTHORIZATION_SCOPE_MISSING, PROJECT_ACCESS_DENIEDRelated: project_context_sources_list, project_context_evidence_get

project_context_sources_list

read

Discover which repositories and knowledge collections this project can search before claiming absence.

Mode: read · low risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “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: project_context_search, project_context_evidence_get

Arguments

projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
minimum length: 1
cursorstring · optional: 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.
minimum length: 1
limitinteger · optional: 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.
minimum: 1 · maximum: 200

Runnable arguments · Retrieve bounded project evidence

{
  "projectId": "prj_fixture_checkout",
  "limit": 50
}

Binding template

{
  "projectId": "{{projectId}}",
  "limit": 50
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

sourcesarray · required

Connected repository sources currently authorized for this project. An empty array explicitly means no matching items.

Array item · object

sources[].sourceIdstring · required

Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.

minimum length: 1

sources[].kind"repository" | "knowledge_collection" · required

Discriminator identifying the typed variant represented by this object. Allowed values: "repository", "knowledge_collection".

sources[].labelstring · required

Human-readable label displayed for this record.

sources[].scopeobject · 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.idstring | 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[].repositoryobject · optional

Connected repository identity and provider metadata. Omit the field when it does not apply; omission is distinct from an empty value.

sources[].repository.ownerstring · required: Repository owner or organization slug returned by the connected source provider; pair it with repository name.
sources[].repository.namestring · required: Human-readable name displayed in Semel.
sources[].repository.defaultBranchstring · required: Repository default branch reported by the connected provider.
sources[].repository.trackingBranchstring · required: Repository branch configured for indexing and review evidence.
sources[].repository.commitShastring | null · required: Git commit SHA pinned by the evidence manifest. A null value explicitly means no current value is available.
sources[].repository.revisionIdstring | null · required: Immutable indexed repository revision identifier. A null value explicitly means no current value is available.

sources[].collectionobject · 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.versioninteger · required: 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.
minimum: 0
sources[].collection.snapshotIdstring · 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[].freshnessobject · required

Repository indexing freshness and configured tracking branch.

sources[].freshness.asOfstring | 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".

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

Example structured result · source-list

{
  "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
}

MCP wire envelope

{
  "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
  }
}

sourceId ← structuredContent.sources[0].sourceId

Next permitted action: Follow nextCursor to completion and distinguish ready, stale, degraded, and unavailable sources.

Complete raw result schema

Output

{
  "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
}

Recovery: AUTHORIZATION_SCOPE_MISSING, PROJECT_ACCESS_DENIEDRelated: project_context_search, project_context_evidence_get

project_create

write · idempotent (needs idempotencyKey)

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 · medium risk
Scopes: brief:read, brief:write
Confirmation: explicit
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel create a project for the new onboarding flow”
“/semel start a new project called Checkout v2”
Errors: PROJECT_ACCESS_DENIED
Related: project_list, project_get, brief_create

Arguments

namestring · required: Human-readable name displayed in Semel. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
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".
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Resolve, create, inspect, and rename a project

{
  "name": "Checkout reliability",
  "reviewMode": "direct",
  "idempotencyKey": "recipe-project-create-v1"
}

Binding template

{
  "name": "{{projectName}}",
  "reviewMode": "direct",
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

projectobject · required

Project record returned by the operation.

project.idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
project.workspaceIdstring · required: Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
project.namestring · required: Human-readable name displayed in Semel.
project.reviewMode"direct" | "propose" · required: Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
project.ownerIdstring · 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.createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

Example structured result · project-created

{
  "project": {
    "id": "prj_fixture_checkout",
    "workspaceId": "ws_fixture_primary",
    "name": "Checkout reliability",
    "reviewMode": "direct",
    "createdAt": "2026-09-07T16:00:00.000Z"
  }
}

MCP wire envelope

{
  "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"
    }
  }
}

projectId ← structuredContent.project.id

Next permitted action: Carry project.id into every project-scoped call.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: project_list, project_get, brief_create

project_get

read

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 · low risk
Scopes: brief:read
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel show me the details of this project”
“/semel what is the review mode for the checkout project?”
Errors: PROJECT_ACCESS_DENIED
Related: project_list, project_rename

Arguments

projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project. Supply a non-empty identifier.
minimum length: 1

Runnable arguments · Resolve, create, inspect, and rename a project

{
  "projectId": "prj_fixture_checkout"
}

Binding template

{
  "projectId": "{{projectId}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

projectobject · required

Canonical project record returned after authorization and, for project_rename, after the durable name update succeeds.

project.idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
project.workspaceIdstring · required: Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
project.namestring · required: Human-readable name displayed in Semel.
project.reviewMode"direct" | "propose" · required: Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
project.ownerIdstring · 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.createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

Example structured result · project

{
  "project": {
    "id": "prj_fixture_checkout",
    "workspaceId": "ws_fixture_primary",
    "name": "Checkout reliability",
    "reviewMode": "direct",
    "createdAt": "2026-09-07T16:00:00.000Z"
  }
}

MCP wire envelope

{
  "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"
    }
  }
}

project ← structuredContent.project

Next permitted action: Confirm the resolved project details before mutation.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: project_list, project_rename

project_list

read

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 · low risk
Scopes: brief:read
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel list my projects”
“/semel what projects do I have?”
Related: project_get, project_create

Arguments

Runnable arguments · Configure a least-privilege unattended agent

{}

Binding template

{}

Complete raw parameter schema

Output

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Structured result

projectsarray · required

Projects reachable by the authenticated principal, filtered by its project allowlist and ordered newest first. An empty array means none are reachable.

Array item · object

projects[].idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
projects[].workspaceIdstring · required: Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
projects[].namestring · required: Human-readable name displayed in Semel.
projects[].reviewMode"direct" | "propose" · required: Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
projects[].ownerIdstring · 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[].createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

Example structured result · project-list

{
  "projects": []
}

MCP wire envelope

{
  "content": [
    {
      "type": "text",
      "text": "{\"projects\":[]}"
    }
  ],
  "structuredContent": {
    "projects": []
  }
}

projects ← structuredContent.projects

Next permitted action: Confirm only expected projects are visible and retain human gates for mutations.

Complete raw result schema

Output

{
  "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
}

Related: project_get, project_create

project_rename

write · idempotent (needs idempotencyKey)

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 · medium risk
Scopes: brief:read, brief:write
Confirmation: explicit
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel rename this project to Checkout v2”
“/semel change the billing project name to Payments”
Errors: PROJECT_ACCESS_DENIED
Related: project_get, project_list

Arguments

projectIdstring · required: Project identifier returned by project_create or project_list; the accountable human must be the project creator or workspace owner.
minimum length: 1
namestring · required: Replacement project display name after trimming, from 1 through 200 characters. A successful call durably renames the project.
minimum length: 1 · maximum length: 200
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Resolve, create, inspect, and rename a project

{
  "projectId": "prj_fixture_checkout",
  "name": "Payments reliability",
  "idempotencyKey": "recipe-project-rename-v1"
}

Binding template

{
  "projectId": "{{projectId}}",
  "name": "Payments reliability",
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

projectobject · required

Canonical project record returned after authorization and, for project_rename, after the durable name update succeeds.

project.idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
project.workspaceIdstring · required: Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
project.namestring · required: Human-readable name displayed in Semel.
project.reviewMode"direct" | "propose" · required: Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
project.ownerIdstring · 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.createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.

Example structured result · project-renamed

{
  "project": {
    "id": "prj_fixture_checkout",
    "workspaceId": "ws_fixture_primary",
    "name": "Payments reliability",
    "reviewMode": "direct",
    "createdAt": "2026-09-07T16:00:00.000Z"
  }
}

MCP wire envelope

{
  "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"
    }
  }
}

renamedProject ← structuredContent.project

Next permitted action: Keep the same project id after the rename.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: project_get, project_list

review_cancel

write · idempotent (needs idempotencyKey)

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 · medium risk
Scopes: brief:read, review:run
Confirmation: explicit
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel cancel that review — I did not mean to start it”
Errors: RUN_ALREADY_TERMINAL PROJECT_ACCESS_DENIED AUTHORIZATION_SCOPE_MISSING
Related: review_start, review_status, review_execution_release

Arguments

runIdstring · required: Review-run identifier returned by a review start, status, or cascade handoff result. Minimum accepted length or value is 1.
minimum length: 1
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Originate and observe a review

{
  "runId": "run_fixture_followup",
  "idempotencyKey": "recipe-review-cancel-v1"
}

Binding template

{
  "runId": "{{newRunId}}",
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

runIdstring · 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".
claimedboolean · 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.
finalizedboolean · 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.

Example structured result · cancel-requested

{
  "runId": "run_fixture_followup",
  "outcome": "cancel_requested",
  "status": "queued"
}

MCP wire envelope

{
  "content": [
    {
      "type": "text",
      "text": "{\"runId\":\"run_fixture_followup\",\"outcome\":\"cancel_requested\",\"status\":\"queued\"}"
    }
  ],
  "structuredContent": {
    "runId": "run_fixture_followup",
    "outcome": "cancel_requested",
    "status": "queued"
  }
}

cancelOutcome ← structuredContent.outcome

Next permitted action: Stop local work and follow the authoritative returned status.

Complete raw result schema

Output

{
  "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
}

Recovery: RUN_ALREADY_TERMINAL, PROJECT_ACCESS_DENIED, AUTHORIZATION_SCOPE_MISSINGRelated: review_start, review_status, review_execution_release

review_execution_checkpoint_append

write · idempotent (needs idempotencyKey)

Append one bounded semantic checkpoint milestone to the current fenced epoch.

Mode: write · low risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “report skill_start progress for the active reviewer skill”
Errors: STALE_FENCE SEQUENCE_GAP CONFLICTING_IDEMPOTENCY_REPLAY PAYLOAD_REJECTED VALIDATION_FAILED
Related: review_execution_sync, review_execution_status

Arguments

executionIdstring · required: External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
minimum length: 1
fenceGenerationinteger · 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.
seqinteger · required: Positive checkpoint event sequence within the current fence generation. Minimum accepted length or value is 0. The value must be an integer.
activeSkillIdstring · optional: 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.
minimum length: 1 · maximum length: 200
milestoneNamestring · required: Short caller-chosen name for the completed execution milestone represented by this checkpoint. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
safeSummarystring · optional: 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.
maximum length: 8192
receiptobject · 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.
Map values · any JSON value
clientObservedAtstring · optional: 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.
format: date-time
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Open and resolve durable review questions

{
  "executionId": "xex_fixture_engineering",
  "fenceGeneration": 1,
  "seq": 7,
  "activeSkillId": "engineering",
  "milestoneName": "question_wait_exit",
  "safeSummary": "The owner answer was accepted and dependent work may resume.",
  "receipt": {
    "questionId": "q_fixture_database",
    "answerAccepted": true
  },
  "clientObservedAt": "2026-09-07T16:00:00.000Z",
  "idempotencyKey": "recipe-question-checkpoint-wait-exit-v1"
}

Binding template

{
  "executionId": "{{executionId}}",
  "fenceGeneration": 1,
  "seq": 7,
  "activeSkillId": "engineering",
  "milestoneName": "question_wait_exit",
  "safeSummary": "The owner answer was accepted and dependent work may resume.",
  "receipt": {
    "questionId": "{{questionId}}",
    "answerAccepted": true
  },
  "clientObservedAt": "2026-09-07T16:00:00.000Z",
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

acceptedtrue · required

Confirms that the checkpoint or answer was durably accepted. This branch always uses true.

seqinteger · required

Positive checkpoint event sequence within the current fence generation. The value must be an integer.

highWaterMarkinteger · required

Highest checkpoint sequence durably accepted after this append. The value must be an integer.

suggestedNextPollAtstring · required

RFC 3339 timestamp for the next recommended sync or status poll.

coalesceboolean · required

Whether Semel recommends coalescing further nonterminal updates for the same stage.

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · checkpoint-accepted

{
  "accepted": true,
  "seq": 7,
  "highWaterMark": 7,
  "suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
  "coalesce": false,
  "controlBlock": {
    "state": {
      "sessionState": "running",
      "protocolVersion": "1.1"
    },
    "allowedNextOperations": [
      {
        "operation": "review_execution_skill_get",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_checkpoint_append",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_heartbeat",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_question_open",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_submit",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_release",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_sync",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_status",
        "preconditions": [
          "Always callable as the documented fail-safe."
        ]
      }
    ],
    "completion": {
      "complete": false,
      "unmetRequirements": [],
      "certificateState": "not_applicable"
    },
    "progress": {
      "checkpointHighWaterMark": 7,
      "openQuestionCount": 0,
      "leaseExpiresAt": "2026-09-07T16:15:00.000Z",
      "suggestedPollAt": "2026-09-07T16:05:00.000Z"
    },
    "operatorAction": {
      "required": false
    }
  }
}

MCP wire envelope

{
  "content": [
    {
      "type": "text",
      "text": "{\"accepted\":true,\"seq\":7,\"highWaterMark\":7,\"suggestedNextPollAt\":\"2026-09-07T16:05:00.000Z\",\"coalesce\":false,\"controlBlock\":{\"state\":{\"sessionState\":\"running\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_skill_get\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_checkpoint_append\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_heartbeat\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_question_open\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_submit\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_release\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_sync\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":7,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}}}"
    }
  ],
  "structuredContent": {
    "accepted": true,
    "seq": 7,
    "highWaterMark": 7,
    "suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
    "coalesce": false,
    "controlBlock": {
      "state": {
        "sessionState": "running",
        "protocolVersion": "1.1"
      },
      "allowedNextOperations": [
        {
          "operation": "review_execution_skill_get",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_checkpoint_append",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_heartbeat",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_question_open",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_submit",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_release",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_sync",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_status",
          "preconditions": [
            "Always callable as the documented fail-safe."
          ]
        }
      ],
      "completion": {
        "complete": false,
        "unmetRequirements": [],
        "certificateState": "not_applicable"
      },
      "progress": {
        "checkpointHighWaterMark": 7,
        "openQuestionCount": 0,
        "leaseExpiresAt": "2026-09-07T16:15:00.000Z",
        "suggestedPollAt": "2026-09-07T16:05:00.000Z"
      },
      "operatorAction": {
        "required": false
      }
    }
  }
}

checkpoint7HighWaterMark ← structuredContent.highWaterMark

Next permitted action: Resume work from the accepted answer or follow an operator correction.

Complete raw result schema

Output

{
  "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
}

Recovery: STALE_FENCE, SEQUENCE_GAP, CONFLICTING_IDEMPOTENCY_REPLAY, PAYLOAD_REJECTED, VALIDATION_FAILEDRelated: review_execution_sync, review_execution_status

review_execution_claim

write · idempotent (needs idempotencyKey)

Claim a review session for external execution, pinning the frozen canonical bundle.

Mode: write · medium risk
Scopes: brief:read, review:execute
Confirmation: implicit
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel continue the session I paused”
Errors: GRANT_EXPIRED PROTOCOL_VERSION_UNSUPPORTED STALE_FENCE PROJECT_ACCESS_DENIED
Related: review_execution_grant_request, review_execution_status

Arguments

grantIdstring · required

Execution-grant identifier returned when the human approval boundary is satisfied. Minimum accepted length or value is 1.

minimum length: 1

reviewSessionIdstring · required

Review-session identifier returned by review_start, review_new_pass, or execution status. Minimum accepted length or value is 1.

minimum length: 1

supportedProtocolVersionsarray · required

Protocol versions the harness can execute, ordered by its preference. An empty array explicitly means no matching items.

minimum items: 1

Array item · string

minimum length: 1

harnessDescriptorobject · required

Self-declared harness, agent, model, and supported-protocol metadata recorded on the execution claim for compatibility and audit.

harnessDescriptor.harnessstring · required: Harness product name declared by the caller; Semel does not independently verify it. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
harnessDescriptor.harnessVersionstring · optional: 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.
minimum length: 1 · maximum length: 100
harnessDescriptor.agentstring · optional: 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.
minimum length: 1 · maximum length: 200
harnessDescriptor.agentVersionstring · optional: 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.
minimum length: 1 · maximum length: 100
harnessDescriptor.modelstring · optional: 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.
minimum length: 1 · maximum length: 200
harnessDescriptor.modelProviderstring · optional: 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.
minimum length: 1 · maximum length: 100

idempotencyKeystring · required

Caller-unique key making this mutation exactly-once (see the receipt contract).

minimum length: 1

Runnable arguments · Claim and execute a local review session

{
  "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

{
  "grantId": "{{grantId}}",
  "reviewSessionId": "{{reviewSessionId}}",
  "supportedProtocolVersions": [
    "{{protocolVersion}}"
  ],
  "harnessDescriptor": {
    "harness": "codex",
    "harnessVersion": "1",
    "agent": "codex",
    "model": "gpt-5"
  },
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

bundleobject · required

Frozen canonical execution bundle returned at claim time.

bundle.protocolVersionstring · required

Semel external-execution protocol version used for this bundle or state.

bundle.instructionsstring · required

Pinned executable runbook instructions for this external execution.

bundle.schemaHashesobject · required

Map from frozen schema name to its SHA-256 identity.

Map values · string

bundle.sessionobject · required

Frozen review-session and run identity plus reviewer position for the claimed external execution.

bundle.session.reviewSessionIdstring · required: Review-session identifier returned by review_start, review_new_pass, or execution status.
bundle.session.runIdstring · required: Review-run identifier returned by a review start, status, or cascade handoff result.
bundle.session.projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project.
bundle.session.briefIdstring · required: Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary.
bundle.session.reviewModestring · required: Project review interaction mode configured in Semel.
bundle.session.reviewerSetarray · required: Ordered reviewer roles configured for this cascade. An empty array explicitly means no matching items.
Array item · string
bundle.session.cascadeStepIdstring | null · required: Identifier of the configured reviewer-cascade step associated with this run. A null value explicitly means no current value is available.

bundle.briefBaseobject · required

Frozen brief identity, version, and content snapshot against which this external execution must produce its result.

bundle.briefBase.versionIdstring · required: Immutable brief version identifier returned by the brief or claim contract.
bundle.briefBase.versionNuminteger · required: Monotonic brief contract version number assigned by Semel. The value must be an integer.
bundle.briefBase.sha256string · required: Lowercase hexadecimal SHA-256 digest used to verify exact bytes.

bundle.skillsarray · 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.

Array item · object

bundle.skills[].rolestring · required: Pinned reviewer or artifact role used by the execution bundle. Minimum accepted length or value is 1.
minimum length: 1
bundle.skills[].versionstring · required: Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 1.
minimum length: 1
bundle.skills[].sha256string · required: Lowercase hexadecimal SHA-256 digest used to verify exact bytes. Minimum accepted length or value is 1.
minimum length: 1
bundle.skills[].framingHashstring · 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.evidencePolicyobject · required

Frozen evidence policy map for this execution bundle; keys are versioned by the bundle contract.

Map values · any JSON value

bundle.requiredCheckpointsarray · required

Milestone names that must be checkpointed before final submission. An empty array explicitly means no matching items.

Array item · string

bundle.limitsobject · required

Server-issued byte, count, timeout, and polling limits that the external harness must obey for this execution.

bundle.limits.checkpointMaxBytesinteger · required: Maximum serialized checkpoint receipt size in bytes. The value must be an integer.
bundle.limits.summaryMaxBytesinteger · required: Maximum safe progress-summary size in UTF-8 bytes. The value must be an integer.
bundle.limits.sessionEventBudgetBytesinteger · required: Maximum total persisted external-event payload for one session, in bytes. The value must be an integer.

canonicalBundleSha256string · required

Lowercase hexadecimal SHA-256 digest of the frozen canonical execution bundle.

envelopeobject · required

Per-claim execution identity, fence, lease, and harness-attestation fields excluded from the bundle hash.

envelope.executionIdstring · required

External-execution identifier returned by a successful execution claim or status lookup.

envelope.fenceGenerationinteger · required

Current positive execution epoch used to reject writes from stale or handed-off harnesses. The value must be an integer.

envelope.leaseExpiresAtstring · required

RFC 3339 lease expiration timestamp; null means no active lease exists.

envelope.heartbeatRecommendedSecondsinteger · required

Recommended maximum interval between heartbeats, in seconds. The value must be an integer.

envelope.harnessDescriptorobject · required

Self-declared harness, agent, model, and supported-protocol metadata recorded on the execution claim for compatibility and audit.

envelope.harnessDescriptor.harnessstring · required: Harness product name declared by the caller; Semel does not independently verify it. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
envelope.harnessDescriptor.harnessVersionstring · optional: 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.
minimum length: 1 · maximum length: 100
envelope.harnessDescriptor.agentstring · optional: 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.
minimum length: 1 · maximum length: 200
envelope.harnessDescriptor.agentVersionstring · optional: 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.
minimum length: 1 · maximum length: 100
envelope.harnessDescriptor.modelstring · optional: 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.
minimum length: 1 · maximum length: 200
envelope.harnessDescriptor.modelProviderstring · optional: 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.
minimum length: 1 · maximum length: 100

activeSkillany of · required

Currently active pinned skill role and cursor; null means activation has not begun. A null value explicitly means no current value is available.

any of

Branch 1

activeSkill.rolestring · required: Pinned reviewer or artifact role used by the execution bundle.
activeSkill.cursorstring · required: Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning.

Branch 2

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · claimed

{
  "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
    }
  }
}

MCP wire envelope

{
  "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
      }
    }
  }
}

executionId ← structuredContent.envelope.executionId
canonicalBundleSha256 ← structuredContent.canonicalBundleSha256

Next permitted action: Persist executionId, fenceGeneration, bundle hash, lease guidance, and activeSkill from structuredContent.

Complete raw result schema

Output

{
  "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
}

Recovery: GRANT_EXPIRED, PROTOCOL_VERSION_UNSUPPORTED, STALE_FENCE, PROJECT_ACCESS_DENIEDRelated: review_execution_grant_request, review_execution_status

review_execution_grant_request

read

Discover or request the operator-issued execution grant that authorizes this harness to claim a review session.

Mode: read · low risk
Scopes: brief:read, review:execute
Confirmation: operator_grant
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel run the checkout brief review locally”
Errors: GRANT_REQUIRED GRANT_EXPIRED PROJECT_ACCESS_DENIED
Related: review_execution_claim, review_execution_status

Arguments

reviewSessionIdstring · required: Review-session identifier returned by review_start, review_new_pass, or execution status. Minimum accepted length or value is 1.
minimum length: 1

Runnable arguments · Claim and execute a local review session

{
  "reviewSessionId": "rs_fixture_engineering"
}

Binding template

{
  "reviewSessionId": "{{reviewSessionId}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

any of

Branch 1

status"ready" · required

Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "ready".

grantobject · required

Current human-approved execution grant summary.

grant.grantIdstring · required: Execution-grant identifier returned when the human approval boundary is satisfied.
grant.statestring · required: Current typed lifecycle state; the schema enum or union branch defines allowed values.
grant.intentstring · required: Human-approved execution intent bound to the grant.
grant.expiresAtstring · required: RFC 3339 expiration timestamp.

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Branch 2

status"approval_required" · required

Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "approval_required".

approvalUristring · required

Semel URI where a human can inspect and approve the execution grant.

pollHandlestring · required

Opaque handle used to poll while human grant approval is pending.

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · approval-required

{
  "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"
    }
  }
}

MCP wire envelope

{
  "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"
      }
    }
  }
}

approvalUri ← structuredContent.approvalUri

Next permitted action: Show approvalUri to the human and poll only as instructed.

Complete raw result schema

Output

{
  "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
    }
  ]
}

Recovery: GRANT_REQUIRED, GRANT_EXPIRED, PROJECT_ACCESS_DENIEDRelated: review_execution_claim, review_execution_status

review_execution_heartbeat

write · idempotent (needs idempotencyKey)

Renew the current fenced epoch lease.

Mode: write · low risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “keep my claim alive while the reviewer skill works”
Errors: STALE_FENCE LEASE_EXPIRED PROJECT_ACCESS_DENIED
Related: review_execution_sync, review_execution_release

Arguments

executionIdstring · required: External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
minimum length: 1
fenceGenerationinteger · 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.
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Claim and execute a local review session

{
  "executionId": "xex_fixture_engineering",
  "fenceGeneration": 1,
  "idempotencyKey": "recipe-execution-heartbeat-v1"
}

Binding template

{
  "executionId": "{{executionId}}",
  "fenceGeneration": 1,
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

leaseExpiresAtstring · required

RFC 3339 lease expiration timestamp; null means no active lease exists.

heartbeatRecommendedSecondsinteger · required

Recommended maximum interval between heartbeats, in seconds. The value must be an integer.

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · lease-renewed

{
  "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
    }
  }
}

MCP wire envelope

{
  "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
      }
    }
  }
}

leaseExpiresAt ← structuredContent.leaseExpiresAt

Next permitted action: Schedule the next heartbeat from heartbeatRecommendedSeconds.

Complete raw result schema

Output

{
  "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
}

Recovery: STALE_FENCE, LEASE_EXPIRED, PROJECT_ACCESS_DENIEDRelated: review_execution_sync, review_execution_release

review_execution_release

write · idempotent (needs idempotencyKey)

Yield the current fenced epoch for handoff or operator stop.

Mode: write · low risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “hand this session off to Codex”
Errors: STALE_FENCE PROJECT_ACCESS_DENIED
Related: review_execution_claim, review_execution_status

Arguments

executionIdstring · required: External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
minimum length: 1
fenceGenerationinteger · 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".
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Claim and execute a local review session

{
  "executionId": "xex_fixture_engineering",
  "fenceGeneration": 1,
  "reason": "handoff",
  "idempotencyKey": "recipe-execution-release-v1"
}

Binding template

{
  "executionId": "{{executionId}}",
  "fenceGeneration": 1,
  "reason": "handoff",
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

releasedtrue · required

Confirms that the execution lease was released. This branch always uses true.

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · released

{
  "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
    }
  }
}

MCP wire envelope

{
  "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
      }
    }
  }
}

released ← structuredContent.released

Next permitted action: Stop; the next harness must claim a fresh epoch and repeat local evidence confirmation.

Complete raw result schema

Output

{
  "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
}

Recovery: STALE_FENCE, PROJECT_ACCESS_DENIEDRelated: review_execution_claim, review_execution_status

review_execution_skill_get

read

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 · low risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/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: review_execution_claim, review_execution_checkpoint_append, review_execution_status

Arguments

executionIdstring · required: External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
minimum length: 1
rolestring · required: Pinned reviewer or artifact role used by the execution bundle. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200

Runnable arguments · Claim and execute a local review session

{
  "executionId": "xex_fixture_engineering",
  "role": "engineering"
}

Binding template

{
  "executionId": "{{executionId}}",
  "role": "engineering"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

artifactobject · required

Exact content-addressed skill artifact selected from the frozen execution bundle.

artifact.rolestring · required: Pinned reviewer or artifact role used by the execution bundle. Minimum accepted length or value is 1.
minimum length: 1
artifact.versionstring · required: Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 1.
minimum length: 1
artifact.sha256string · required: Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
pattern: ^[a-f0-9]{64}$
artifact.framingHashany of · 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.
any of
Branch 1
pattern: ^[a-f0-9]{64}$
Branch 2
artifact.contentTypestring · required: 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.
minimum length: 1
artifact.bytesstring · required: Exact UTF-8 skill artifact body; verify its SHA-256 before activation.

Example structured result · active-skill

{
  "artifact": {
    "role": "engineering",
    "version": "1",
    "sha256": "182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7",
    "framingHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
    "contentType": "text/markdown",
    "bytes": "# Engineering review\n\nValidate the brief against the repository evidence."
  }
}

MCP wire envelope

{
  "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."
    }
  }
}

skillSha256 ← structuredContent.artifact.sha256

Next permitted action: Verify exact pinned hash/framing and execute only the active skill bytes.

Complete raw result schema

Output

{
  "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
}

Recovery: PROTOCOL_VERSION_UNSUPPORTED, LEASE_EXPIRED, STALE_FENCE, CANCELLED, PAYLOAD_REJECTED, PROJECT_ACCESS_DENIEDRelated: review_execution_claim, review_execution_checkpoint_append, review_execution_status

review_execution_status

read

Return the authoritative execution state — always callable, the documented fail-safe.

Mode: read · low risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “what is the current state of my claimed session”
Errors: PROJECT_ACCESS_DENIED
Related: review_execution_sync

Arguments

reviewSessionIdstring · 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. Minimum accepted length or value is 1.
minimum length: 1
executionIdstring · 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. Minimum accepted length or value is 1.
minimum length: 1

Runnable arguments · Recover authoritative local execution state

{
  "reviewSessionId": "rs_fixture_engineering"
}

Binding template

{
  "reviewSessionId": "{{reviewSessionId}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

executionany of · required

Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available.

any of

Branch 1

execution.executionIdstring · required: External-execution identifier returned by a successful execution claim or status lookup.
execution.reviewSessionIdstring · required: Review-session identifier returned by review_start, review_new_pass, or execution status.
execution.statestring · required: Current typed lifecycle state; the schema enum or union branch defines allowed values.
execution.currentFenceGenerationinteger · required: Active execution fence generation; refresh local state to this integer before attempting another fenced write. The value must be an integer.
execution.activeSkillCursorstring | 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.

Branch 2

epochany of · 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.

any of

Branch 1

epoch.fenceGenerationinteger · required: Current positive execution epoch used to reject writes from stale or handed-off harnesses. The value must be an integer.
epoch.leaseExpiresAtstring | null · required: RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
epoch.heartbeatAtstring | 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.claimedByPrincipalstring · required: Agent principal identifier that claimed this execution epoch.
epoch.startedAtstring · required: RFC 3339 timestamp when the execution epoch started.
epoch.endedAtstring | 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.

Branch 2

checkpointHighWaterMarkinteger · required

Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.

openQuestionCountinteger · required

Number of durable questions still awaiting an accepted answer. The value must be an integer.

certificateReferenceany of · 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.

any of

Branch 1

certificateReference.certificateIdstring · required: Execution-certificate identifier assigned after successful finalization.
certificateReference.statestring · required: Current typed lifecycle state; the schema enum or union branch defines allowed values.

Branch 2

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · execution-status

{
  "execution": {
    "executionId": "xex_fixture_engineering",
    "reviewSessionId": "rs_fixture_engineering",
    "state": "running",
    "currentFenceGeneration": 1,
    "activeSkillCursor": null
  },
  "epoch": {
    "fenceGeneration": 1,
    "leaseExpiresAt": "2026-09-07T16:15:00.000Z",
    "heartbeatAt": "2026-09-07T16:00:30.000Z",
    "claimedByPrincipal": "example",
    "startedAt": "2026-09-07T16:00:00.000Z",
    "endedAt": null
  },
  "checkpointHighWaterMark": 0,
  "openQuestionCount": 0,
  "certificateReference": null,
  "controlBlock": {
    "state": {
      "sessionState": "running",
      "protocolVersion": "1.1"
    },
    "allowedNextOperations": [
      {
        "operation": "review_execution_skill_get",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_checkpoint_append",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_heartbeat",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_question_open",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_submit",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_release",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_sync",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_status",
        "preconditions": [
          "Always callable as the documented fail-safe."
        ]
      }
    ],
    "completion": {
      "complete": false,
      "unmetRequirements": [],
      "certificateState": "not_applicable"
    },
    "progress": {
      "checkpointHighWaterMark": 0,
      "openQuestionCount": 0,
      "leaseExpiresAt": "2026-09-07T16:15:00.000Z",
      "suggestedPollAt": "2026-09-07T16:05:00.000Z"
    },
    "operatorAction": {
      "required": false
    }
  }
}

MCP wire envelope

{
  "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\":0,\"openQuestionCount\":0,\"certificateReference\":null,\"controlBlock\":{\"state\":{\"sessionState\":\"running\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_skill_get\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_checkpoint_append\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_heartbeat\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_question_open\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_submit\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_release\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_sync\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":0,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}}}"
    }
  ],
  "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": 0,
    "openQuestionCount": 0,
    "certificateReference": null,
    "controlBlock": {
      "state": {
        "sessionState": "running",
        "protocolVersion": "1.1"
      },
      "allowedNextOperations": [
        {
          "operation": "review_execution_skill_get",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_checkpoint_append",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_heartbeat",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_question_open",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_submit",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_release",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_sync",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_status",
          "preconditions": [
            "Always callable as the documented fail-safe."
          ]
        }
      ],
      "completion": {
        "complete": false,
        "unmetRequirements": [],
        "certificateState": "not_applicable"
      },
      "progress": {
        "checkpointHighWaterMark": 0,
        "openQuestionCount": 0,
        "leaseExpiresAt": "2026-09-07T16:15:00.000Z",
        "suggestedPollAt": "2026-09-07T16:05:00.000Z"
      },
      "operatorAction": {
        "required": false
      }
    }
  }
}

epoch ← structuredContent.epoch
executionId ← structuredContent.execution.executionId

Next permitted action: Inspect controlBlock, current epoch/lease, pending questions, and allowedNextOperations.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: review_execution_sync

review_execution_submit

write · idempotent (needs idempotencyKey)

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 · high risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “submit my completed review for this session”
Errors: VALIDATION_FAILED BRIEF_VERSION_CONFLICT QUESTION_OPEN STALE_FENCE PROJECT_ACCESS_DENIED
Related: review_execution_status, review_execution_checkpoint_append, review_execution_grant_request, review_status

Arguments

executionIdstring · required

External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.

minimum length: 1

fenceGenerationinteger · 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.

submissionRevisioninteger · 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.

canonicalBundleSha256string · required

Lowercase hexadecimal SHA-256 digest of the frozen canonical execution bundle. Minimum accepted length or value is 1.

minimum length: 1

resultobject · 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.findingsarray · optional

Reviewer findings associated with the selected brief version. Omission uses the schema default []. An empty array explicitly means no matching items.

default: [] · maximum items: 50

Array item · object

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[].notestring · required

Reviewer-facing finding detail that explains the observed issue and the evidence-based change requested. Maximum accepted length or value is 4000.

maximum length: 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[].citationsarray · optional

maximum items: 5

Array item · any of

any of

Branch 1

result.findings[].citations[].sourceType"brief-section" · required: Discriminator identifying the evidence source variant. This branch always uses "brief-section".
result.findings[].citations[].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[].statementIdstring · optional: 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.
minimum length: 1 · maximum length: 200
result.findings[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

Branch 2

result.findings[].citations[].sourceType"artifact" · required: Discriminator identifying the evidence source variant. This branch always uses "artifact".
result.findings[].citations[].artifactIdstring · required: Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
result.findings[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

Branch 3

result.findings[].citations[].sourceType"repository-code" · required: Discriminator identifying the evidence source variant. This branch always uses "repository-code".
result.findings[].citations[].citationKeystring · required: Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
result.findings[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

result.questionsarray · optional

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.

default: [] · maximum items: 50

Array item · object

result.questions[].decisionKeystring · required

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.

minimum length: 1 · maximum length: 200 · pattern: ^[a-z0-9]+(?:[._-][a-z0-9]+)*$

result.questions[].textstring · required

Human-authored or model-produced text for this typed record. Maximum accepted length or value is 4000.

maximum length: 4000

result.questions[].context_excerptstring · optional

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.

maximum length: 2000

result.questions[].recommendationstring · required

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.

minimum length: 1 · maximum length: 1200

result.questions[].recommendationRationalestring · required

Evidence-based explanation of why the reviewer recommends the proposed answer. Accepted length or value is 1 through 1200, inclusive.

minimum length: 1 · maximum length: 1200

result.questions[].consequenceOfDeferringstring · required

Concrete product or engineering consequence of postponing the requested decision. Accepted length or value is 1 through 1200, inclusive.

minimum length: 1 · maximum length: 1200

result.questions[].optionsarray · optional

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.

minimum items: 2 · maximum items: 5

Array item · string

maximum length: 1000

result.questions[].suggestedRespondentIdstring · required

Optional Semel user identifier suggested to answer the question. Accepted length or value is 1 through 160, inclusive.

minimum length: 1 · maximum length: 160

result.questions[].citationsarray · optional

maximum items: 5

Array item · any of

any of

Branch 1

result.questions[].citations[].sourceType"brief-section" · required: Discriminator identifying the evidence source variant. This branch always uses "brief-section".
result.questions[].citations[].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[].statementIdstring · optional: 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.
minimum length: 1 · maximum length: 200
result.questions[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

Branch 2

result.questions[].citations[].sourceType"artifact" · required: Discriminator identifying the evidence source variant. This branch always uses "artifact".
result.questions[].citations[].artifactIdstring · required: Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
result.questions[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

Branch 3

result.questions[].citations[].sourceType"repository-code" · required: Discriminator identifying the evidence source variant. This branch always uses "repository-code".
result.questions[].citations[].citationKeystring · required: Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
result.questions[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

result.codeClaimsarray · optional

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.

maximum items: 50

Array item · object

result.codeClaims[].claimstring · required

Concise factual assertion about repository behavior that the evidence checker must verify before publication. Accepted length or value is 1 through 4000, inclusive.

minimum length: 1 · maximum length: 4000

result.codeClaims[].citationsarray · required

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.

minimum items: 1 · maximum items: 5

Array item · any of

any of

Branch 1

result.codeClaims[].citations[].sourceType"brief-section" · required: Discriminator identifying the evidence source variant. This branch always uses "brief-section".
result.codeClaims[].citations[].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[].statementIdstring · optional: 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.
minimum length: 1 · maximum length: 200
result.codeClaims[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

Branch 2

result.codeClaims[].citations[].sourceType"artifact" · required: Discriminator identifying the evidence source variant. This branch always uses "artifact".
result.codeClaims[].citations[].artifactIdstring · required: Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
result.codeClaims[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

Branch 3

result.codeClaims[].citations[].sourceType"repository-code" · required: Discriminator identifying the evidence source variant. This branch always uses "repository-code".
result.codeClaims[].citations[].citationKeystring · required: Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
result.codeClaims[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

result.codeClaims[].consequencestring · optional

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.

minimum length: 1 · maximum length: 4000

result.codeClaims[].uncertaintystring · optional

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.

minimum length: 1 · maximum length: 4000

result.codeClaims[].recommendationstring · optional

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.

minimum length: 1 · maximum length: 4000

result.sectionEditsobject · 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.goalstring · optional

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.

maximum length: 4000

result.sectionEdits.userPersonaContextstring · optional

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.

maximum length: 4000

result.sectionEdits.scopestring · optional

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.

maximum length: 4000

result.sectionEdits.outOfScopestring · optional

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.

maximum length: 4000

result.sectionEdits.requirementsarray · optional

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

result.sectionEdits.edgeCasesarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

result.sectionEdits.acceptanceCriteriaarray · optional

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.

maximum items: 50

Array item · object

result.sectionEdits.acceptanceCriteria[].textstring · required

Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.

minimum length: 1 · maximum length: 1000

result.sectionEdits.acceptanceCriteria[].implementationboolean · 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[].manualEvidenceobject · 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.rationalestring · required: Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
result.sectionEdits.acceptanceCriteria[].manualEvidence.evidencePathstring · required: Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000

result.sectionEdits.acceptanceCriteria[].idstring · optional

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.

minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

result.sectionEdits.acceptanceCriteria[].citationsarray · optional

maximum items: 5

Array item · any of

any of

Branch 1

result.sectionEdits.acceptanceCriteria[].citations[].sourceType"brief-section" · required: Discriminator identifying the evidence source variant. This branch always uses "brief-section".
result.sectionEdits.acceptanceCriteria[].citations[].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[].statementIdstring · optional: 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.
minimum length: 1 · maximum length: 200
result.sectionEdits.acceptanceCriteria[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

Branch 2

result.sectionEdits.acceptanceCriteria[].citations[].sourceType"artifact" · required: Discriminator identifying the evidence source variant. This branch always uses "artifact".
result.sectionEdits.acceptanceCriteria[].citations[].artifactIdstring · required: Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
result.sectionEdits.acceptanceCriteria[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

Branch 3

result.sectionEdits.acceptanceCriteria[].citations[].sourceType"repository-code" · required: Discriminator identifying the evidence source variant. This branch always uses "repository-code".
result.sectionEdits.acceptanceCriteria[].citations[].citationKeystring · required: Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
result.sectionEdits.acceptanceCriteria[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

result.sectionEdits.rolesPermissionsarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

result.sectionEdits.statesarray · optional

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

result.sectionEdits.productSolutionstring · optional

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.

maximum length: 4000

result.sectionEdits.technicalSolutionstring · optional

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.

maximum length: 4000

result.sectionEdits.dataModelImplicationsstring · optional

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.

maximum length: 4000

result.sectionEdits.architectureAssumptionsstring · optional

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.

maximum length: 4000

result.sectionEdits.designstring · optional

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.

maximum length: 4000

result.sectionEdits.testingQaChecklistarray · optional

maximum items: 50

Array item · object

result.sectionEdits.testingQaChecklist[].textstring · required: Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000

result.sectionEdits.testPlanUnitarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

result.sectionEdits.testPlanIntegrationarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

result.sectionEdits.testPlanUiUxarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

result.sectionEdits.openQuestionsarray · optional

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.

maximum items: 50

Array item · string

minimum length: 1 · maximum length: 1000

result.sectionEdits.generatedTicketsarray · optional

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.

maximum items: 50

Array item · object

result.sectionEdits.generatedTickets[].idstring · optional: 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.
minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
result.sectionEdits.generatedTickets[].titlestring · required: Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
minimum length: 1 · maximum length: 500
result.sectionEdits.generatedTickets[].descriptionany of · 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.
any of
Branch 1
maximum length: 10000
Branch 2
result.sectionEdits.generatedTickets[].boundCriteriaarray · optional: 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.
maximum items: 50
Array item · string
minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$
result.sectionEdits.generatedTickets[].boundRequirementsarray · optional: 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.
maximum items: 50
Array item · string
minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

result.sectionEdits.requiredEvidencearray · optional

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.

maximum items: 50

Array item · object

result.sectionEdits.requiredEvidence[].textstring · required

Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.

minimum length: 1 · maximum length: 1000

result.sectionEdits.requiredEvidence[].implementationboolean · 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[].manualEvidenceobject · 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.rationalestring · required: Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
result.sectionEdits.requiredEvidence[].manualEvidence.evidencePathstring · required: Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000

result.sectionEdits.requiredEvidence[].idstring · optional

minimum length: 1 · maximum length: 200 · pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]*$

result.sectionEdits.requiredEvidence[].citationsarray · optional

maximum items: 5

Array item · any of

any of

Branch 1

result.sectionEdits.requiredEvidence[].citations[].sourceType"brief-section" · required: Discriminator identifying the evidence source variant. This branch always uses "brief-section".
result.sectionEdits.requiredEvidence[].citations[].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[].statementIdstring · optional: 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.
minimum length: 1 · maximum length: 200
result.sectionEdits.requiredEvidence[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

Branch 2

result.sectionEdits.requiredEvidence[].citations[].sourceType"artifact" · required: Discriminator identifying the evidence source variant. This branch always uses "artifact".
result.sectionEdits.requiredEvidence[].citations[].artifactIdstring · required: Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
result.sectionEdits.requiredEvidence[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

Branch 3

result.sectionEdits.requiredEvidence[].citations[].sourceType"repository-code" · required: Discriminator identifying the evidence source variant. This branch always uses "repository-code".
result.sectionEdits.requiredEvidence[].citations[].citationKeystring · required: Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
result.sectionEdits.requiredEvidence[].citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200

result.sectionEdits.decisionsarray · optional

maximum items: 50

Array item · object

result.sectionEdits.decisions[].textstring · required: Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
result.sectionEdits.decisions[].sourcestring · optional: 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.
maximum length: 1000

result.sectionEdits.sourceArtifactLinksarray · optional

maximum items: 50

Array item · object

result.sectionEdits.sourceArtifactLinks[].labelstring · required: Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive.
minimum length: 1 · maximum length: 1000
result.sectionEdits.sourceArtifactLinks[].kindstring · optional: 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.
maximum length: 200

result.summaryOfChangesstring · optional

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.

maximum length: 4000

idempotencyKeystring · required

Caller-unique key making this mutation exactly-once (see the receipt contract).

minimum length: 1

Runnable arguments · Claim and execute a local review session

{
  "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

{
  "executionId": "{{executionId}}",
  "fenceGeneration": 1,
  "submissionRevision": 1,
  "canonicalBundleSha256": "{{canonicalBundleSha256}}",
  "result": {
    "reviewer": "engineering",
    "findings": [],
    "questions": [],
    "summaryOfChanges": "Validated retry-safe payment intent reuse."
  },
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

any of

Branch 1

status"completed" · required

Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "completed".

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

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

briefVersionNumany of · 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.

any of

Branch 1

Branch 2

certificateReferenceany of · 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.

any of

Branch 1

certificateReference.certificateIdstring · required: Execution-certificate identifier assigned after successful finalization.
certificateReference.statestring · required: Current typed lifecycle state; the schema enum or union branch defines allowed values.

Branch 2

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

cascadeany of · 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.

any of

Branch 1

cascade.status"awaiting_local_claim" · required

Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "awaiting_local_claim".

cascade.runIdstring · required

Review-run identifier returned by a review start, status, or cascade handoff result.

cascade.reviewSessionIdstring | 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.

cascade.cascadeStepIdstring · required

Identifier of the configured reviewer-cascade step associated with this run.

cascade.grantApprovalUristring · 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.

cascade.controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

cascade.controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

cascade.controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
cascade.controlBlock.state.executionIdstring · 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.
cascade.controlBlock.state.epochinteger · 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.
cascade.controlBlock.state.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
cascade.controlBlock.state.bundleVersionstring · 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.

cascade.controlBlock.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

cascade.controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
cascade.controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

cascade.controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

cascade.controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
cascade.controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
cascade.controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

cascade.controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

cascade.controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
cascade.controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
cascade.controlBlock.progress.leaseExpiresAtstring | null · required: RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
cascade.controlBlock.progress.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

cascade.controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

cascade.controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
cascade.controlBlock.operatorAction.uristring · 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.
cascade.controlBlock.operatorAction.reasonstring · 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.

cascade.controlBlock.recoveryobject · 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.

cascade.controlBlock.recovery.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
cascade.controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
cascade.controlBlock.recovery.recoveryOperationstring · 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.

cascade.controlBlock.errorobject · 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.

cascade.controlBlock.error.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
cascade.controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
cascade.controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
cascade.controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
cascade.controlBlock.error.operatorApprovalUristring · 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.
cascade.controlBlock.error.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Branch 2

cascade.status"in_progress" · required: Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "in_progress".
cascade.runIdstring · required: Review-run identifier returned by a review start, status, or cascade handoff result.
cascade.reviewSessionIdstring | 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.
cascade.cascadeStepIdstring · required: Identifier of the configured reviewer-cascade step associated with this run.
cascade.executionany of · 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".
any of
Branch 1
Branch 2

Branch 3

cascade.status"settled" · required: Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "settled".
cascade.runIdstring · required: Review-run identifier returned by a review start, status, or cascade handoff result.
cascade.cascadeStepIdstring · required: Identifier of the configured reviewer-cascade step associated with this run.
cascade.runStatusstring · required: Terminal or current review-run status returned by finalization when no additional cascade dispatch is required.

Branch 4

cascade.status"gate_wait" · required: Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "gate_wait".
cascade.cascadeStepIdstring · required: Identifier of the configured reviewer-cascade step associated with this run.

Branch 5

cascade.status"blocked" · required: Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "blocked".
cascade.cascadeStepIdstring · required: Identifier of the configured reviewer-cascade step associated with this run.
cascade.reason"cap_exceeded" · required: Typed or human-readable reason for the current outcome; omission means no reason is required. This branch always uses "cap_exceeded".
cascade.hardCapCentsinteger · required: Workspace hard spending cap in integer US-dollar cents. The value must be an integer.
cascade.spentThisMonthCentsinteger · required: Workspace spend in integer US-dollar cents for the current billing month. The value must be an integer.

Branch 6

cascade.status"cascade_complete" · required: Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "cascade_complete".

Branch 7

cascade.status"none" · required: Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "none".

Branch 8

cascade.status"pending" · required: Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "pending".
cascade.reasonstring · required: Typed or human-readable reason for the current outcome; omission means no reason is required.

Branch 2

status"repair_required" · required

Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "repair_required".

submissionRevisioninteger · required

Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer.

payloadSha256string · required

Lowercase hexadecimal SHA-256 digest of the canonical submitted payload.

violationsarray · required

Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items.

minimum items: 1

Array item · object

violations[].pointerstring · required: RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root.
violations[].ruleIdstring · required: Stable validation-rule identifier for this violation.
violations[].remediationCategorystring · required: Machine-readable category describing the required correction.
violations[].messagestring · required: User-facing validation or remediation message that contains no secret material.

remainingRepairAttemptsinteger · required

Distinct corrected submissions still allowed before operator attention is required. Minimum accepted length or value is 0. The value must be an integer.

minimum: 0

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Branch 3

status"needs_attention" · required

Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "needs_attention".

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

submissionRevisioninteger · required

Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer.

violationsarray · required

Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items.

Array item · object

violations[].pointerstring · required: RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root.
violations[].ruleIdstring · required: Stable validation-rule identifier for this violation.
violations[].remediationCategorystring · required: Machine-readable category describing the required correction.
violations[].messagestring · required: User-facing validation or remediation message that contains no secret material.

historyarray · required

Complete safe submission-validation history, oldest attempt first. An empty array explicitly means no matching items.

Array item · object

history[].submissionRevisioninteger · required

Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer.

history[].payloadSha256string · required

Lowercase hexadecimal SHA-256 digest of the canonical submitted payload.

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

history[].violationsarray · required

Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items.

Array item · object

history[].violations[].pointerstring · required: RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root.
history[].violations[].ruleIdstring · required: Stable validation-rule identifier for this violation.
history[].violations[].remediationCategorystring · required: Machine-readable category describing the required correction.
history[].violations[].messagestring · required: User-facing validation or remediation message that contains no secret material.

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Branch 4

status"version_conflict" · required

Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "version_conflict".

pinnedBriefBaseVersionIdstring · required

Immutable brief-version identifier frozen when the execution began and used for stale-base detection.

pinnedBriefBaseVersionNuminteger · required

Monotonic brief-version number frozen when the execution began and used for stale-base detection. The value must be an integer.

currentBriefVersionIdstring · required

Immutable identifier of the current canonical brief version reported after a stale-base rejection.

currentBriefVersionNuminteger · required

Monotonic number of the current canonical brief version reported after a stale-base rejection. The value must be an integer.

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · completed

{
  "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
      }
    }
  }
}

MCP wire envelope

{
  "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
        }
      }
    }
  }
}

cascade ← structuredContent.cascade

Next permitted action: Follow cascade.status; request the next grant only for awaiting_local_claim and never wait for certificate signing.

Complete raw result schema

Output

{
  "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
    }
  ]
}

Recovery: VALIDATION_FAILED, BRIEF_VERSION_CONFLICT, QUESTION_OPEN, STALE_FENCE, PROJECT_ACCESS_DENIEDRelated: review_execution_status, review_execution_checkpoint_append, review_execution_grant_request, review_status

review_execution_sync

read

Cursor-poll for recorded answers, cancellation, handoff, and lease state.

Mode: read · low risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “check whether the operator answered my open question yet”
Errors: PROJECT_ACCESS_DENIED
Related: review_question_answer, review_execution_status

Arguments

executionIdstring · required: External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
minimum length: 1
cursorstring · optional: 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.
minimum length: 1
fenceGenerationinteger · 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.

Runnable arguments · Recover authoritative local execution state

{
  "executionId": "xex_fixture_engineering"
}

Binding template

{
  "executionId": "{{executionId}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

answersarray · required

Accepted durable answers emitted since the requested synchronization cursor, in causal order. An empty array explicitly means no matching items.

Array item · object

answers[].questionIdstring · required: Durable question identifier returned by review_question_open or execution sync.
answers[].answerIdstring · required: Immutable answer identifier assigned by Semel when an answer attempt is recorded.
answers[].channelstring · required: Typed delivery or answer channel recorded as provenance.
answers[].answerTextstring · required: Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit.
answers[].answeredAtstring · required: RFC 3339 timestamp when the active answer was recorded.

cancellationRequestedboolean · required

Whether a cancellation request is pending for this execution.

serverCommandsarray · required

Ordered server commands issued since the supplied synchronization cursor. An empty array explicitly means no matching items.

Array item · object

serverCommands[].commandstring · required: Server-issued synchronization command the harness must process in order.
serverCommands[].issuedAtstring · required: RFC 3339 timestamp when the server command was issued.

handoffobject · required

Execution handoff state relative to the caller’s remembered epoch.

handoff.occurredboolean · required: Whether an execution handoff occurred since the supplied cursor or epoch.
handoff.currentFenceGenerationinteger · required: Active execution fence generation; refresh local state to this integer before attempting another fenced write. The value must be an integer.

leaseobject · required

Current lease identity and expiry as observed during synchronization.

lease.fenceGenerationany of · 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.
any of
Branch 1
Branch 2
lease.leaseExpiresAtstring | null · required: RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
lease.currentboolean · required: Whether the caller-provided fence generation is still the active execution epoch.

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

suggestedNextPollAtstring · required

RFC 3339 timestamp for the next recommended sync or status poll.

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · sync

{
  "answers": [],
  "cancellationRequested": false,
  "serverCommands": [],
  "handoff": {
    "occurred": false,
    "currentFenceGeneration": 1
  },
  "lease": {
    "fenceGeneration": 1,
    "leaseExpiresAt": "2026-09-07T16:15:00.000Z",
    "current": true
  },
  "nextCursor": null,
  "suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
  "controlBlock": {
    "state": {
      "sessionState": "running",
      "protocolVersion": "1.1"
    },
    "allowedNextOperations": [
      {
        "operation": "review_execution_skill_get",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_checkpoint_append",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_heartbeat",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_question_open",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_submit",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_release",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_sync",
        "preconditions": [
          "The active epoch may progress, ask a question, submit, or release."
        ]
      },
      {
        "operation": "review_execution_status",
        "preconditions": [
          "Always callable as the documented fail-safe."
        ]
      }
    ],
    "completion": {
      "complete": false,
      "unmetRequirements": [],
      "certificateState": "not_applicable"
    },
    "progress": {
      "checkpointHighWaterMark": 0,
      "openQuestionCount": 0,
      "leaseExpiresAt": "2026-09-07T16:15:00.000Z",
      "suggestedPollAt": "2026-09-07T16:05:00.000Z"
    },
    "operatorAction": {
      "required": false
    }
  }
}

MCP wire envelope

{
  "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\":null,\"suggestedNextPollAt\":\"2026-09-07T16:05:00.000Z\",\"controlBlock\":{\"state\":{\"sessionState\":\"running\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_skill_get\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_checkpoint_append\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_heartbeat\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_question_open\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_submit\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_release\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_sync\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":0,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}}}"
    }
  ],
  "structuredContent": {
    "answers": [],
    "cancellationRequested": false,
    "serverCommands": [],
    "handoff": {
      "occurred": false,
      "currentFenceGeneration": 1
    },
    "lease": {
      "fenceGeneration": 1,
      "leaseExpiresAt": "2026-09-07T16:15:00.000Z",
      "current": true
    },
    "nextCursor": null,
    "suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
    "controlBlock": {
      "state": {
        "sessionState": "running",
        "protocolVersion": "1.1"
      },
      "allowedNextOperations": [
        {
          "operation": "review_execution_skill_get",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_checkpoint_append",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_heartbeat",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_question_open",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_submit",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_release",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_sync",
          "preconditions": [
            "The active epoch may progress, ask a question, submit, or release."
          ]
        },
        {
          "operation": "review_execution_status",
          "preconditions": [
            "Always callable as the documented fail-safe."
          ]
        }
      ],
      "completion": {
        "complete": false,
        "unmetRequirements": [],
        "certificateState": "not_applicable"
      },
      "progress": {
        "checkpointHighWaterMark": 0,
        "openQuestionCount": 0,
        "leaseExpiresAt": "2026-09-07T16:15:00.000Z",
        "suggestedPollAt": "2026-09-07T16:05:00.000Z"
      },
      "operatorAction": {
        "required": false
      }
    }
  }
}

handoff ← structuredContent.handoff

Next permitted action: Accept cancellation/takeover, or follow the server-provided recovery/grant path.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: review_question_answer, review_execution_status

review_new_pass

write · idempotent (needs idempotencyKey)

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 · high risk
Scopes: brief:read, review:run
Confirmation: explicit
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel re-run the review now that I updated the brief”
Errors: PROJECT_ACCESS_DENIED AUTHORIZATION_SCOPE_MISSING
Related: review_start, review_status, review_execution_status

Arguments

briefIdstring · required: Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1.
minimum length: 1
anchorRunIdstring · required: 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.
minimum length: 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".
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Originate and observe a review

{
  "briefId": "brf_fixture_checkout",
  "anchorRunId": "run_fixture_review",
  "execution": "local",
  "idempotencyKey": "recipe-review-new-pass-v1"
}

Binding template

{
  "briefId": "{{briefId}}",
  "anchorRunId": "{{anchorRunId}}",
  "execution": "local",
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

runobject · required

Newly created review run and its queue position.

run.idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
run.statusstring · required: Current typed status; the schema enum or union branch lists every allowed value.
run.positioninteger · required: Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer.
minimum: 0

cascadeobject · required

Observed next-step cascade handoff after submission or review admission.

cascade.projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project.
cascade.phasestring · required: Current cascade phase reported by Semel.

dispatchobject · 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.admittedboolean · required

Whether the review run was admitted for execution.

dispatch.softCapWarningboolean · required

Optional nonblocking workspace spending warning attached to admission.

dispatch.evidenceWaitobject · 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.manifestIdstring · required: Evidence manifest identifier whose readiness is being reported.
dispatch.evidenceWait.state"pending" · required: Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "pending".
dispatch.evidenceWait.deadlineAtstring · required: RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision.
dispatch.evidenceWait.requiredRepositoryCountinteger · required: Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer.
minimum: 0
dispatch.evidenceWait.unavailableRepositoryCountinteger · required: Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer.
minimum: 0
dispatch.evidenceWait.statusPathstring · required: Relative Semel API path for polling evidence readiness.
dispatch.evidenceWait.decisionPathstring · required: Relative Semel API path for the human evidence-wait decision.
dispatch.evidenceWait.actionsarray · required: User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items.
Array item · string

dispatch.reviewSessionIdstring · 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.grantApprovalUristring · 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.controlBlockobject · 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.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

dispatch.controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
dispatch.controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
dispatch.controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

dispatch.controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
dispatch.controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

dispatch.controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

dispatch.controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
dispatch.controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
dispatch.controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

dispatch.controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

dispatch.controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
dispatch.controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
dispatch.controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

dispatch.controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

dispatch.controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
dispatch.controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
dispatch.controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
dispatch.controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
dispatch.controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
dispatch.controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
dispatch.controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
dispatch.controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · local-start

{
  "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
  }
}

MCP wire envelope

{
  "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
    }
  }
}

newRunId ← structuredContent.run.id

Next permitted action: Request the returned local session grant; do not claim without approval.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIED, AUTHORIZATION_SCOPE_MISSINGRelated: review_start, review_status, review_execution_status

review_question_answer

write · idempotent (needs idempotencyKey)

Record a local_harness answer; first valid terminal answer wins.

Mode: write · low risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “the operator just told me the answer locally”
Errors: STALE_FENCE CANCELLED PROJECT_ACCESS_DENIED
Related: review_question_open, review_execution_sync

Arguments

executionIdstring · required

External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.

minimum length: 1

fenceGenerationinteger · 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.

questionIdstring · required

Durable question identifier returned by review_question_open or execution sync. Minimum accepted length or value is 1.

minimum length: 1

answerTextstring · required

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.

minimum length: 1 · maximum length: 20000

transmittingAgentstring · optional

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.

maximum length: 200

humanAttributionobject · 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.claimedNamestring · optional: 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.
maximum length: 200
humanAttribution.claimedEmailstring · optional: 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.
format: email

idempotencyKeystring · required

Caller-unique key making this mutation exactly-once (see the receipt contract).

minimum length: 1

Runnable arguments · Open and resolve durable review questions

{
  "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

{
  "executionId": "{{executionId}}",
  "fenceGeneration": 1,
  "questionId": "{{questionId}}",
  "answerText": "Use online expand/contract.",
  "transmittingAgent": "codex",
  "humanAttribution": {
    "claimedName": "Repository owner"
  },
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

outcome"accepted" | "conflict" · required

Typed result of this operation; union branches define the follow-up action for each value. Allowed values: "accepted", "conflict".

answerIdstring · required

Immutable answer identifier assigned by Semel when an answer attempt is recorded.

questionIdstring · required

Durable question identifier returned by review_question_open or execution sync.

activeAnswerobject · required

Question’s current winning immutable answer, including conflict responses.

activeAnswer.answerIdstring · required: Immutable answer identifier assigned by Semel when an answer attempt is recorded.
activeAnswer.channelstring · required: Typed delivery or answer channel recorded as provenance.
activeAnswer.answerTextstring · required: Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit.
activeAnswer.answeredAtstring · required: RFC 3339 timestamp when the active answer was recorded.

roundResumedboolean · required

Whether this accepted answer closed the question round and resumed the run.

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · accepted-answer

{
  "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
    }
  }
}

MCP wire envelope

{
  "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
      }
    }
  }
}

activeAnswer ← structuredContent.activeAnswer

Next permitted action: Resume dependent work only when this answer is accepted or matches the existing winner.

Complete raw result schema

Output

{
  "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
}

Recovery: STALE_FENCE, CANCELLED, PROJECT_ACCESS_DENIEDRelated: review_question_open, review_execution_sync

review_question_answer_supersede

write · idempotent (needs idempotencyKey)

Verified-operator correction of an already-accepted answer.

Mode: write · medium risk
Scopes: brief:read, review:execute
Confirmation: operator_grant
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “the operator corrected an earlier answer”
Errors: VALIDATION_FAILED PROJECT_ACCESS_DENIED
Related: review_question_answer, review_execution_status

Arguments

executionIdstring · required: External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
minimum length: 1
questionIdstring · required: Durable question identifier returned by review_question_open or execution sync. Minimum accepted length or value is 1.
minimum length: 1
correctedAnswerTextstring · required: Replacement answer text supplied by a verified operator while preserving answer history. Accepted length or value is 1 through 20000, inclusive.
minimum length: 1 · maximum length: 20000
reasonstring · 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. Maximum accepted length or value is 2000.
maximum length: 2000
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Open and resolve durable review questions

{
  "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

{
  "executionId": "{{executionId}}",
  "questionId": "{{questionId}}",
  "correctedAnswerText": "Use an online expand/contract migration with a compatibility window.",
  "reason": "Owner clarified rollback requirements.",
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

outcome"accepted" · required

Typed result of this operation; union branches define the follow-up action for each value. This branch always uses "accepted".

newAnswerIdstring · required

Immutable identifier of the corrected answer created by a successful supersede operation.

supersededAnswerIdstring · required

Immutable identifier of the prior answer replaced by a successful supersede operation.

recoveryCursorobject · required

Causal boundary the harness must use after an operator corrects an answer.

recoveryCursor.invalidatedFromSeqinteger · required: First checkpoint sequence considered downstream of the corrected answer. Minimum accepted length or value is 0. The value must be an integer.
minimum: 0
recoveryCursor.activeSkillCursorstring | 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.

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · superseded

{
  "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
    }
  }
}

MCP wire envelope

{
  "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
      }
    }
  }
}

recoveryCursor ← structuredContent.recoveryCursor

Next permitted action: Rework from recoveryCursor before final submission.

Complete raw result schema

Output

{
  "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
}

Recovery: VALIDATION_FAILED, PROJECT_ACCESS_DENIEDRelated: review_question_answer, review_execution_status

review_question_open

write · idempotent (needs idempotencyKey)

Durably create a question before displaying or delivering it anywhere.

Mode: write · low risk
Scopes: brief:read, review:execute
Confirmation: none
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “ask the operator whether this endpoint should require auth”
Errors: STALE_FENCE CANCELLED PROJECT_ACCESS_DENIED
Related: review_question_answer, review_execution_sync

Arguments

executionIdstring · required

External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.

minimum length: 1

fenceGenerationinteger · 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.

clientQuestionIdstring · required

Caller-stable logical question identifier; it must equal the MCP idempotency key for this call. Accepted length or value is 1 through 200, inclusive.

minimum length: 1 · maximum length: 200

textstring · required

Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 20000, inclusive.

minimum length: 1 · maximum length: 20000

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

contextExcerptstring · optional

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.

maximum length: 20000

sectionstring · optional

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.

maximum length: 200

optionsarray · optional

minimum items: 2 · maximum items: 5

Array item · string

minimum length: 1 · maximum length: 500

citationsarray · optional

Array item · any of

any of

Branch 1

citations[].sourceType"brief-section" · required: Discriminator identifying the evidence source variant. This branch always uses "brief-section".
citations[].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[].statementIdstring · optional: 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.
minimum length: 1 · maximum length: 200
citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200
citations[].briefIdstring · required: Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary.
citations[].contractVersionIdstring · required: Immutable brief contract-version identifier resolved by Semel.
citations[].versionNuminteger · 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[].reviewersarray · required: Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
minimum items: 1
Array item · "product" | "engineering" | "design" | "security" | "test"
citations[].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".

Branch 2

citations[].sourceType"artifact" · required: Discriminator identifying the evidence source variant. This branch always uses "artifact".
citations[].artifactIdstring · required: Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200
citations[].extractedTextHashstring · required: Hash of the normalized text extracted from the cited artifact, used to bind the citation to exact processed content.
citations[].reviewersarray · required: Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
minimum items: 1
Array item · "product" | "engineering" | "design" | "security" | "test"
citations[].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".

Branch 3

citations[].sourceType"repository-code" · required: Discriminator identifying the evidence source variant. This branch always uses "repository-code".
citations[].citationKeystring · required: Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
minimum length: 1 · maximum length: 200
citations[].verbatimstring · required: Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
minimum length: 1 · maximum length: 1200
citations[].evidenceManifestIdstring · required: Immutable evidence-manifest identifier captured for the review run. Minimum accepted length or value is 1.
minimum length: 1
citations[].evidenceManifestItemIdstring · required: Identifier of the exact item inside the immutable evidence manifest. Minimum accepted length or value is 1.
minimum length: 1
citations[].workspaceRepositoryIdstring · required: Workspace-scoped connected repository identifier recorded in evidence provenance. Minimum accepted length or value is 1.
minimum length: 1
citations[].revisionIdstring · required: Immutable indexed repository revision identifier. Minimum accepted length or value is 1.
minimum length: 1
citations[].commitShastring · required: Git commit SHA pinned by the evidence manifest.
pattern: ^(?:[a-f0-9]{40}|[a-f0-9]{64})$
citations[].blobShastring · required: Git blob SHA for the cited file contents.
pattern: ^(?:[a-f0-9]{40}|[a-f0-9]{64})$
citations[].pathstring · required: Repository-relative source path; it never denotes an arbitrary local filesystem path. Minimum accepted length or value is 1.
minimum length: 1
citations[].startLineinteger · 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[].endLineinteger · 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[].excerptSha256string · required: Lowercase hexadecimal SHA-256 digest of the exact cited excerpt.
pattern: ^[a-f0-9]{64}$
citations[].route"exact" | "lexical" | "hybrid" · required: Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
citations[].coverageobject · required: Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence.
Map values · any JSON value
citations[].reviewersarray · required: Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
minimum items: 1
Array item · "product" | "engineering" | "design" | "security" | "test"
citations[].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".

responseDeadlineHintstring · optional

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.

format: date-time

idempotencyKeystring · required

Caller-unique key making this mutation exactly-once (see the receipt contract).

minimum length: 1

Runnable arguments · Open and resolve durable review questions

{
  "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

{
  "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}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

questionIdstring · required

Durable question identifier returned by review_question_open or execution sync.

dedupedboolean · required

Whether the existing durable question was returned for an idempotent replay.

responseDeadlinestring · required

RFC 3339 timestamp after which the unanswered question requires recovery.

deliveryStatearray · required

Per-channel best-effort question notification outcomes. An empty array explicitly means no matching items.

Array item · object

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[].providerRefstring · 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[].safeErrorstring · 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.

controlBlockobject · required

Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.

controlBlock.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · question-opened

{
  "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
    }
  }
}

MCP wire envelope

{
  "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
      }
    }
  }
}

questionId ← structuredContent.questionId

Next permitted action: Display the durable question and its options only after this call succeeds.

Complete raw result schema

Output

{
  "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
}

Recovery: STALE_FENCE, CANCELLED, PROJECT_ACCESS_DENIEDRelated: review_question_answer, review_execution_sync

review_start

write · idempotent (needs idempotencyKey)

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 · high risk
Scopes: brief:read, review:run
Confirmation: explicit
Idempotency: Required. Reuse the key only for the same logical mutation with unchanged arguments.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “/semel run the review for the checkout brief”
Errors: PROJECT_ACCESS_DENIED AUTHORIZATION_SCOPE_MISSING
Related: review_new_pass, review_status, review_execution_status

Arguments

briefIdstring · required: Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1.
minimum length: 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".
idempotencyKeystring · required: Caller-unique key making this mutation exactly-once (see the receipt contract).
minimum length: 1

Runnable arguments · Originate and observe a review

{
  "briefId": "brf_fixture_checkout",
  "execution": "hosted",
  "idempotencyKey": "recipe-review-start-v1"
}

Binding template

{
  "briefId": "{{briefId}}",
  "execution": "hosted",
  "idempotencyKey": "{{idempotencyKey}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

runobject · required

Newly created review run and its queue position.

run.idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
run.statusstring · required: Current typed status; the schema enum or union branch lists every allowed value.
run.positioninteger · required: Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer.
minimum: 0

cascadeobject · required

Observed next-step cascade handoff after submission or review admission.

cascade.projectIdstring · required: Project identifier returned by project_create or project_list; the caller must have access to that project.
cascade.phasestring · required: Current cascade phase reported by Semel.

dispatchobject · 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.admittedboolean · required

Whether the review run was admitted for execution.

dispatch.softCapWarningboolean · required

Optional nonblocking workspace spending warning attached to admission.

dispatch.evidenceWaitobject · 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.manifestIdstring · required: Evidence manifest identifier whose readiness is being reported.
dispatch.evidenceWait.state"pending" · required: Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "pending".
dispatch.evidenceWait.deadlineAtstring · required: RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision.
dispatch.evidenceWait.requiredRepositoryCountinteger · required: Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer.
minimum: 0
dispatch.evidenceWait.unavailableRepositoryCountinteger · required: Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer.
minimum: 0
dispatch.evidenceWait.statusPathstring · required: Relative Semel API path for polling evidence readiness.
dispatch.evidenceWait.decisionPathstring · required: Relative Semel API path for the human evidence-wait decision.
dispatch.evidenceWait.actionsarray · required: User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items.
Array item · string

dispatch.reviewSessionIdstring · 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.grantApprovalUristring · 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.controlBlockobject · 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.stateobject · required

Current typed lifecycle state; the schema enum or union branch defines allowed values.

dispatch.controlBlock.state.sessionStatestring · required: Authoritative lifecycle state of the parent review session reported by the execution runbook.
dispatch.controlBlock.state.executionIdstring · 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.epochinteger · 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.protocolVersionstring · required: Semel external-execution protocol version used for this bundle or state.
dispatch.controlBlock.state.bundleVersionstring · 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.allowedNextOperationsarray · required

Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.

Array item · object

dispatch.controlBlock.allowedNextOperations[].operationstring · required: MCP operation name currently permitted by the runbook control block.
dispatch.controlBlock.allowedNextOperations[].preconditionsarray · required: Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
Array item · string

dispatch.controlBlock.completionobject · required

Authoritative completion assessment for the current execution state.

dispatch.controlBlock.completion.completeboolean · required: Whether all protocol completion requirements are currently satisfied.
dispatch.controlBlock.completion.unmetRequirementsarray · required: Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
Array item · string
dispatch.controlBlock.completion.certificateState"not_applicable" | "pending" | "signed" | "failed" · required: Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".

dispatch.controlBlock.progressobject · required

Current durable checkpoint, question, lease, and polling progress.

dispatch.controlBlock.progress.checkpointHighWaterMarkinteger · required: Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
dispatch.controlBlock.progress.openQuestionCountinteger · required: Number of durable questions still awaiting an accepted answer. The value must be an integer.
dispatch.controlBlock.progress.leaseExpiresAtstring | 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.suggestedPollAtstring · required: RFC 3339 timestamp for the next recommended status poll.

dispatch.controlBlock.operatorActionobject · required

Human action required before the protocol may continue.

dispatch.controlBlock.operatorAction.requiredboolean · required: Whether the operator action must occur before execution can continue.
dispatch.controlBlock.operatorAction.uristring · 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.reasonstring · 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.recoveryobject · 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.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
dispatch.controlBlock.recovery.idempotentboolean · required: Whether retrying the named recovery operation with identical arguments is safe.
dispatch.controlBlock.recovery.recoveryOperationstring · 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.errorobject · 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.codestring · required: Stable machine-readable protocol error code used to choose a documented recovery action.
dispatch.controlBlock.error.retryableboolean · required: Whether repeating the documented recovery operation can succeed without changing permanent state.
dispatch.controlBlock.error.currentStatestring · required: Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
dispatch.controlBlock.error.permittedNextOperationsarray · required: Operation names permitted after this protocol error. An empty array explicitly means no matching items.
Array item · string
dispatch.controlBlock.error.operatorApprovalUristring · 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.safeTextstring · required: Sanitized user-facing error text that excludes secrets and internal exception details.

Example structured result · hosted-start

{
  "run": {
    "id": "run_fixture_review",
    "status": "queued",
    "position": 0
  },
  "cascade": {
    "projectId": "prj_fixture_checkout",
    "phase": "reviewing"
  },
  "dispatch": {
    "status": "invoking",
    "admitted": true,
    "softCapWarning": false
  }
}

MCP wire envelope

{
  "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
    }
  }
}

runId ← structuredContent.run.id

Next permitted action: Poll review_status and respect configless, cap, evidence-wait, or in-flight outcomes.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIED, AUTHORIZATION_SCOPE_MISSINGRelated: review_new_pass, review_status, review_execution_status

review_status

read

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 · low risk
Scopes: brief:read, review:run
Confirmation: none
Idempotency: No idempotency key. This is a read operation.
Prerequisites: Authenticated connection, the listed scopes, and a server state that permits this operation.
Try: “what is the status of the review for this brief”
Errors: PROJECT_ACCESS_DENIED
Related: review_start, review_new_pass, review_execution_status

Arguments

briefIdstring · required: Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1.
minimum length: 1

Runnable arguments · Configure a review session at the human boundary

{
  "briefId": "brf_fixture_checkout"
}

Binding template

{
  "briefId": "{{briefId}}"
}

Complete raw parameter schema

Output

{
  "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
}

Structured result

projectIdstring · required

Project identifier returned by project_create or project_list; the caller must have access to that project.

phasestring · required

Current cascade phase reported by Semel.

inFlightboolean · required

Whether the cascade currently has an unsettled run.

executionany of · 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".

any of

Branch 1

Branch 2

awaitingLocalClaimboolean · required

Whether the next external run is waiting for a harness claim.

stepsarray · required

Configured cascade steps in execution order with their latest run state. An empty array explicitly means no matching items.

Array item · object

steps[].idstring · required

Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.

steps[].positioninteger · required

Stable zero-based or configured ordering position returned by Semel. The value must be an integer.

steps[].kindstring · required

Discriminator identifying the typed variant represented by this object.

steps[].statusstring · required

Current typed status; the schema enum or union branch lists every allowed value.

steps[].latestRunany of · required

Latest run for this cascade step; null means the step has not run. A null value explicitly means no current value is available.

any of

Branch 1

steps[].latestRun.idstring · required: Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
steps[].latestRun.statusstring · required: Current typed status; the schema enum or union branch lists every allowed value.
steps[].latestRun.createdAtstring · required: RFC 3339 timestamp assigned by Semel when this record was created.
steps[].latestRun.reviewSessionIdstring | 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.

Branch 2

latestRunIdstring | null · required

Most recent run identifier in the cascade; null means no run exists. A null value explicitly means no current value is available.

latestTerminalRunIdstring | null · required

Most recent terminal run identifier; null means none has settled. A null value explicitly means no current value is available.

evidenceWaitobject · 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.manifestIdstring · required: Evidence manifest identifier whose readiness is being reported.
evidenceWait.state"pending" · required: Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "pending".
evidenceWait.deadlineAtstring · required: RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision.
evidenceWait.requiredRepositoryCountinteger · required: Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer.
minimum: 0
evidenceWait.unavailableRepositoryCountinteger · required: Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer.
minimum: 0
evidenceWait.statusPathstring · required: Relative Semel API path for polling evidence readiness.
evidenceWait.decisionPathstring · required: Relative Semel API path for the human evidence-wait decision.
evidenceWait.actionsarray · required: User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items.
Array item · string

blockedany of · required

Non-null spending or configuration condition currently blocking review progress. A null value explicitly means no current value is available.

any of

Branch 1

blocked.reason"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.hardCapCentsinteger · required: Workspace hard spending cap in integer US-dollar cents. The value must be an integer.
blocked.spentThisMonthCentsinteger · required: Workspace spend in integer US-dollar cents for the current billing month. The value must be an integer.

Branch 2

Example structured result · review-status

{
  "projectId": "prj_fixture_checkout",
  "phase": "reviewing",
  "inFlight": false,
  "execution": "hosted",
  "awaitingLocalClaim": false,
  "steps": [],
  "latestRunId": "example",
  "latestTerminalRunId": "example",
  "blocked": null
}

MCP wire envelope

{
  "content": [
    {
      "type": "text",
      "text": "{\"projectId\":\"prj_fixture_checkout\",\"phase\":\"reviewing\",\"inFlight\":false,\"execution\":\"hosted\",\"awaitingLocalClaim\":false,\"steps\":[],\"latestRunId\":\"example\",\"latestTerminalRunId\":\"example\",\"blocked\":null}"
    }
  ],
  "structuredContent": {
    "projectId": "prj_fixture_checkout",
    "phase": "reviewing",
    "inFlight": false,
    "execution": "hosted",
    "awaitingLocalClaim": false,
    "steps": [],
    "latestRunId": "example",
    "latestTerminalRunId": "example",
    "blocked": null
  }
}

phase ← structuredContent.phase

Next permitted action: Explain the current state and the exact human portal action.

Complete raw result schema

Output

{
  "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
}

Recovery: PROJECT_ACCESS_DENIEDRelated: 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.

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.

Tool reference

MCP tools#

brief_checklist_update

Arguments

Structured result

brief_collection_list

Arguments

Structured result

brief_create

Arguments

Structured result

brief_export_markdown

Arguments

Structured result

brief_export_package

Arguments

Structured result

brief_get_full

Arguments

Structured result

brief_list

Arguments

Structured result

brief_update

Arguments

Structured result

project_codebase_link

Arguments

Structured result

project_codebases_list

Arguments

Structured result

project_context_evidence_get

Arguments

Structured result

project_context_search

Arguments

Structured result

project_context_sources_list

Arguments

Structured result

project_create

Arguments

Structured result

project_get

Arguments

Structured result

project_list

Arguments

Structured result

project_rename

Arguments

Structured result

review_cancel

Arguments

Structured result

review_execution_checkpoint_append

Arguments

Structured result

review_execution_claim

Arguments

Structured result

review_execution_grant_request

Arguments

Structured result

review_execution_heartbeat

Arguments

Structured result

review_execution_release

Arguments

Structured result

review_execution_skill_get

Arguments

Structured result

review_execution_status

Arguments

Structured result

review_execution_submit

Arguments

Structured result

MCP tools

Calling a tool correctly

What is deliberately not here