# Tool reference
Every customer-visible Semel MCP tool — purpose, required scopes, idempotency, common errors, and related tools — generated from the live operation registry.
This reference is generated from the server’s operation registry. Treat the live MCP `tools/list` result as the authority for the current session; the page explains the same inputs, outputs, scopes, state assumptions, idempotency rules, risks, errors, and related operations in a browsable form.
## MCP tools
### brief_checklist_update
Toggle a single QA-checklist row on a brief on or off, without rewriting the rest of the brief. Use to tick off or clear one acceptance check as work is verified.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `brief:write`
- Confirmation: implicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `index` — integer; required; minimum 0. Zero-based QA checklist item position, guarded by expectedText against reorder races. Minimum accepted length or value is 0. The value must be an integer.
- `expectedText` — string; required; minimum length 1; maximum length 262144. Expected current checklist text at index; a mismatch fails instead of updating the wrong row. Accepted length or value is 1 through 262144, inclusive.
- `checked` — boolean; required. Whether this QA checklist item is currently complete.
- `ifVersionNum` — integer; optional. Optional optimistic precondition using the current brief contract version number. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"index": {
"type": "integer",
"minimum": 0,
"description": "Zero-based QA checklist item position, guarded by expectedText against reorder races. Minimum accepted length or value is 0. The value must be an integer."
},
"expectedText": {
"type": "string",
"minLength": 1,
"maxLength": 262144,
"description": "Expected current checklist text at index; a mismatch fails instead of updating the wrong row. Accepted length or value is 1 through 262144, inclusive."
},
"checked": {
"type": "boolean",
"description": "Whether this QA checklist item is currently complete."
},
"ifVersionNum": {
"type": "integer",
"description": "Optional optimistic precondition using the current brief contract version number. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"index",
"expectedText",
"checked",
"briefId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"index": 0,
"expectedText": "API contract reviewed",
"checked": true,
"ifVersionNum": 4,
"idempotencyKey": "recipe-brief-checklist-update-v1"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"index": 0,
"expectedText": "API contract reviewed",
"checked": true,
"ifVersionNum": 4,
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `brief` — object; required. Current brief record returned by the operation.
- `brief.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `brief.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `brief.title` — string; required. Human-readable title displayed in Semel.
- `brief.state` — "drafting" | "in_review" | "baselined" | "in_development" | "checked" | "superseded" | "closed"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "drafting", "in_review", "baselined", "in_development", "checked", "superseded", "closed".
- `brief.currentVersionHash` — string | null; required. Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available.
- `brief.content` — object; required. Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
- `brief.content{key}` — JSON value; optional.
- `brief.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `brief.delivery` — object; optional. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value.
- `brief.delivery.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `brief.delivery.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `brief.delivery.deliveryStatus (anyOf branch 2)` — null; required.
- `brief.delivery.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `brief.delivery.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `brief.delivery.changedAt (anyOf branch 1)` — string; required; format date-time.
- `brief.delivery.changedAt (anyOf branch 2)` — null; required.
- `brief.delivery.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `brief.delivery.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `brief.delivery.source (anyOf branch 1)` — "web" | "mcp"; required.
- `brief.delivery.source (anyOf branch 2)` — null; required.
- `brief.createdNewVersion` — boolean; required. Whether the write changed canonical content and minted a new immutable brief version.
- `brief.staledApprovals` — integer; required. Number of prior approval rows made stale by this content change. The value must be an integer.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"brief": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"state": {
"type": "string",
"enum": [
"drafting",
"in_review",
"baselined",
"in_development",
"checked",
"superseded",
"closed"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"drafting\", \"in_review\", \"baselined\", \"in_development\", \"checked\", \"superseded\", \"closed\"."
},
"currentVersionHash": {
"type": [
"string",
"null"
],
"description": "Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available."
},
"content": {
"type": "object",
"additionalProperties": {},
"description": "Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
},
"delivery": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value."
},
"createdNewVersion": {
"type": "boolean",
"description": "Whether the write changed canonical content and minted a new immutable brief version."
},
"staledApprovals": {
"type": "integer",
"description": "Number of prior approval rows made stale by this content change. The value must be an integer."
}
},
"required": [
"id",
"projectId",
"title",
"state",
"currentVersionHash",
"content",
"versionNum",
"createdNewVersion",
"staledApprovals"
],
"additionalProperties": false,
"description": "Current brief record returned by the operation."
}
},
"required": [
"brief"
],
"additionalProperties": false
}
```
**Example structured result (checklist-toggled)**
```json
{
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
},
{
"id": "AC-02",
"text": "The response identifies the original payment intent."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
],
"checklist": [
{
"text": "API contract reviewed",
"checked": true
}
]
},
"versionNum": 5,
"createdNewVersion": true,
"staledApprovals": 0
}
}
```
Bindings: checklistVersionCreated from structuredContent.brief.createdNewVersion.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"brief\":{\"id\":\"brf_fixture_checkout\",\"projectId\":\"prj_fixture_checkout\",\"title\":\"Retry-safe checkout\",\"state\":\"drafting\",\"currentVersionHash\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"content\":{\"goal\":\"Prevent duplicate charges when checkout retries.\",\"requirements\":[\"Reuse one payment intent for retried submissions.\"],\"acceptanceCriteria\":[{\"id\":\"AC-01\",\"text\":\"A retried request returns the original successful result.\"},{\"id\":\"AC-02\",\"text\":\"The response identifies the original payment intent.\"}],\"sourceArtifactLinks\":[{\"label\":\"Linear ENG-42\",\"kind\":\"linear\"}],\"checklist\":[{\"text\":\"API contract reviewed\",\"checked\":true}]},\"versionNum\":5,\"createdNewVersion\":true,\"staledApprovals\":0}}"
}
],
"structuredContent": {
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
},
{
"id": "AC-02",
"text": "The response identifies the original payment intent."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
],
"checklist": [
{
"text": "API contract reviewed",
"checked": true
}
]
},
"versionNum": 5,
"createdNewVersion": true,
"staledApprovals": 0
}
}
}
```
Next permitted action: Use this atomic result instead of replacing the full checklist.
**Example requests**
- “/semel check off the third QA item on the checkout brief”
- “/semel mark the login QA check as done”
Errors: `PROJECT_ACCESS_DENIED`, `BRIEF_VERSION_CONFLICT`.
Related operations: `brief_update`, `brief_get_full`.
---
### brief_collection_list
Page through one durable brief collection (versions, decisionHistory, proposals, …) by keyset cursor. Use to walk a collection beyond the first page that brief_get_full returns.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
- `collection` — "versions" | "decisionHistory" | "findings" | "proposals" | "approvals" | "comments" | "artifacts" | "workOrders" | "reviewSessions" | "shares"; required. Durable collection to page within this brief. Use one of the advertised collection keys; the result contains only that collection.
- `cursor` — string; optional; minimum length 1. Opaque keyset cursor returned as nextCursor by the preceding page for this same brief and collection. Omit to read the first page.
- `limit` — integer; optional; minimum 1; maximum 200. Maximum records to return, as an integer from 1 through 200. Omit to use the server default.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
},
"collection": {
"type": "string",
"enum": [
"versions",
"decisionHistory",
"findings",
"proposals",
"approvals",
"comments",
"artifacts",
"workOrders",
"reviewSessions",
"shares"
],
"description": "Durable collection to page within this brief. Use one of the advertised collection keys; the result contains only that collection."
},
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque keyset cursor returned as nextCursor by the preceding page for this same brief and collection. Omit to read the first page."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Maximum records to return, as an integer from 1 through 200. Omit to use the server default."
}
},
"required": [
"briefId",
"collection"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"collection": "decisionHistory",
"limit": 50
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"collection": "decisionHistory",
"limit": 50
}
```
**Returns**
- `collection` — "versions" | "decisionHistory" | "findings" | "proposals" | "approvals" | "comments" | "artifacts" | "workOrders" | "reviewSessions" | "shares"; required. Named durable brief collection to page; use one of the documented enum values. Allowed values: "versions", "decisionHistory", "findings", "proposals", "approvals", "comments", "artifacts", "workOrders", "reviewSessions", "shares".
- `items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `items[]` — object; required.
- `items[]{key}` — JSON value; optional.
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"collection": {
"type": "string",
"enum": [
"versions",
"decisionHistory",
"findings",
"proposals",
"approvals",
"comments",
"artifacts",
"workOrders",
"reviewSessions",
"shares"
],
"description": "Named durable brief collection to page; use one of the documented enum values. Allowed values: \"versions\", \"decisionHistory\", \"findings\", \"proposals\", \"approvals\", \"comments\", \"artifacts\", \"workOrders\", \"reviewSessions\", \"shares\"."
},
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": {}
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"collection",
"items",
"nextCursor"
],
"additionalProperties": false
}
```
**Example structured result (collection-page)**
```json
{
"collection": "decisionHistory",
"items": [],
"nextCursor": null
}
```
Bindings: nextCursor from structuredContent.nextCursor.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"collection\":\"decisionHistory\",\"items\":[],\"nextCursor\":null}"
}
],
"structuredContent": {
"collection": "decisionHistory",
"items": [],
"nextCursor": null
}
}
```
Next permitted action: Repeat with the returned cursor until nextCursor is null.
**Example requests**
- “/semel list the version history for this brief”
- “/semel show the decision history of the checkout brief”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `brief_list`, `brief_get_full`.
---
### brief_comment_resolve
Resolve one brief comment or finding by id. Already-resolved comments return their existing resolution; this operation never reopens a comment.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
- `commentId` — string; required; minimum length 1. Identifier of the brief comment to resolve.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
},
"commentId": {
"type": "string",
"minLength": 1,
"description": "Identifier of the brief comment to resolve."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"briefId",
"commentId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"commentId": "bcm_fixture_contract",
"idempotencyKey": "recipe-brief-comment-resolve-v1"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"commentId": "{{commentId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `comment` — object; required. The comment after resolution, carrying who resolved it, when, and through which channel.
- `comment.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `comment.briefId` — string; required. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary.
- `comment.sectionKey` — string; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result.
- `comment.anchor` — string | null; required. Optional structured location within a brief section for this comment; null means the comment applies to the section as a whole. A null value explicitly means no current value is available.
- `comment.text` — string; required. Human-authored or model-produced text for this typed record.
- `comment.authorId` — string; required. Semel user identifier for the comment or content author.
- `comment.authorEmail` — JSON value; optional. Display email of the comment author when the caller may read it; null or omitted otherwise.
- `comment.authorEmail (anyOf branch 1)` — string; optional; format email.
- `comment.authorEmail (anyOf branch 2)` — null; optional.
- `comment.resolvedAt` — string | null; required. RFC 3339 timestamp when the comment was resolved; null means unresolved. A null value explicitly means no current value is available.
- `comment.resolvedBy` — string | null; required. Semel user identifier that resolved the comment; absent until resolution. A null value explicitly means no current value is available.
- `comment.channel` — "web" | "mcp"; optional. Typed delivery or answer channel recorded as provenance. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: "web", "mcp".
- `comment.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `comment.updatedAt` — string; required. RFC 3339 timestamp when this record was last updated.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"comment": {
"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."
},
"briefId": {
"type": "string",
"description": "Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary."
},
"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."
},
"authorEmail": {
"anyOf": [
{
"type": "string",
"format": "email"
},
{
"type": "null"
}
],
"description": "Display email of the comment author when the caller may read it; null or omitted otherwise."
},
"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."
},
"channel": {
"type": "string",
"enum": [
"web",
"mcp"
],
"description": "Typed delivery or answer channel recorded as provenance. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: \"web\", \"mcp\"."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
},
"updatedAt": {
"type": "string",
"description": "RFC 3339 timestamp when this record was last updated."
}
},
"required": [
"id",
"briefId",
"sectionKey",
"anchor",
"text",
"authorId",
"resolvedAt",
"resolvedBy",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "The comment after resolution, carrying who resolved it, when, and through which channel."
}
},
"required": [
"comment"
],
"additionalProperties": false
}
```
**Example structured result (comment-resolved)**
```json
{
"comment": {
"id": "bcm_fixture_contract",
"briefId": "brf_fixture_checkout",
"sectionKey": "example",
"anchor": "example",
"text": "example",
"authorId": "example",
"resolvedAt": "2026-09-07T16:00:00.000Z",
"resolvedBy": "usr_fixture_owner",
"createdAt": "example",
"updatedAt": "example",
"channel": "mcp"
}
}
```
Bindings: commentResolvedAt from structuredContent.comment.resolvedAt.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"comment\":{\"id\":\"bcm_fixture_contract\",\"briefId\":\"brf_fixture_checkout\",\"sectionKey\":\"example\",\"anchor\":\"example\",\"text\":\"example\",\"authorId\":\"example\",\"resolvedAt\":\"2026-09-07T16:00:00.000Z\",\"resolvedBy\":\"usr_fixture_owner\",\"createdAt\":\"example\",\"updatedAt\":\"example\",\"channel\":\"mcp\"}}"
}
],
"structuredContent": {
"comment": {
"id": "bcm_fixture_contract",
"briefId": "brf_fixture_checkout",
"sectionKey": "example",
"anchor": "example",
"text": "example",
"authorId": "example",
"resolvedAt": "2026-09-07T16:00:00.000Z",
"resolvedBy": "usr_fixture_owner",
"createdAt": "example",
"updatedAt": "example",
"channel": "mcp"
}
}
}
```
Next permitted action: Report the resolution; an already-resolved comment returns its original resolver and channel.
**Example requests**
- “/semel resolve the addressed comment on the checkout brief”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `brief_get_full`, `brief_update`.
---
### brief_create
Create a new brief inside a project — its title and first contract version — as the starting artifact for an effort's requirements. Use once the project exists to begin capturing what will be built.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `title` — string; required; minimum length 1; maximum length 500. Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
- `content` — object; optional. Complete replacement brief document for agent writes, limited to 262144 serialized bytes. Known sections use the canonical nested shapes; unknown metadata and _draft remain round-trippable.
- `content.goal` — string; optional; maximum length 4000. Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.userPersonaContext` — string; optional; maximum length 4000. User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.customerFacingLaunchMessage` — string; optional; maximum length 4000. Copy-ready end-user launch message stating the capability, value, and one concrete example. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.scope` — string; optional; maximum length 4000. Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.outOfScope` — string; optional; maximum length 4000. Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.requirements` — array; optional; maximum items 50. Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.requirements[]` — string; required; minimum length 1; maximum length 1000.
- `content.edgeCases` — array; optional; maximum items 50. Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.edgeCases[]` — string; required; minimum length 1; maximum length 1000.
- `content.acceptanceCriteria` — array; optional; maximum items 50. Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.acceptanceCriteria[]` — object; required.
- `content.acceptanceCriteria[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.acceptanceCriteria[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.acceptanceCriteria[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.acceptanceCriteria[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.acceptanceCriteria[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `content.acceptanceCriteria[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `content.rolesPermissions` — array; optional; maximum items 50. Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.rolesPermissions[]` — string; required; minimum length 1; maximum length 1000.
- `content.states` — array; optional; maximum items 50. User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.states[]` — string; required; minimum length 1; maximum length 1000.
- `content.productSolution` — string; optional; maximum length 4000. Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.technicalSolution` — string; optional; maximum length 4000. Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.dataModelImplications` — string; optional; maximum length 4000. Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.architectureAssumptions` — string; optional; maximum length 4000. Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.design` — string; optional; maximum length 4000. Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.testingQaChecklist` — array; optional; maximum items 50. Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testingQaChecklist[]` — object; required.
- `content.testingQaChecklist[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.testingQaChecklist[].checked` — boolean; required. Whether this QA checklist item is currently complete.
- `content.testingQaChecklist[].addedBy` — string; optional; maximum length 200. Actor label that added the QA item; omission means legacy or unavailable attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.testingQaChecklist[].checkedBy` — string; optional; maximum length 200. Actor label that last checked the item; omission means it has no check attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.testingQaChecklist[].checkedAt` — string; optional; format date-time. RFC 3339 timestamp when the item was checked; omission means it is unchecked or legacy data. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string.
- `content.testPlanUnit` — array; optional; maximum items 50. Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanUnit[]` — string; required; minimum length 1; maximum length 1000.
- `content.testPlanIntegration` — array; optional; maximum items 50. Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanIntegration[]` — string; required; minimum length 1; maximum length 1000.
- `content.testPlanUiUx` — array; optional; maximum items 50. Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanUiUx[]` — string; required; minimum length 1; maximum length 1000.
- `content.openQuestions` — array; optional; maximum items 50. Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.openQuestions[]` — string; required; minimum length 1; maximum length 1000.
- `content.generatedTickets` — array; optional; maximum items 50. Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.generatedTickets[]` — object; required.
- `content.generatedTickets[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.generatedTickets[].title` — string; required; minimum length 1; maximum length 500. Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
- `content.generatedTickets[].description` — JSON value; required. Human-readable explanatory text; null or omission means no description was supplied. A null value explicitly means no current value is available. Maximum accepted length or value is 10000.
- `content.generatedTickets[].description (anyOf branch 1)` — string; required; maximum length 10000.
- `content.generatedTickets[].description (anyOf branch 2)` — null; required.
- `content.generatedTickets[].boundCriteria` — array; required; maximum items 50. Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items.
- `content.generatedTickets[].boundCriteria[]` — string; required; minimum length 1; maximum length 200.
- `content.generatedTickets[].boundRequirements` — array; optional; maximum items 50. Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.generatedTickets[].boundRequirements[]` — string; required; minimum length 1; maximum length 200.
- `content.requiredEvidence` — array; optional; maximum items 50. Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.requiredEvidence[]` — object; required.
- `content.requiredEvidence[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.requiredEvidence[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.requiredEvidence[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.requiredEvidence[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.requiredEvidence[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `content.requiredEvidence[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `content.decisions` — array; optional; maximum items 50. Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.decisions[]` — object; required.
- `content.decisions[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.decisions[].source` — string; optional; maximum length 1000. Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000.
- `content.decisions[].stated` — boolean; optional. Whether the decision was explicitly stated rather than inferred; omission means unknown legacy provenance. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.sourceArtifactLinks` — array; optional; maximum items 50. Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.sourceArtifactLinks[]` — object; required.
- `content.sourceArtifactLinks[].label` — string; required; minimum length 1; maximum length 1000. Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive.
- `content.sourceArtifactLinks[].kind` — string; optional; maximum length 200. Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.sourceArtifactLinks[].read` — boolean; optional. Whether the referenced source artifact was read when the brief snapshot was produced. Omit the field when it does not apply; omission is distinct from an empty value.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive."
},
"content": {
"type": "object",
"properties": {
"goal": {
"type": "string",
"maxLength": 4000,
"description": "Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"userPersonaContext": {
"type": "string",
"maxLength": 4000,
"description": "User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"customerFacingLaunchMessage": {
"type": "string",
"maxLength": 4000,
"description": "Copy-ready end-user launch message stating the capability, value, and one concrete example. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"scope": {
"type": "string",
"maxLength": 4000,
"description": "Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"outOfScope": {
"type": "string",
"maxLength": 4000,
"description": "Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"requirements": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"edgeCases": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"acceptanceCriteria": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"implementation": {
"type": "boolean",
"description": "Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value."
},
"manualEvidence": {
"type": "object",
"properties": {
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive."
},
"evidencePath": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive."
}
},
"required": [
"rationale",
"evidencePath"
],
"additionalProperties": false,
"description": "Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"id",
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"rolesPermissions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"states": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"productSolution": {
"type": "string",
"maxLength": 4000,
"description": "Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"technicalSolution": {
"type": "string",
"maxLength": 4000,
"description": "Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"dataModelImplications": {
"type": "string",
"maxLength": 4000,
"description": "Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"architectureAssumptions": {
"type": "string",
"maxLength": 4000,
"description": "Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"design": {
"type": "string",
"maxLength": 4000,
"description": "Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"testingQaChecklist": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"checked": {
"type": "boolean",
"description": "Whether this QA checklist item is currently complete."
},
"addedBy": {
"type": "string",
"maxLength": 200,
"description": "Actor label that added the QA item; omission means legacy or unavailable attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"checkedBy": {
"type": "string",
"maxLength": 200,
"description": "Actor label that last checked the item; omission means it has no check attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"checkedAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp when the item was checked; omission means it is unchecked or legacy data. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string."
}
},
"required": [
"text",
"checked"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanUnit": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanIntegration": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanUiUx": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"openQuestions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"generatedTickets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive."
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 10000
},
{
"type": "null"
}
],
"description": "Human-readable explanatory text; null or omission means no description was supplied. A null value explicitly means no current value is available. Maximum accepted length or value is 10000."
},
"boundCriteria": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
},
"maxItems": 50,
"description": "Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items."
},
"boundRequirements": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
},
"maxItems": 50,
"description": "Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"required": [
"id",
"title",
"description",
"boundCriteria"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"requiredEvidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"implementation": {
"type": "boolean",
"description": "Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value."
},
"manualEvidence": {
"type": "object",
"properties": {
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive."
},
"evidencePath": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive."
}
},
"required": [
"rationale",
"evidencePath"
],
"additionalProperties": false,
"description": "Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"id",
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"decisions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"source": {
"type": "string",
"maxLength": 1000,
"description": "Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000."
},
"stated": {
"type": "boolean",
"description": "Whether the decision was explicitly stated rather than inferred; omission means unknown legacy provenance. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"sourceArtifactLinks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive."
},
"kind": {
"type": "string",
"maxLength": 200,
"description": "Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"read": {
"type": "boolean",
"description": "Whether the referenced source artifact was read when the brief snapshot was produced. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"label"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"additionalProperties": true,
"description": "Complete replacement brief document for agent writes, limited to 262144 serialized bytes. Known sections use the canonical nested shapes; unknown metadata and _draft remain round-trippable."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"projectId",
"title",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"idempotencyKey": "recipe-brief-create-v1"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"title": "{{briefTitle}}",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `brief` — object; required. Current brief record returned by the operation.
- `brief.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `brief.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `brief.title` — string; required. Human-readable title displayed in Semel.
- `brief.state` — "drafting" | "in_review" | "baselined" | "in_development" | "checked" | "superseded" | "closed"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "drafting", "in_review", "baselined", "in_development", "checked", "superseded", "closed".
- `brief.currentVersionHash` — string | null; required. Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available.
- `brief.content` — object; required. Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
- `brief.content{key}` — JSON value; optional.
- `brief.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `brief.delivery` — object; optional. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value.
- `brief.delivery.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `brief.delivery.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `brief.delivery.deliveryStatus (anyOf branch 2)` — null; required.
- `brief.delivery.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `brief.delivery.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `brief.delivery.changedAt (anyOf branch 1)` — string; required; format date-time.
- `brief.delivery.changedAt (anyOf branch 2)` — null; required.
- `brief.delivery.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `brief.delivery.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `brief.delivery.source (anyOf branch 1)` — "web" | "mcp"; required.
- `brief.delivery.source (anyOf branch 2)` — null; required.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"brief": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"state": {
"type": "string",
"enum": [
"drafting",
"in_review",
"baselined",
"in_development",
"checked",
"superseded",
"closed"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"drafting\", \"in_review\", \"baselined\", \"in_development\", \"checked\", \"superseded\", \"closed\"."
},
"currentVersionHash": {
"type": [
"string",
"null"
],
"description": "Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available."
},
"content": {
"type": "object",
"additionalProperties": {},
"description": "Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
},
"delivery": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"id",
"projectId",
"title",
"state",
"currentVersionHash",
"content",
"versionNum"
],
"additionalProperties": false,
"description": "Current brief record returned by the operation."
}
},
"required": [
"brief"
],
"additionalProperties": false
}
```
**Example structured result (brief-created)**
```json
{
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"versionNum": 1
}
}
```
Bindings: briefId from structuredContent.brief.id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"brief\":{\"id\":\"brf_fixture_checkout\",\"projectId\":\"prj_fixture_checkout\",\"title\":\"Retry-safe checkout\",\"state\":\"drafting\",\"currentVersionHash\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"content\":{\"goal\":\"Prevent duplicate charges when checkout retries.\",\"requirements\":[\"Reuse one payment intent for retried submissions.\"],\"acceptanceCriteria\":[{\"id\":\"AC-01\",\"text\":\"A retried request returns the original successful result.\"}],\"sourceArtifactLinks\":[{\"label\":\"Linear ENG-42\",\"kind\":\"linear\"}]},\"versionNum\":1}}"
}
],
"structuredContent": {
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"versionNum": 1
}
}
}
```
Next permitted action: Load the complete persisted aggregate by the returned brief id.
**Example requests**
- “/semel create a brief for the checkout flow”
- “/semel start a new brief in the billing project”
Errors: `PROJECT_ACCESS_DENIED`, `PROJECT_ALREADY_HAS_BRIEF`.
Related operations: `brief_update`, `brief_get_full`, `project_create`.
---
### brief_delivery_status_set
Set or correct an explicit brief delivery status. This never changes the brief contract or review state.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `deliveryStatus` — JSON value; required. Desired explicit delivery state; null deliberately clears the marker and does not alter review, approval, or contract state.
- `deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `deliveryStatus (anyOf branch 2)` — null; required.
- `ifDeliveryStatusVersion` — integer; required; minimum 0. Required optimistic-concurrency precondition copied from the latest deliveryStatusVersion returned by Semel.
- `correctionReason` — string; optional; minimum length 1; maximum length 500. Trimmed audit reason required for backward transitions and clears; tabs and line breaks are allowed but other control characters are rejected.
- `briefId` — string; required; minimum length 1. Brief identifier whose explicit delivery status should be changed.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Desired explicit delivery state; null deliberately clears the marker and does not alter review, approval, or contract state."
},
"ifDeliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Required optimistic-concurrency precondition copied from the latest deliveryStatusVersion returned by Semel."
},
"correctionReason": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Trimmed audit reason required for backward transitions and clears; tabs and line breaks are allowed but other control characters are rejected."
},
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier whose explicit delivery status should be changed."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"deliveryStatus",
"ifDeliveryStatusVersion",
"briefId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"deliveryStatus": "shipped",
"ifDeliveryStatusVersion": 0,
"idempotencyKey": "recipe-brief-delivery-status-set-v1"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"deliveryStatus": "{{briefDeliveryStatus}}",
"ifDeliveryStatusVersion": 0,
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `brief` — object; required. Current brief record returned by the operation.
- `brief.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `brief.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `brief.title` — string; required. Human-readable title displayed in Semel.
- `brief.state` — "drafting" | "in_review" | "baselined" | "in_development" | "checked" | "superseded" | "closed"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "drafting", "in_review", "baselined", "in_development", "checked", "superseded", "closed".
- `brief.currentVersionHash` — string | null; required. Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available.
- `brief.content` — object; required. Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
- `brief.content{key}` — JSON value; optional.
- `brief.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `brief.delivery` — object; optional. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value.
- `brief.delivery.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `brief.delivery.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `brief.delivery.deliveryStatus (anyOf branch 2)` — null; required.
- `brief.delivery.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `brief.delivery.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `brief.delivery.changedAt (anyOf branch 1)` — string; required; format date-time.
- `brief.delivery.changedAt (anyOf branch 2)` — null; required.
- `brief.delivery.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `brief.delivery.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `brief.delivery.source (anyOf branch 1)` — "web" | "mcp"; required.
- `brief.delivery.source (anyOf branch 2)` — null; required.
- `delivery` — object; required. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state.
- `delivery.projection` — object; required. Authoritative delivery projection after the operation, including an exact no-op response.
- `delivery.projection.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `delivery.projection.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `delivery.projection.deliveryStatus (anyOf branch 2)` — null; required.
- `delivery.projection.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `delivery.projection.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `delivery.projection.changedAt (anyOf branch 1)` — string; required; format date-time.
- `delivery.projection.changedAt (anyOf branch 2)` — null; required.
- `delivery.projection.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `delivery.projection.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `delivery.projection.source (anyOf branch 1)` — "web" | "mcp"; required.
- `delivery.projection.source (anyOf branch 2)` — null; required.
- `delivery.changed` — boolean; required. True when projection and audit event were committed; false for an exact event-free no-op.
- `delivery.eventId` — string | null; required. Immutable delivery-status audit event identifier for a committed change; null for an exact no-op.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"brief": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"state": {
"type": "string",
"enum": [
"drafting",
"in_review",
"baselined",
"in_development",
"checked",
"superseded",
"closed"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"drafting\", \"in_review\", \"baselined\", \"in_development\", \"checked\", \"superseded\", \"closed\"."
},
"currentVersionHash": {
"type": [
"string",
"null"
],
"description": "Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available."
},
"content": {
"type": "object",
"additionalProperties": {},
"description": "Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
},
"delivery": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"id",
"projectId",
"title",
"state",
"currentVersionHash",
"content",
"versionNum"
],
"additionalProperties": false,
"description": "Current brief record returned by the operation."
},
"delivery": {
"type": "object",
"properties": {
"projection": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Authoritative delivery projection after the operation, including an exact no-op response."
},
"changed": {
"type": "boolean",
"description": "True when projection and audit event were committed; false for an exact event-free no-op."
},
"eventId": {
"type": [
"string",
"null"
],
"description": "Immutable delivery-status audit event identifier for a committed change; null for an exact no-op."
}
},
"required": [
"projection",
"changed",
"eventId"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state."
}
},
"required": [
"brief",
"delivery"
],
"additionalProperties": false
}
```
**Example structured result (brief-delivery-status-set)**
```json
{
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {},
"versionNum": 0,
"delivery": {
"deliveryStatus": "shipped",
"deliveryStatusVersion": 1,
"changedAt": "2026-09-07T16:00:00.000Z",
"changedById": "example",
"source": "mcp"
}
},
"delivery": {
"projection": {
"deliveryStatus": "shipped",
"deliveryStatusVersion": 1,
"changedAt": "2026-09-07T16:00:00.000Z",
"changedById": "example",
"source": "mcp"
},
"changed": true,
"eventId": "example"
}
}
```
Bindings: briefDeliveryStatus from structuredContent.delivery.projection.deliveryStatus.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"brief\":{\"id\":\"brf_fixture_checkout\",\"projectId\":\"prj_fixture_checkout\",\"title\":\"Retry-safe checkout\",\"state\":\"drafting\",\"currentVersionHash\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"content\":{},\"versionNum\":0,\"delivery\":{\"deliveryStatus\":\"shipped\",\"deliveryStatusVersion\":1,\"changedAt\":\"2026-09-07T16:00:00.000Z\",\"changedById\":\"example\",\"source\":\"mcp\"}},\"delivery\":{\"projection\":{\"deliveryStatus\":\"shipped\",\"deliveryStatusVersion\":1,\"changedAt\":\"2026-09-07T16:00:00.000Z\",\"changedById\":\"example\",\"source\":\"mcp\"},\"changed\":true,\"eventId\":\"example\"}}"
}
],
"structuredContent": {
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {},
"versionNum": 0,
"delivery": {
"deliveryStatus": "shipped",
"deliveryStatusVersion": 1,
"changedAt": "2026-09-07T16:00:00.000Z",
"changedById": "example",
"source": "mcp"
}
},
"delivery": {
"projection": {
"deliveryStatus": "shipped",
"deliveryStatusVersion": 1,
"changedAt": "2026-09-07T16:00:00.000Z",
"changedById": "example",
"source": "mcp"
},
"changed": true,
"eventId": "example"
}
}
}
```
Next permitted action: Keep delivery status separate from the complete-content replacement and its contract version.
**Example requests**
- “/semel mark brief brf_… as deployed”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `brief_get_full`, `project_delivery_status_set`.
---
### brief_export_markdown
DEPRECATED compatibility export that renders a brief to Markdown only. It is not a verified implementation handoff; use brief_export_package instead.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
}
},
"required": [
"briefId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}"
}
```
**Returns**
- `filename` — string; required. Safe suggested filename for the downloaded export.
- `resource` — JSON value; required. Optional MCP resource descriptor for the Markdown export; null means the export is available only in the inline payload. A null value explicitly means no current value is available.
- `resource (anyOf branch 1)` — object; required.
- `resource (anyOf branch 1).uri` — string; required. Absolute or same-origin URI for the referenced resource or required operator action.
- `resource (anyOf branch 1).name` — string; required. Human-readable name displayed in Semel.
- `resource (anyOf branch 1).mimeType` — string; required. Internet media type of the artifact or exported resource; null means the producer did not record one.
- `resource (anyOf branch 2)` — null; required.
- `downloadUrl` — string | null; required. Short-lived or public download URL returned by Semel; do not construct or persist it as an identifier. A null value explicitly means no current value is available.
- `markdown` — string | null; required. Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters. A null value explicitly means no current value is available.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"filename": {
"type": "string",
"description": "Safe suggested filename for the downloaded export."
},
"resource": {
"anyOf": [
{
"type": "object",
"properties": {
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"mimeType": {
"type": "string",
"description": "Internet media type of the artifact or exported resource; null means the producer did not record one."
}
},
"required": [
"uri",
"name",
"mimeType"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Optional MCP resource descriptor for the Markdown export; null means the export is available only in the inline payload. A null value explicitly means no current value is available."
},
"downloadUrl": {
"type": [
"string",
"null"
],
"description": "Short-lived or public download URL returned by Semel; do not construct or persist it as an identifier. A null value explicitly means no current value is available."
},
"markdown": {
"type": [
"string",
"null"
],
"description": "Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters. A null value explicitly means no current value is available."
}
},
"required": [
"filename",
"resource",
"downloadUrl",
"markdown"
],
"additionalProperties": false
}
```
**Example structured result (legacy-markdown)**
```json
{
"filename": "retry-safe-checkout.zip",
"resource": {
"uri": "https://mcp.semel.ai/brief-exports/brf_fixture_checkout.md",
"name": "retry-safe-checkout.md",
"mimeType": "text/markdown"
},
"downloadUrl": "example",
"markdown": "example"
}
```
Bindings: legacyResource from structuredContent.resource.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"filename\":\"retry-safe-checkout.zip\",\"resource\":{\"uri\":\"https://mcp.semel.ai/brief-exports/brf_fixture_checkout.md\",\"name\":\"retry-safe-checkout.md\",\"mimeType\":\"text/markdown\"},\"downloadUrl\":\"example\",\"markdown\":\"example\"}"
},
{
"type": "resource_link",
"uri": "https://mcp.semel.ai/brief-exports/brf_fixture_checkout.md",
"name": "retry-safe-checkout.md",
"mimeType": "text/markdown"
}
],
"structuredContent": {
"filename": "retry-safe-checkout.zip",
"resource": {
"uri": "https://mcp.semel.ai/brief-exports/brf_fixture_checkout.md",
"name": "retry-safe-checkout.md",
"mimeType": "text/markdown"
},
"downloadUrl": "example",
"markdown": "example"
}
}
```
Next permitted action: Label the result deprecated and do not treat it as a verified handoff.
**Example requests**
- “/semel export this brief as markdown”
- “/semel give me the markdown for the checkout brief”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `brief_export_package`, `brief_get_full`.
---
### brief_export_package
Create a verified, immutable ZIP implementation handoff for a brief — the canonical R9 export. Use to hand a completed brief off to implementation; if it errors, no usable package exists and you should not fall back to the deprecated Markdown export.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"briefId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"idempotencyKey": "recipe-brief-export-package-v1"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `exportId` — string; required; minimum length 1. Opaque identifier assigned to this deterministic export package; use returned download metadata rather than constructing it. Minimum accepted length or value is 1.
- `status` — constant "ready"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "ready".
- `filename` — string; required; minimum length 1. Safe suggested filename for the downloaded export. Minimum accepted length or value is 1.
- `downloadUrl` — string; required; minimum length 1. Short-lived or public download URL returned by Semel; do not construct or persist it as an identifier. Minimum accepted length or value is 1.
- `manifestSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the export manifest.
- `implementationReady` — constant true; required. Whether the exported brief satisfies Semel implementation-readiness checks. This branch always uses true.
- `expiresAt` — string; required; format date-time. RFC 3339 expiration timestamp. Use an RFC 3339 date-time string.
- `snapshotId` — string; required; minimum length 1. Immutable export snapshot identifier used to reproduce the exported brief state. Minimum accepted length or value is 1.
- `contractVersionId` — string; required; minimum length 1. Immutable brief contract-version identifier resolved by Semel. Minimum accepted length or value is 1.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"exportId": {
"type": "string",
"minLength": 1,
"description": "Opaque identifier assigned to this deterministic export package; use returned download metadata rather than constructing it. Minimum accepted length or value is 1."
},
"status": {
"type": "string",
"const": "ready",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"ready\"."
},
"filename": {
"type": "string",
"minLength": 1,
"description": "Safe suggested filename for the downloaded export. Minimum accepted length or value is 1."
},
"downloadUrl": {
"type": "string",
"minLength": 1,
"description": "Short-lived or public download URL returned by Semel; do not construct or persist it as an identifier. Minimum accepted length or value is 1."
},
"manifestSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest of the export manifest."
},
"implementationReady": {
"type": "boolean",
"const": true,
"description": "Whether the exported brief satisfies Semel implementation-readiness checks. This branch always uses true."
},
"expiresAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 expiration timestamp. Use an RFC 3339 date-time string."
},
"snapshotId": {
"type": "string",
"minLength": 1,
"description": "Immutable export snapshot identifier used to reproduce the exported brief state. Minimum accepted length or value is 1."
},
"contractVersionId": {
"type": "string",
"minLength": 1,
"description": "Immutable brief contract-version identifier resolved by Semel. Minimum accepted length or value is 1."
}
},
"required": [
"exportId",
"status",
"filename",
"downloadUrl",
"manifestSha256",
"implementationReady",
"expiresAt",
"snapshotId",
"contractVersionId"
],
"additionalProperties": false
}
```
**Example structured result (ready)**
```json
{
"exportId": "example",
"status": "ready",
"filename": "retry-safe-checkout.zip",
"downloadUrl": "https://mcp.semel.ai/brief-exports/exp_fixture_checkout",
"manifestSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"implementationReady": true,
"expiresAt": "2026-09-07T16:00:00.000Z",
"snapshotId": "example",
"contractVersionId": "example"
}
```
Bindings: downloadUrl from structuredContent.downloadUrl.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"exportId\":\"example\",\"status\":\"ready\",\"filename\":\"retry-safe-checkout.zip\",\"downloadUrl\":\"https://mcp.semel.ai/mcp/brief-exports/example/download\",\"manifestSha256\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"implementationReady\":true,\"expiresAt\":\"2026-09-07T16:00:00.000Z\",\"snapshotId\":\"example\",\"contractVersionId\":\"example\"}"
},
{
"type": "resource_link",
"uri": "https://mcp.semel.ai/mcp/brief-exports/example/download",
"name": "retry-safe-checkout.zip",
"mimeType": "application/zip"
}
],
"structuredContent": {
"exportId": "example",
"status": "ready",
"filename": "retry-safe-checkout.zip",
"downloadUrl": "https://mcp.semel.ai/mcp/brief-exports/example/download",
"manifestSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"implementationReady": true,
"expiresAt": "2026-09-07T16:00:00.000Z",
"snapshotId": "example",
"contractVersionId": "example"
}
}
```
Next permitted action: Fetch the bearer-authenticated resource before expiresAt and verify the manifest/hash.
**Example requests**
- “/semel export the checkout brief as an implementation package”
- “/semel build the handoff package for this brief”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `brief_get_full`, `brief_export_markdown`.
---
### brief_get_full
Read the complete brief aggregate in one call — the current content plus the first page of every durable collection (versions, decision history, proposals, and more). Use to load everything about a brief before acting on it.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
}
},
"required": [
"briefId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}"
}
```
**Returns**
- `brief` — object; required. Current brief record returned by the operation.
- `brief.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `brief.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `brief.title` — string; required. Human-readable title displayed in Semel.
- `brief.state` — "drafting" | "in_review" | "baselined" | "in_development" | "checked" | "superseded" | "closed"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "drafting", "in_review", "baselined", "in_development", "checked", "superseded", "closed".
- `brief.currentVersionHash` — string | null; required. Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available.
- `brief.content` — object; required. Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
- `brief.content{key}` — JSON value; optional.
- `brief.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `brief.delivery` — object; optional. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value.
- `brief.delivery.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `brief.delivery.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `brief.delivery.deliveryStatus (anyOf branch 2)` — null; required.
- `brief.delivery.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `brief.delivery.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `brief.delivery.changedAt (anyOf branch 1)` — string; required; format date-time.
- `brief.delivery.changedAt (anyOf branch 2)` — null; required.
- `brief.delivery.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `brief.delivery.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `brief.delivery.source (anyOf branch 1)` — "web" | "mcp"; required.
- `brief.delivery.source (anyOf branch 2)` — null; required.
- `collections` — object; required. First page of each durable collection associated with the brief.
- `collections.versions` — object; required. Immutable brief version summaries, newest first.
- `collections.versions.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.versions.items[]` — object; required.
- `collections.versions.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.versions.items[].versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `collections.versions.items[].contentHash` — string; required. Hash of the immutable brief content snapshot.
- `collections.versions.items[].aiReviewerRole` — string | null; required. Reviewer role that authored this immutable brief version; null means a human or legacy source authored it. A null value explicitly means no current value is available.
- `collections.versions.items[].aiReviewerIdentity` — object; optional. Server-stamped identity of the reviewer occurrence that authored this immutable brief version. Omit the field when it does not apply; omission is distinct from an empty value.
- `collections.versions.items[].aiReviewerIdentity.schemaVersion` — constant 2; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2.
- `collections.versions.items[].aiReviewerIdentity.occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `collections.versions.items[].aiReviewerIdentity.reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `collections.versions.items[].aiReviewerIdentity.reviewerRef (anyOf branch 1)` — object; required.
- `collections.versions.items[].aiReviewerIdentity.reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `collections.versions.items[].aiReviewerIdentity.reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.versions.items[].aiReviewerIdentity.reviewerRef (anyOf branch 2)` — object; required.
- `collections.versions.items[].aiReviewerIdentity.reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `collections.versions.items[].aiReviewerIdentity.reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `collections.versions.items[].aiReviewerIdentity.reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `collections.versions.items[].aiReviewerIdentity.label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `collections.versions.items[].aiReviewerIdentity.legacyRole` — JSON value; required. Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.versions.items[].aiReviewerIdentity.legacyRole (anyOf branch 1)` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.versions.items[].aiReviewerIdentity.legacyRole (anyOf branch 2)` — null; required.
- `collections.versions.items[].sourceRunId` — string | null; required. Review-run identifier that authored this brief version; null means the version was not created by a reviewer run. A null value explicitly means no current value is available.
- `collections.versions.items[].isRevert` — boolean; required. Whether this immutable version was created by reverting to prior content.
- `collections.versions.items[].createdById` — string; required. Semel user identifier recorded as the initiating creator.
- `collections.versions.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.versions.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.decisionHistory` — object; required. Durable question and decision history for the brief.
- `collections.decisionHistory.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.decisionHistory.items[]` — object; required.
- `collections.decisionHistory.items[].kind` — "canonical_decision" | "reviewer_question"; required. Discriminator identifying the typed variant represented by this object. Allowed values: "canonical_decision", "reviewer_question".
- `collections.decisionHistory.items[].sourceId` — string; required. Opaque source identifier returned by project_context_sources_list; pass it back unchanged.
- `collections.decisionHistory.items[].text` — string; required. Human-authored or model-produced text for this typed record.
- `collections.decisionHistory.items[].answer` — string | null; required. Durable answer text recorded for this decision-history entry; null means the question had no accepted answer at this snapshot. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].status` — string | null; required. Current typed status; the schema enum or union branch lists every allowed value. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].reviewerRole` — string | null; required. Reviewer role attributed to this question, finding, or version. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].reviewerIdentity` — object; optional. Server-stamped reviewer occurrence identity, or the bounded occurrence echo accepted from a schema-2 result. Omit the field when it does not apply; omission is distinct from an empty value.
- `collections.decisionHistory.items[].reviewerIdentity.schemaVersion` — constant 2; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2.
- `collections.decisionHistory.items[].reviewerIdentity.occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `collections.decisionHistory.items[].reviewerIdentity.reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `collections.decisionHistory.items[].reviewerIdentity.reviewerRef (anyOf branch 1)` — object; required.
- `collections.decisionHistory.items[].reviewerIdentity.reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `collections.decisionHistory.items[].reviewerIdentity.reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.decisionHistory.items[].reviewerIdentity.reviewerRef (anyOf branch 2)` — object; required.
- `collections.decisionHistory.items[].reviewerIdentity.reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `collections.decisionHistory.items[].reviewerIdentity.reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `collections.decisionHistory.items[].reviewerIdentity.reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `collections.decisionHistory.items[].reviewerIdentity.label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `collections.decisionHistory.items[].reviewerIdentity.legacyRole` — JSON value; required. Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.decisionHistory.items[].reviewerIdentity.legacyRole (anyOf branch 1)` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.decisionHistory.items[].reviewerIdentity.legacyRole (anyOf branch 2)` — null; required.
- `collections.decisionHistory.items[].section` — string | null; required. Canonical brief section key associated with the question, finding, proposal, or decision entry. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].iterationRound` — JSON value; required. One-based review iteration that produced this decision-history entry; null means legacy round data is unavailable. A null value explicitly means no current value is available. The value must be an integer.
- `collections.decisionHistory.items[].iterationRound (anyOf branch 1)` — integer; required.
- `collections.decisionHistory.items[].iterationRound (anyOf branch 2)` — null; required.
- `collections.decisionHistory.items[].sessionId` — string | null; required. Review-session identifier associated with this historical record; null means legacy provenance is unavailable. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].runId` — string | null; required. Review-run identifier returned by a review start, status, or cascade handoff result. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].actorUserId` — string | null; required. Accountable Semel user identifier recorded on the event. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].createdAt` — string | null; required. RFC 3339 timestamp assigned by Semel when this record was created. A null value explicitly means no current value is available.
- `collections.decisionHistory.items[].answeredAt` — string | null; required. RFC 3339 timestamp when the active answer was recorded. A null value explicitly means no current value is available.
- `collections.decisionHistory.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.findings` — object; required. Reviewer findings associated with the selected brief version.
- `collections.findings.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.findings.items[]` — object; required.
- `collections.findings.items[].section` — string; required. Canonical brief section key associated with the question, finding, proposal, or decision entry.
- `collections.findings.items[].note` — string; required. Reviewer-facing finding detail that explains the observed issue and the evidence-based change requested.
- `collections.findings.items[].severity` — "info" | "warn" | "block"; required. Finding impact level: info is advisory, warn requires attention, and block prevents approval or completion. Allowed values: "info", "warn", "block".
- `collections.findings.items[].citations` — array; optional. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `collections.findings.items[].citations[]` — JSON value; required.
- `collections.findings.items[].citations[] (anyOf branch 1)` — object; required.
- `collections.findings.items[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `collections.findings.items[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `collections.findings.items[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 1).briefId` — string; required. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary.
- `collections.findings.items[].citations[] (anyOf branch 1).contractVersionId` — string; required. Immutable brief contract-version identifier resolved by Semel.
- `collections.findings.items[].citations[] (anyOf branch 1).versionNum` — integer; optional. Monotonic brief contract version number assigned by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citations[] (anyOf branch 1).reviewers` — array; required; minimum items 1. Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
- `collections.findings.items[].citations[] (anyOf branch 1).reviewers[]` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].citations[] (anyOf branch 1).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `collections.findings.items[].citations[] (anyOf branch 2)` — object; required.
- `collections.findings.items[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `collections.findings.items[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 2).extractedTextHash` — string; required. Hash of the normalized text extracted from the cited artifact, used to bind the citation to exact processed content.
- `collections.findings.items[].citations[] (anyOf branch 2).reviewers` — array; required; minimum items 1. Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
- `collections.findings.items[].citations[] (anyOf branch 2).reviewers[]` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].citations[] (anyOf branch 2).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `collections.findings.items[].citations[] (anyOf branch 3)` — object; required.
- `collections.findings.items[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `collections.findings.items[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 3).evidenceManifestId` — string; required; minimum length 1. Immutable evidence-manifest identifier captured for the review run. Minimum accepted length or value is 1.
- `collections.findings.items[].citations[] (anyOf branch 3).evidenceManifestItemId` — string; required; minimum length 1. Identifier of the exact item inside the immutable evidence manifest. Minimum accepted length or value is 1.
- `collections.findings.items[].citations[] (anyOf branch 3).workspaceRepositoryId` — string; required; minimum length 1. Workspace-scoped connected repository identifier recorded in evidence provenance. Minimum accepted length or value is 1.
- `collections.findings.items[].citations[] (anyOf branch 3).revisionId` — string; required; minimum length 1. Immutable indexed repository revision identifier. Minimum accepted length or value is 1.
- `collections.findings.items[].citations[] (anyOf branch 3).commitSha` — string; required. Git commit SHA pinned by the evidence manifest.
- `collections.findings.items[].citations[] (anyOf branch 3).blobSha` — string; required. Git blob SHA for the cited file contents.
- `collections.findings.items[].citations[] (anyOf branch 3).path` — string; required; minimum length 1. Repository-relative source path; it never denotes an arbitrary local filesystem path. Minimum accepted length or value is 1.
- `collections.findings.items[].citations[] (anyOf branch 3).startLine` — integer; required. One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citations[] (anyOf branch 3).endLine` — integer; required. One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citations[] (anyOf branch 3).excerptSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the exact cited excerpt.
- `collections.findings.items[].citations[] (anyOf branch 3).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `collections.findings.items[].citations[] (anyOf branch 3).coverage` — object; required. Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence.
- `collections.findings.items[].citations[] (anyOf branch 3).coverage{key}` — JSON value; optional.
- `collections.findings.items[].citations[] (anyOf branch 3).reviewers` — array; required; minimum items 1. Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
- `collections.findings.items[].citations[] (anyOf branch 3).reviewers[]` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].citations[] (anyOf branch 3).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `collections.findings.items[].citations[] (anyOf branch 4)` — object; required.
- `collections.findings.items[].citations[] (anyOf branch 4).sourceType` — constant "local-worktree"; required. Discriminator identifying the evidence source variant. This branch always uses "local-worktree".
- `collections.findings.items[].citations[] (anyOf branch 4).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 4).repositoryId` — string; required; minimum length 1. Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
- `collections.findings.items[].citations[] (anyOf branch 4).headSha` — string; required. Git commit SHA of the local worktree HEAD at binding or citation time.
- `collections.findings.items[].citations[] (anyOf branch 4).fileSha` — JSON value; optional. Git blob SHA of the local working file computed with git hash-object; null when unavailable. 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.
- `collections.findings.items[].citations[] (anyOf branch 4).fileSha (anyOf branch 1)` — string; optional.
- `collections.findings.items[].citations[] (anyOf branch 4).fileSha (anyOf branch 2)` — null; optional.
- `collections.findings.items[].citations[] (anyOf branch 4).path` — string; required; minimum length 1; maximum length 4096. Repository-relative source path; it never denotes an arbitrary local filesystem path. Accepted length or value is 1 through 4096, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 4).startLine` — integer; required. One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citations[] (anyOf branch 4).endLine` — integer; required. One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citations[] (anyOf branch 4).excerptSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the exact cited excerpt.
- `collections.findings.items[].citations[] (anyOf branch 4).dirty` — boolean; required. Whether the local worktree had uncommitted changes at binding or citation time.
- `collections.findings.items[].citations[] (anyOf branch 4).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `collections.findings.items[].citations[] (anyOf branch 4).verification` — constant "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. This branch always uses "unverified".
- `collections.findings.items[].citations[] (anyOf branch 4).reviewers` — array; required; minimum items 1. Reviewer roles whose evidence processing verified or contributed this citation. An empty array explicitly means no matching items.
- `collections.findings.items[].citations[] (anyOf branch 4).reviewers[]` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].citationsV2` — array; optional. Schema-2 evidence citations carrying server-stamped reviewer occurrence attribution. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `collections.findings.items[].citationsV2[]` — JSON value; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 1)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `collections.findings.items[].citationsV2[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `collections.findings.items[].citationsV2[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).briefId` — string; required. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).contractVersionId` — string; required. Immutable brief contract-version identifier resolved by Semel.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).versionNum` — integer; optional. Monotonic brief contract version number assigned by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `collections.findings.items[].citationsV2[] (anyOf branch 1).identitySchemaVersion` — constant 2; required. Version of the reviewer identity attribution stamped on this citation record. This branch always uses 2.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities` — array; required; minimum items 1; maximum items 20. Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. An empty array explicitly means no matching items.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[]` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].schemaVersion` — constant 2; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].reviewerRef (anyOf branch 1)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].reviewerRef (anyOf branch 2)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].legacyRole` — JSON value; required. Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].legacyRole (anyOf branch 1)` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 1).reviewerIdentities[].legacyRole (anyOf branch 2)` — null; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 2)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `collections.findings.items[].citationsV2[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).extractedTextHash` — string; required. Hash of the normalized text extracted from the cited artifact, used to bind the citation to exact processed content.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `collections.findings.items[].citationsV2[] (anyOf branch 2).identitySchemaVersion` — constant 2; required. Version of the reviewer identity attribution stamped on this citation record. This branch always uses 2.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities` — array; required; minimum items 1; maximum items 20. Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. An empty array explicitly means no matching items.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[]` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].schemaVersion` — constant 2; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].reviewerRef (anyOf branch 1)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].reviewerRef (anyOf branch 2)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].legacyRole` — JSON value; required. Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].legacyRole (anyOf branch 1)` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 2).reviewerIdentities[].legacyRole (anyOf branch 2)` — null; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 3)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `collections.findings.items[].citationsV2[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).evidenceManifestId` — string; required; minimum length 1. Immutable evidence-manifest identifier captured for the review run. Minimum accepted length or value is 1.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).evidenceManifestItemId` — string; required; minimum length 1. Identifier of the exact item inside the immutable evidence manifest. Minimum accepted length or value is 1.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).workspaceRepositoryId` — string; required; minimum length 1. Workspace-scoped connected repository identifier recorded in evidence provenance. Minimum accepted length or value is 1.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).revisionId` — string; required; minimum length 1. Immutable indexed repository revision identifier. Minimum accepted length or value is 1.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).commitSha` — string; required. Git commit SHA pinned by the evidence manifest.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).blobSha` — string; required. Git blob SHA for the cited file contents.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).path` — string; required; minimum length 1. Repository-relative source path; it never denotes an arbitrary local filesystem path. Minimum accepted length or value is 1.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).startLine` — integer; required. One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).endLine` — integer; required. One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).excerptSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the exact cited excerpt.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `collections.findings.items[].citationsV2[] (anyOf branch 3).coverage` — object; required. Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).coverage{key}` — JSON value; optional.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).verification` — "exact" | "canonical" | "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. Allowed values: "exact", "canonical", "unverified".
- `collections.findings.items[].citationsV2[] (anyOf branch 3).identitySchemaVersion` — constant 2; required. Version of the reviewer identity attribution stamped on this citation record. This branch always uses 2.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities` — array; required; minimum items 1; maximum items 20. Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. An empty array explicitly means no matching items.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[]` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].schemaVersion` — constant 2; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].reviewerRef (anyOf branch 1)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].reviewerRef (anyOf branch 2)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].legacyRole` — JSON value; required. Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].legacyRole (anyOf branch 1)` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 3).reviewerIdentities[].legacyRole (anyOf branch 2)` — null; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 4)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).sourceType` — constant "local-worktree"; required. Discriminator identifying the evidence source variant. This branch always uses "local-worktree".
- `collections.findings.items[].citationsV2[] (anyOf branch 4).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).repositoryId` — string; required; minimum length 1. Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).headSha` — string; required. Git commit SHA of the local worktree HEAD at binding or citation time.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).fileSha` — JSON value; optional. Git blob SHA of the local working file computed with git hash-object; null when unavailable. 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.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).fileSha (anyOf branch 1)` — string; optional.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).fileSha (anyOf branch 2)` — null; optional.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).path` — string; required; minimum length 1; maximum length 4096. Repository-relative source path; it never denotes an arbitrary local filesystem path. Accepted length or value is 1 through 4096, inclusive.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).startLine` — integer; required. One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).endLine` — integer; required. One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).excerptSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the exact cited excerpt.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).dirty` — boolean; required. Whether the local worktree had uncommitted changes at binding or citation time.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).verification` — constant "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. This branch always uses "unverified".
- `collections.findings.items[].citationsV2[] (anyOf branch 4).identitySchemaVersion` — constant 2; required. Version of the reviewer identity attribution stamped on this citation record. This branch always uses 2.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities` — array; required; minimum items 1; maximum items 20. Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. An empty array explicitly means no matching items.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[]` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].schemaVersion` — constant 2; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].reviewerRef (anyOf branch 1)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].reviewerRef (anyOf branch 2)` — object; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].legacyRole` — JSON value; required. Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].legacyRole (anyOf branch 1)` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].citationsV2[] (anyOf branch 4).reviewerIdentities[].legacyRole (anyOf branch 2)` — null; required.
- `collections.findings.items[].reviewerIdentities` — array; optional; minimum items 1; maximum items 20. Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `collections.findings.items[].reviewerIdentities[]` — object; required.
- `collections.findings.items[].reviewerIdentities[].schemaVersion` — constant 2; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2.
- `collections.findings.items[].reviewerIdentities[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `collections.findings.items[].reviewerIdentities[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `collections.findings.items[].reviewerIdentities[].reviewerRef (anyOf branch 1)` — object; required.
- `collections.findings.items[].reviewerIdentities[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `collections.findings.items[].reviewerIdentities[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.findings.items[].reviewerIdentities[].reviewerRef (anyOf branch 2)` — object; required.
- `collections.findings.items[].reviewerIdentities[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `collections.findings.items[].reviewerIdentities[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `collections.findings.items[].reviewerIdentities[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `collections.findings.items[].reviewerIdentities[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `collections.findings.items[].reviewerIdentities[].legacyRole` — JSON value; required. Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.findings.items[].reviewerIdentities[].legacyRole (anyOf branch 1)` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.findings.items[].reviewerIdentities[].legacyRole (anyOf branch 2)` — null; required.
- `collections.findings.items[].evidenceUnavailable` — boolean; optional. Whether the finding was emitted without the evidence normally required for verification; omission means evidence availability was not separately recorded. Omit the field when it does not apply; omission is distinct from an empty value.
- `collections.findings.items[].claimDisposition` — "verified" | "unverified"; optional. Published support disposition for a code claim; omission indicates a legacy row that is treated as verified. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: "verified", "unverified".
- `collections.findings.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.proposals` — object; required. Reviewer proposals and their decision/commit state.
- `collections.proposals.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.proposals.items[]` — object; required.
- `collections.proposals.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.proposals.items[].sessionId` — string; required. Review-session identifier associated with this historical record; null means legacy provenance is unavailable.
- `collections.proposals.items[].section` — string; required. Canonical brief section key associated with the question, finding, proposal, or decision entry.
- `collections.proposals.items[].summary` — string | null; required. Concise safe summary intended for users and logs. A null value explicitly means no current value is available.
- `collections.proposals.items[].status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `collections.proposals.items[].decidedById` — string | null; required. Semel user identifier that decided this proposal; absent until a decision exists. A null value explicitly means no current value is available.
- `collections.proposals.items[].decidedAt` — string | null; required. RFC 3339 timestamp of the proposal decision; null means undecided. A null value explicitly means no current value is available.
- `collections.proposals.items[].decisionSource` — string | null; required. Typed provenance showing whether a proposal decision came from a user, reviewer, or system rule; null means unavailable legacy provenance. A null value explicitly means no current value is available.
- `collections.proposals.items[].committedAt` — string | null; required. RFC 3339 timestamp when the accepted proposal was committed; null means not committed. A null value explicitly means no current value is available.
- `collections.proposals.items[].sourceRound` — JSON value; required. Review round that produced this proposal; null means no round provenance was recorded. A null value explicitly means no current value is available. The value must be an integer.
- `collections.proposals.items[].sourceRound (anyOf branch 1)` — integer; required.
- `collections.proposals.items[].sourceRound (anyOf branch 2)` — null; required.
- `collections.proposals.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.proposals.items[].reviewerIdentities` — array; optional; minimum items 1; maximum items 20. Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `collections.proposals.items[].reviewerIdentities[]` — object; required.
- `collections.proposals.items[].reviewerIdentities[].schemaVersion` — constant 2; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2.
- `collections.proposals.items[].reviewerIdentities[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `collections.proposals.items[].reviewerIdentities[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `collections.proposals.items[].reviewerIdentities[].reviewerRef (anyOf branch 1)` — object; required.
- `collections.proposals.items[].reviewerIdentities[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `collections.proposals.items[].reviewerIdentities[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.proposals.items[].reviewerIdentities[].reviewerRef (anyOf branch 2)` — object; required.
- `collections.proposals.items[].reviewerIdentities[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `collections.proposals.items[].reviewerIdentities[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `collections.proposals.items[].reviewerIdentities[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `collections.proposals.items[].reviewerIdentities[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `collections.proposals.items[].reviewerIdentities[].legacyRole` — JSON value; required. Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.proposals.items[].reviewerIdentities[].legacyRole (anyOf branch 1)` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.proposals.items[].reviewerIdentities[].legacyRole (anyOf branch 2)` — null; required.
- `collections.proposals.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.approvals` — object; required. Append-only human approval records for brief versions.
- `collections.approvals.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.approvals.items[]` — object; required.
- `collections.approvals.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.approvals.items[].contractVersionId` — string; required. Immutable brief contract-version identifier resolved by Semel.
- `collections.approvals.items[].approverId` — string; required. Semel user identifier for the human who recorded this approval decision.
- `collections.approvals.items[].action` — string; required. Typed human approval action recorded in the append-only approval ledger.
- `collections.approvals.items[].isStale` — boolean; required. Whether this historical approval no longer targets the current brief version.
- `collections.approvals.items[].reRequestReason` — string | null; required. Reason a previously decided approval was requested again; null means no re-request reason applies. A null value explicitly means no current value is available.
- `collections.approvals.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.approvals.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.comments` — object; required. Human comments attached to brief sections or anchors.
- `collections.comments.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.comments.items[]` — object; required.
- `collections.comments.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.comments.items[].sectionKey` — string; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result.
- `collections.comments.items[].anchor` — string | null; required. Optional structured location within a brief section for this comment; null means the comment applies to the section as a whole. A null value explicitly means no current value is available.
- `collections.comments.items[].text` — string; required. Human-authored or model-produced text for this typed record.
- `collections.comments.items[].authorId` — string; required. Semel user identifier for the comment or content author.
- `collections.comments.items[].resolvedAt` — string | null; required. RFC 3339 timestamp when the comment was resolved; null means unresolved. A null value explicitly means no current value is available.
- `collections.comments.items[].resolvedBy` — string | null; required. Semel user identifier that resolved the comment; absent until resolution. A null value explicitly means no current value is available.
- `collections.comments.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.comments.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.artifacts` — object; required. Source artifacts attached to the brief.
- `collections.artifacts.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.artifacts.items[]` — object; required.
- `collections.artifacts.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.artifacts.items[].artifactType` — string; required. Semel artifact classification used to select ingestion and display behavior for this source material.
- `collections.artifacts.items[].label` — string | null; required. Human-readable label displayed for this record. A null value explicitly means no current value is available.
- `collections.artifacts.items[].sourceUrl` — string | null; required. Original source URL recorded for the artifact; null means the artifact has no external source URL. A null value explicitly means no current value is available.
- `collections.artifacts.items[].mimeType` — string | null; required. Internet media type of the artifact or exported resource; null means the producer did not record one. A null value explicitly means no current value is available.
- `collections.artifacts.items[].sizeBytes` — JSON value; required. Artifact size in bytes. A null value explicitly means no current value is available. The value must be an integer.
- `collections.artifacts.items[].sizeBytes (anyOf branch 1)` — integer; required.
- `collections.artifacts.items[].sizeBytes (anyOf branch 2)` — null; required.
- `collections.artifacts.items[].ingestionStatus` — string; required. Current artifact ingestion lifecycle state; only ready artifacts may supply reviewed evidence.
- `collections.artifacts.items[].createdById` — string | null; required. Semel user identifier recorded as the initiating creator. A null value explicitly means no current value is available.
- `collections.artifacts.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.artifacts.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.workOrders` — object; required. Materialized implementation work orders for the brief.
- `collections.workOrders.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.workOrders.items[]` — object; required.
- `collections.workOrders.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.workOrders.items[].title` — string; required. Human-readable title displayed in Semel.
- `collections.workOrders.items[].description` — string | null; required. Human-readable explanatory text; null or omission means no description was supplied. A null value explicitly means no current value is available.
- `collections.workOrders.items[].position` — integer; required. Stable zero-based or configured ordering position returned by Semel. The value must be an integer.
- `collections.workOrders.items[].boundCriteria` — array; required. Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items.
- `collections.workOrders.items[].boundCriteria[]` — string; required.
- `collections.workOrders.items[].boundRequirements` — array; required. Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. An empty array explicitly means no matching items.
- `collections.workOrders.items[].boundRequirements[]` — string; required.
- `collections.workOrders.items[].externalTracker` — string | null; required. External issue-tracker provider associated with the work order; null means the work order has not been exported. A null value explicitly means no current value is available.
- `collections.workOrders.items[].externalUrl` — string | null; required. External tracker URL associated with the work order; null means no issue is linked. A null value explicitly means no current value is available.
- `collections.workOrders.items[].exportState` — string; required. Current external-tracker export lifecycle state for this generated work order.
- `collections.workOrders.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.workOrders.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.reviewSessions` — object; required. Review session summaries associated with the brief.
- `collections.reviewSessions.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.reviewSessions.items[]` — object; required.
- `collections.reviewSessions.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.reviewSessions.items[].runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `collections.reviewSessions.items[].status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `collections.reviewSessions.items[].reviewerSet` — array; required. Ordered reviewer roles configured for this cascade. An empty array explicitly means no matching items.
- `collections.reviewSessions.items[].reviewerSet[]` — string; required.
- `collections.reviewSessions.items[].reviewerIdentitySchemaVersion` — constant 2; optional. Version of the reviewer identity schema attached to this historical review session. Omit the field when it does not apply; omission is distinct from an empty value. This branch always uses 2.
- `collections.reviewSessions.items[].cascadeExecutionSnapshotId` — string; optional. Identifier of the immutable cascade snapshot shared by every reviewer session in this pass. Omit the field when it does not apply; omission is distinct from an empty value.
- `collections.reviewSessions.items[].activeReviewerOccurrenceId` — string; optional. Enabled reviewer occurrence assigned to this individual review session or execution. Omit the field when it does not apply; omission is distinct from an empty value.
- `collections.reviewSessions.items[].reviewerOccurrences` — array; optional; minimum items 1; maximum items 20. Complete ordered reviewer occurrence list preserved in the immutable cascade execution snapshot. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `collections.reviewSessions.items[].reviewerOccurrences[]` — object; required.
- `collections.reviewSessions.items[].reviewerOccurrences[].position` — integer; required; minimum 0. Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer.
- `collections.reviewSessions.items[].reviewerOccurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `collections.reviewSessions.items[].reviewerOccurrences[].identity` — object; required. Frozen reviewer occurrence identity used for display and exact historical attribution.
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.reviewerRef (anyOf branch 1)` — object; required.
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.reviewerRef (anyOf branch 2)` — object; required.
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.legacyRole` — JSON value; required. Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: "product", "engineering", "design", "security", "test".
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.legacyRole (anyOf branch 1)` — "product" | "engineering" | "design" | "security" | "test"; required.
- `collections.reviewSessions.items[].reviewerOccurrences[].identity.legacyRole (anyOf branch 2)` — null; required.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin` — object; required. Exact skill, framing, capability, and model pins for this reviewer occurrence.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.framing` — object; required. Exact shared reviewer framing artifact pin used for this occurrence.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.framing.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.framing.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.capabilities` — array; required; maximum items 32. Ordered exact capability artifact pins available to this reviewer occurrence. An empty array explicitly means no matching items.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.capabilities[]` — object; required.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.capabilities[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.capabilities[].version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.capabilities[].sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.model` — object; required. Optional model name declared by the harness.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `collections.reviewSessions.items[].reviewerOccurrences[].pin.model.reasoning (anyOf branch 2)` — null; required.
- `collections.reviewSessions.items[].reviewerConfiguration` — object; optional. Immutable configuration revision and adoption origin preserved for this review session. Omit the field when it does not apply; omission is distinct from an empty value.
- `collections.reviewSessions.items[].reviewerConfiguration.revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `collections.reviewSessions.items[].reviewerConfiguration.origin` — object; required. Immutable source from which this cascade configuration was adopted; it never consults a current default.
- `collections.reviewSessions.items[].reviewerConfiguration.origin.kind` — "project" | "personal_default" | "team_default" | "builtin_fallback" | "explicit_override"; required. Discriminator identifying the typed variant represented by this object. Allowed values: "project", "personal_default", "team_default", "builtin_fallback", "explicit_override".
- `collections.reviewSessions.items[].reviewerConfiguration.origin.presetVersionId` — JSON value; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available. Accepted length or value is 1 through 200, inclusive.
- `collections.reviewSessions.items[].reviewerConfiguration.origin.presetVersionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 200.
- `collections.reviewSessions.items[].reviewerConfiguration.origin.presetVersionId (anyOf branch 2)` — null; required.
- `collections.reviewSessions.items[].reviewedContractVersionId` — string | null; required. Immutable contract-version identifier actually reviewed by this session; null means the session has not pinned one. A null value explicitly means no current value is available.
- `collections.reviewSessions.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.reviewSessions.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `collections.shares` — object; required. Share-link records associated with the brief.
- `collections.shares.items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `collections.shares.items[]` — object; required.
- `collections.shares.items[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `collections.shares.items[].accessLevel` — string; required. Share-link access policy assigned by Semel; the enum identifies whether the recipient may only view or may also interact.
- `collections.shares.items[].sharedById` — string; required. Semel user identifier for the person who created the share.
- `collections.shares.items[].isActive` — boolean; required. Whether this share link remains active.
- `collections.shares.items[].expiresAt` — string | null; required. RFC 3339 expiration timestamp. A null value explicitly means no current value is available.
- `collections.shares.items[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `collections.shares.nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `gateNotificationStatus` — JSON value; required. Latest human gate notification status; null means no notification request exists. A null value explicitly means no current value is available.
- `gateNotificationStatus (anyOf branch 1)` — object; required.
- `gateNotificationStatus (anyOf branch 1).requestId` — string; required. Server request identifier used for support correlation; it is not an idempotency key.
- `gateNotificationStatus (anyOf branch 1).assignmentId` — string | null; required. Human gate assignment identifier created by Semel. A null value explicitly means no current value is available.
- `gateNotificationStatus (anyOf branch 1).contentHash` — string | null; required. Hash of the immutable brief content snapshot. A null value explicitly means no current value is available.
- `gateNotificationStatus (anyOf branch 1).notifiedAt` — string | null; required. RFC 3339 timestamp when the gate notification was sent; null means not sent. A null value explicitly means no current value is available.
- `gateNotificationStatus (anyOf branch 1).createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `gateNotificationStatus (anyOf branch 2)` — null; required.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"brief": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"state": {
"type": "string",
"enum": [
"drafting",
"in_review",
"baselined",
"in_development",
"checked",
"superseded",
"closed"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"drafting\", \"in_review\", \"baselined\", \"in_development\", \"checked\", \"superseded\", \"closed\"."
},
"currentVersionHash": {
"type": [
"string",
"null"
],
"description": "Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available."
},
"content": {
"type": "object",
"additionalProperties": {},
"description": "Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
},
"delivery": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"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."
},
"aiReviewerIdentity": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2."
},
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"legacyRole": {
"anyOf": [
{
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
{
"type": "null"
}
],
"description": "Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"schemaVersion",
"occurrenceId",
"reviewerRef",
"label",
"legacyRole"
],
"additionalProperties": false,
"description": "Server-stamped identity of the reviewer occurrence that authored this immutable brief version. Omit the field when it does not apply; omission is distinct from an empty value."
},
"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."
},
"reviewerIdentity": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2."
},
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"legacyRole": {
"anyOf": [
{
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
{
"type": "null"
}
],
"description": "Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"schemaVersion",
"occurrenceId",
"reviewerRef",
"label",
"legacyRole"
],
"additionalProperties": false,
"description": "Server-stamped reviewer occurrence identity, or the bounded occurrence echo accepted from a schema-2 result. Omit the field when it does not apply; omission is distinct from an empty value."
},
"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "local-worktree",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"local-worktree\"."
},
"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."
},
"repositoryId": {
"type": "string",
"minLength": 1,
"description": "Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1."
},
"headSha": {
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$",
"description": "Git commit SHA of the local worktree HEAD at binding or citation time."
},
"fileSha": {
"anyOf": [
{
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$"
},
{
"type": "null"
}
],
"description": "Git blob SHA of the local working file computed with git hash-object; null when unavailable. 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."
},
"path": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Repository-relative source path; it never denotes an arbitrary local filesystem path. Accepted length or value is 1 through 4096, inclusive."
},
"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."
},
"dirty": {
"type": "boolean",
"description": "Whether the local worktree had uncommitted changes at binding or citation time."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
},
"verification": {
"type": "string",
"const": "unverified",
"description": "Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. This branch always uses \"unverified\"."
},
"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."
}
},
"required": [
"sourceType",
"citationKey",
"repositoryId",
"headSha",
"path",
"startLine",
"endLine",
"excerptSha256",
"dirty",
"verbatim",
"verification",
"reviewers"
],
"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."
},
"citationsV2": {
"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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."
},
"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\"."
},
"identitySchemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the reviewer identity attribution stamped on this citation record. This branch always uses 2."
},
"reviewerIdentities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2."
},
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"legacyRole": {
"anyOf": [
{
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
{
"type": "null"
}
],
"description": "Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"schemaVersion",
"occurrenceId",
"reviewerRef",
"label",
"legacyRole"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. An empty array explicitly means no matching items."
}
},
"required": [
"sourceType",
"sectionKey",
"verbatim",
"briefId",
"contractVersionId",
"verification",
"identitySchemaVersion",
"reviewerIdentities"
],
"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."
},
"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\"."
},
"identitySchemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the reviewer identity attribution stamped on this citation record. This branch always uses 2."
},
"reviewerIdentities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2."
},
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"legacyRole": {
"anyOf": [
{
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
{
"type": "null"
}
],
"description": "Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"schemaVersion",
"occurrenceId",
"reviewerRef",
"label",
"legacyRole"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. An empty array explicitly means no matching items."
}
},
"required": [
"sourceType",
"artifactId",
"verbatim",
"extractedTextHash",
"verification",
"identitySchemaVersion",
"reviewerIdentities"
],
"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."
},
"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\"."
},
"identitySchemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the reviewer identity attribution stamped on this citation record. This branch always uses 2."
},
"reviewerIdentities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2."
},
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"legacyRole": {
"anyOf": [
{
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
{
"type": "null"
}
],
"description": "Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"schemaVersion",
"occurrenceId",
"reviewerRef",
"label",
"legacyRole"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. An empty array explicitly means no matching items."
}
},
"required": [
"sourceType",
"citationKey",
"verbatim",
"evidenceManifestId",
"evidenceManifestItemId",
"workspaceRepositoryId",
"revisionId",
"commitSha",
"blobSha",
"path",
"startLine",
"endLine",
"excerptSha256",
"route",
"coverage",
"verification",
"identitySchemaVersion",
"reviewerIdentities"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"sourceType": {
"type": "string",
"const": "local-worktree",
"description": "Discriminator identifying the evidence source variant. This branch always uses \"local-worktree\"."
},
"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."
},
"repositoryId": {
"type": "string",
"minLength": 1,
"description": "Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1."
},
"headSha": {
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$",
"description": "Git commit SHA of the local worktree HEAD at binding or citation time."
},
"fileSha": {
"anyOf": [
{
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$"
},
{
"type": "null"
}
],
"description": "Git blob SHA of the local working file computed with git hash-object; null when unavailable. 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."
},
"path": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Repository-relative source path; it never denotes an arbitrary local filesystem path. Accepted length or value is 1 through 4096, inclusive."
},
"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."
},
"dirty": {
"type": "boolean",
"description": "Whether the local worktree had uncommitted changes at binding or citation time."
},
"verbatim": {
"type": "string",
"minLength": 1,
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive."
},
"verification": {
"type": "string",
"const": "unverified",
"description": "Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. This branch always uses \"unverified\"."
},
"identitySchemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the reviewer identity attribution stamped on this citation record. This branch always uses 2."
},
"reviewerIdentities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2."
},
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"legacyRole": {
"anyOf": [
{
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
{
"type": "null"
}
],
"description": "Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"schemaVersion",
"occurrenceId",
"reviewerRef",
"label",
"legacyRole"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. An empty array explicitly means no matching items."
}
},
"required": [
"sourceType",
"citationKey",
"repositoryId",
"headSha",
"path",
"startLine",
"endLine",
"excerptSha256",
"dirty",
"verbatim",
"verification",
"identitySchemaVersion",
"reviewerIdentities"
],
"additionalProperties": false
}
]
},
"description": "Schema-2 evidence citations carrying server-stamped reviewer occurrence attribution. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"reviewerIdentities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2."
},
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"legacyRole": {
"anyOf": [
{
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
{
"type": "null"
}
],
"description": "Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"schemaVersion",
"occurrenceId",
"reviewerRef",
"label",
"legacyRole"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. 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."
},
"reviewerIdentities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2."
},
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"legacyRole": {
"anyOf": [
{
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
{
"type": "null"
}
],
"description": "Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"schemaVersion",
"occurrenceId",
"reviewerRef",
"label",
"legacyRole"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Server-stamped reviewer occurrence identities attributed to this finding, proposal, or citation. 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",
"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."
},
"reviewerIdentitySchemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the reviewer identity schema attached to this historical review session. Omit the field when it does not apply; omission is distinct from an empty value. This branch always uses 2."
},
"cascadeExecutionSnapshotId": {
"type": "string",
"description": "Identifier of the immutable cascade snapshot shared by every reviewer session in this pass. Omit the field when it does not apply; omission is distinct from an empty value."
},
"activeReviewerOccurrenceId": {
"type": "string",
"description": "Enabled reviewer occurrence assigned to this individual review session or execution. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reviewerOccurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"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."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"identity": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"legacyRole": {
"anyOf": [
{
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
{
"type": "null"
}
],
"description": "Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"legacyRole"
],
"additionalProperties": false,
"description": "Frozen reviewer occurrence identity used for display and exact historical attribution."
},
"pin": {
"type": "object",
"properties": {
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"framing": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact shared reviewer framing artifact pin used for this occurrence."
},
"capabilities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"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."
},
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"id",
"version",
"sha256"
],
"additionalProperties": false
},
"maxItems": 32,
"description": "Ordered exact capability artifact pins available to this reviewer occurrence. An empty array explicitly means no matching items."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"skill",
"framing",
"capabilities",
"model"
],
"additionalProperties": false,
"description": "Exact skill, framing, capability, and model pins for this reviewer occurrence."
}
},
"required": [
"position",
"enabled",
"identity",
"pin"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Complete ordered reviewer occurrence list preserved in the immutable cascade execution snapshot. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"reviewerConfiguration": {
"type": "object",
"properties": {
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"origin": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"project",
"personal_default",
"team_default",
"builtin_fallback",
"explicit_override"
],
"description": "Discriminator identifying the typed variant represented by this object. Allowed values: \"project\", \"personal_default\", \"team_default\", \"builtin_fallback\", \"explicit_override\"."
},
"presetVersionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available. Accepted length or value is 1 through 200, inclusive."
}
},
"required": [
"kind",
"presetVersionId"
],
"additionalProperties": false,
"description": "Immutable source from which this cascade configuration was adopted; it never consults a current default."
}
},
"required": [
"revision",
"origin"
],
"additionalProperties": false,
"description": "Immutable configuration revision and adoption origin preserved for this review session. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reviewedContractVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable contract-version identifier actually reviewed by this session; null means the session has not pinned one. A null value explicitly means no current value is available."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"runId",
"status",
"reviewerSet",
"reviewedContractVersionId",
"createdAt"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Review session summaries associated with the brief."
},
"shares": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"accessLevel": {
"type": "string",
"description": "Share-link access policy assigned by Semel; the enum identifies whether the recipient may only view or may also interact."
},
"sharedById": {
"type": "string",
"description": "Semel user identifier for the person who created the share."
},
"isActive": {
"type": "boolean",
"description": "Whether this share link remains active."
},
"expiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 expiration timestamp. A null value explicitly means no current value is available."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"accessLevel",
"sharedById",
"isActive",
"expiresAt",
"createdAt"
],
"additionalProperties": false
},
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"items",
"nextCursor"
],
"additionalProperties": false,
"description": "Share-link records associated with the brief."
}
},
"required": [
"versions",
"decisionHistory",
"findings",
"proposals",
"approvals",
"comments",
"artifacts",
"workOrders",
"reviewSessions",
"shares"
],
"additionalProperties": false,
"description": "First page of each durable collection associated with the brief."
},
"gateNotificationStatus": {
"anyOf": [
{
"type": "object",
"properties": {
"requestId": {
"type": "string",
"description": "Server request identifier used for support correlation; it is not an idempotency key."
},
"assignmentId": {
"type": [
"string",
"null"
],
"description": "Human gate assignment identifier created by Semel. A null value explicitly means no current value is available."
},
"contentHash": {
"type": [
"string",
"null"
],
"description": "Hash of the immutable brief content snapshot. A null value explicitly means no current value is available."
},
"notifiedAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp when the gate notification was sent; null means not sent. A null value explicitly means no current value is available."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"requestId",
"assignmentId",
"contentHash",
"notifiedAt",
"createdAt"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Latest human gate notification status; null means no notification request exists. A null value explicitly means no current value is available."
}
},
"required": [
"brief",
"collections",
"gateNotificationStatus"
],
"additionalProperties": false
}
```
**Example structured result (full-brief)**
```json
{
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"versionNum": 1
},
"collections": {
"versions": {
"items": [],
"nextCursor": null
},
"decisionHistory": {
"items": [],
"nextCursor": null
},
"findings": {
"items": [],
"nextCursor": null
},
"proposals": {
"items": [],
"nextCursor": null
},
"approvals": {
"items": [],
"nextCursor": null
},
"comments": {
"items": [],
"nextCursor": null
},
"artifacts": {
"items": [],
"nextCursor": null
},
"workOrders": {
"items": [],
"nextCursor": null
},
"reviewSessions": {
"items": [],
"nextCursor": null
},
"shares": {
"items": [],
"nextCursor": null
}
},
"gateNotificationStatus": null
}
```
Bindings: brief from structuredContent.brief.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"brief\":{\"id\":\"brf_fixture_checkout\",\"projectId\":\"prj_fixture_checkout\",\"title\":\"Retry-safe checkout\",\"state\":\"drafting\",\"currentVersionHash\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"content\":{\"goal\":\"Prevent duplicate charges when checkout retries.\",\"requirements\":[\"Reuse one payment intent for retried submissions.\"],\"acceptanceCriteria\":[{\"id\":\"AC-01\",\"text\":\"A retried request returns the original successful result.\"}],\"sourceArtifactLinks\":[{\"label\":\"Linear ENG-42\",\"kind\":\"linear\"}]},\"versionNum\":1},\"collections\":{\"versions\":{\"items\":[],\"nextCursor\":null},\"decisionHistory\":{\"items\":[],\"nextCursor\":null},\"findings\":{\"items\":[],\"nextCursor\":null},\"proposals\":{\"items\":[],\"nextCursor\":null},\"approvals\":{\"items\":[],\"nextCursor\":null},\"comments\":{\"items\":[],\"nextCursor\":null},\"artifacts\":{\"items\":[],\"nextCursor\":null},\"workOrders\":{\"items\":[],\"nextCursor\":null},\"reviewSessions\":{\"items\":[],\"nextCursor\":null},\"shares\":{\"items\":[],\"nextCursor\":null}},\"gateNotificationStatus\":null}"
}
],
"structuredContent": {
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"versionNum": 1
},
"collections": {
"versions": {
"items": [],
"nextCursor": null
},
"decisionHistory": {
"items": [],
"nextCursor": null
},
"findings": {
"items": [],
"nextCursor": null
},
"proposals": {
"items": [],
"nextCursor": null
},
"approvals": {
"items": [],
"nextCursor": null
},
"comments": {
"items": [],
"nextCursor": null
},
"artifacts": {
"items": [],
"nextCursor": null
},
"workOrders": {
"items": [],
"nextCursor": null
},
"reviewSessions": {
"items": [],
"nextCursor": null
},
"shares": {
"items": [],
"nextCursor": null
}
},
"gateNotificationStatus": null
}
}
```
Next permitted action: Show the created brief and call out any source gaps for the human.
**Example requests**
- “/semel show me everything in the checkout brief”
- “/semel open the full brief for the billing project”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `brief_list`, `brief_collection_list`, `brief_export_package`.
---
### brief_list
List the briefs this principal may reach (filtered by its project allowlist), newest-updated first. Use to find a brief before reading or editing it.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `cursor` — string; optional; minimum length 1. Opaque keyset cursor returned as nextCursor by the preceding brief_list response. Omit to read the first page.
- `limit` — integer; optional; minimum 1; maximum 200. Maximum briefs to return, as an integer from 1 through 200. Omit to use the server default.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque keyset cursor returned as nextCursor by the preceding brief_list response. Omit to read the first page."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Maximum briefs to return, as an integer from 1 through 200. Omit to use the server default."
}
},
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"limit": 50
}
```
**Binding template**
```json
{
"limit": 50
}
```
**Returns**
- `briefs` — array; required. Brief summaries reachable by the authenticated principal. An empty array explicitly means no matching items.
- `briefs[]` — object; required.
- `briefs[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `briefs[].projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `briefs[].title` — string; required. Human-readable title displayed in Semel.
- `briefs[].state` — string; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `briefs[].versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `briefs[].updatedAt` — string; required. RFC 3339 timestamp when this record was last updated.
- `briefs[].delivery` — object; optional. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value.
- `briefs[].delivery.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `briefs[].delivery.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `briefs[].delivery.deliveryStatus (anyOf branch 2)` — null; required.
- `briefs[].delivery.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `briefs[].delivery.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `briefs[].delivery.changedAt (anyOf branch 1)` — string; required; format date-time.
- `briefs[].delivery.changedAt (anyOf branch 2)` — null; required.
- `briefs[].delivery.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `briefs[].delivery.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `briefs[].delivery.source (anyOf branch 1)` — "web" | "mcp"; required.
- `briefs[].delivery.source (anyOf branch 2)` — null; required.
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"briefs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"state": {
"type": "string",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
},
"updatedAt": {
"type": "string",
"description": "RFC 3339 timestamp when this record was last updated."
},
"delivery": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"id",
"projectId",
"title",
"state",
"versionNum",
"updatedAt"
],
"additionalProperties": false
},
"description": "Brief summaries reachable by the authenticated principal. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"briefs",
"nextCursor"
],
"additionalProperties": false
}
```
**Example structured result (brief-list)**
```json
{
"briefs": [
{
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"versionNum": 3,
"updatedAt": "2026-09-07T16:00:00.000Z"
}
],
"nextCursor": null
}
```
Bindings: briefId from structuredContent.briefs[0].id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"briefs\":[{\"id\":\"brf_fixture_checkout\",\"projectId\":\"prj_fixture_checkout\",\"title\":\"Retry-safe checkout\",\"state\":\"drafting\",\"versionNum\":3,\"updatedAt\":\"2026-09-07T16:00:00.000Z\"}],\"nextCursor\":null}"
}
],
"structuredContent": {
"briefs": [
{
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"versionNum": 3,
"updatedAt": "2026-09-07T16:00:00.000Z"
}
],
"nextCursor": null
}
}
```
Next permitted action: Select an exact brief or ask the human to disambiguate.
**Example requests**
- “/semel list my briefs”
- “/semel what briefs are there in progress?”
Errors: universal authentication and validation errors only.
Related operations: `brief_get_full`, `brief_collection_list`.
---
### brief_update
Edit a brief's title and content, minting a new immutable contract version whenever the content changes. Use to revise requirements or work orders on an existing brief; pass ifVersionNum to guard against a concurrent edit.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `content` — object; required. Complete replacement brief document for agent writes, limited to 262144 serialized bytes. Known sections use the canonical nested shapes; unknown metadata and _draft remain round-trippable.
- `content.goal` — string; optional; maximum length 4000. Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.userPersonaContext` — string; optional; maximum length 4000. User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.customerFacingLaunchMessage` — string; optional; maximum length 4000. Copy-ready end-user launch message stating the capability, value, and one concrete example. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.scope` — string; optional; maximum length 4000. Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.outOfScope` — string; optional; maximum length 4000. Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.requirements` — array; optional; maximum items 50. Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.requirements[]` — string; required; minimum length 1; maximum length 1000.
- `content.edgeCases` — array; optional; maximum items 50. Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.edgeCases[]` — string; required; minimum length 1; maximum length 1000.
- `content.acceptanceCriteria` — array; optional; maximum items 50. Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.acceptanceCriteria[]` — object; required.
- `content.acceptanceCriteria[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.acceptanceCriteria[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.acceptanceCriteria[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.acceptanceCriteria[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.acceptanceCriteria[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `content.acceptanceCriteria[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `content.rolesPermissions` — array; optional; maximum items 50. Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.rolesPermissions[]` — string; required; minimum length 1; maximum length 1000.
- `content.states` — array; optional; maximum items 50. User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.states[]` — string; required; minimum length 1; maximum length 1000.
- `content.productSolution` — string; optional; maximum length 4000. Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.technicalSolution` — string; optional; maximum length 4000. Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.dataModelImplications` — string; optional; maximum length 4000. Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.architectureAssumptions` — string; optional; maximum length 4000. Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.design` — string; optional; maximum length 4000. Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `content.testingQaChecklist` — array; optional; maximum items 50. Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testingQaChecklist[]` — object; required.
- `content.testingQaChecklist[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.testingQaChecklist[].checked` — boolean; required. Whether this QA checklist item is currently complete.
- `content.testingQaChecklist[].addedBy` — string; optional; maximum length 200. Actor label that added the QA item; omission means legacy or unavailable attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.testingQaChecklist[].checkedBy` — string; optional; maximum length 200. Actor label that last checked the item; omission means it has no check attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.testingQaChecklist[].checkedAt` — string; optional; format date-time. RFC 3339 timestamp when the item was checked; omission means it is unchecked or legacy data. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string.
- `content.testPlanUnit` — array; optional; maximum items 50. Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanUnit[]` — string; required; minimum length 1; maximum length 1000.
- `content.testPlanIntegration` — array; optional; maximum items 50. Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanIntegration[]` — string; required; minimum length 1; maximum length 1000.
- `content.testPlanUiUx` — array; optional; maximum items 50. Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.testPlanUiUx[]` — string; required; minimum length 1; maximum length 1000.
- `content.openQuestions` — array; optional; maximum items 50. Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.openQuestions[]` — string; required; minimum length 1; maximum length 1000.
- `content.generatedTickets` — array; optional; maximum items 50. Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.generatedTickets[]` — object; required.
- `content.generatedTickets[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.generatedTickets[].title` — string; required; minimum length 1; maximum length 500. Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
- `content.generatedTickets[].description` — JSON value; required. Human-readable explanatory text; null or omission means no description was supplied. A null value explicitly means no current value is available. Maximum accepted length or value is 10000.
- `content.generatedTickets[].description (anyOf branch 1)` — string; required; maximum length 10000.
- `content.generatedTickets[].description (anyOf branch 2)` — null; required.
- `content.generatedTickets[].boundCriteria` — array; required; maximum items 50. Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items.
- `content.generatedTickets[].boundCriteria[]` — string; required; minimum length 1; maximum length 200.
- `content.generatedTickets[].boundRequirements` — array; optional; maximum items 50. Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.generatedTickets[].boundRequirements[]` — string; required; minimum length 1; maximum length 200.
- `content.requiredEvidence` — array; optional; maximum items 50. Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.requiredEvidence[]` — object; required.
- `content.requiredEvidence[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `content.requiredEvidence[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.requiredEvidence[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.requiredEvidence[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.requiredEvidence[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `content.requiredEvidence[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `content.decisions` — array; optional; maximum items 50. Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.decisions[]` — object; required.
- `content.decisions[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `content.decisions[].source` — string; optional; maximum length 1000. Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000.
- `content.decisions[].stated` — boolean; optional. Whether the decision was explicitly stated rather than inferred; omission means unknown legacy provenance. Omit the field when it does not apply; omission is distinct from an empty value.
- `content.sourceArtifactLinks` — array; optional; maximum items 50. Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `content.sourceArtifactLinks[]` — object; required.
- `content.sourceArtifactLinks[].label` — string; required; minimum length 1; maximum length 1000. Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive.
- `content.sourceArtifactLinks[].kind` — string; optional; maximum length 200. Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `content.sourceArtifactLinks[].read` — boolean; optional. Whether the referenced source artifact was read when the brief snapshot was produced. Omit the field when it does not apply; omission is distinct from an empty value.
- `title` — string; optional; minimum length 1; maximum length 500. Human-readable title displayed in Semel. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 500, inclusive.
- `ifVersionNum` — integer; optional. Optional optimistic precondition using the current brief contract version number. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `clearDraft` — boolean; optional. When true, explicitly clears draft state after the complete document update; omission leaves it unchanged. Omit the field when it does not apply; omission is distinct from an empty value.
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"content": {
"type": "object",
"properties": {
"goal": {
"type": "string",
"maxLength": 4000,
"description": "Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"userPersonaContext": {
"type": "string",
"maxLength": 4000,
"description": "User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"customerFacingLaunchMessage": {
"type": "string",
"maxLength": 4000,
"description": "Copy-ready end-user launch message stating the capability, value, and one concrete example. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"scope": {
"type": "string",
"maxLength": 4000,
"description": "Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"outOfScope": {
"type": "string",
"maxLength": 4000,
"description": "Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"requirements": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"edgeCases": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"acceptanceCriteria": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"implementation": {
"type": "boolean",
"description": "Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value."
},
"manualEvidence": {
"type": "object",
"properties": {
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive."
},
"evidencePath": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive."
}
},
"required": [
"rationale",
"evidencePath"
],
"additionalProperties": false,
"description": "Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"id",
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"rolesPermissions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"states": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"productSolution": {
"type": "string",
"maxLength": 4000,
"description": "Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"technicalSolution": {
"type": "string",
"maxLength": 4000,
"description": "Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"dataModelImplications": {
"type": "string",
"maxLength": 4000,
"description": "Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"architectureAssumptions": {
"type": "string",
"maxLength": 4000,
"description": "Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"design": {
"type": "string",
"maxLength": 4000,
"description": "Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000."
},
"testingQaChecklist": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"checked": {
"type": "boolean",
"description": "Whether this QA checklist item is currently complete."
},
"addedBy": {
"type": "string",
"maxLength": 200,
"description": "Actor label that added the QA item; omission means legacy or unavailable attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"checkedBy": {
"type": "string",
"maxLength": 200,
"description": "Actor label that last checked the item; omission means it has no check attribution. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"checkedAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp when the item was checked; omission means it is unchecked or legacy data. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string."
}
},
"required": [
"text",
"checked"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanUnit": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanIntegration": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"testPlanUiUx": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"openQuestions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"maxItems": 50,
"description": "Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"generatedTickets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive."
},
"description": {
"anyOf": [
{
"type": "string",
"maxLength": 10000
},
{
"type": "null"
}
],
"description": "Human-readable explanatory text; null or omission means no description was supplied. A null value explicitly means no current value is available. Maximum accepted length or value is 10000."
},
"boundCriteria": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
},
"maxItems": 50,
"description": "Stable acceptance-criterion IDs implemented by this work order. An empty array explicitly means no matching items."
},
"boundRequirements": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
},
"maxItems": 50,
"description": "Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"required": [
"id",
"title",
"description",
"boundCriteria"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"requiredEvidence": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive."
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"implementation": {
"type": "boolean",
"description": "Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value."
},
"manualEvidence": {
"type": "object",
"properties": {
"rationale": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive."
},
"evidencePath": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive."
}
},
"required": [
"rationale",
"evidencePath"
],
"additionalProperties": false,
"description": "Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"id",
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"decisions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive."
},
"source": {
"type": "string",
"maxLength": 1000,
"description": "Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000."
},
"stated": {
"type": "boolean",
"description": "Whether the decision was explicitly stated rather than inferred; omission means unknown legacy provenance. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"text"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"sourceArtifactLinks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1,
"maxLength": 1000,
"description": "Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive."
},
"kind": {
"type": "string",
"maxLength": 200,
"description": "Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"read": {
"type": "boolean",
"description": "Whether the referenced source artifact was read when the brief snapshot was produced. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"label"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
}
},
"additionalProperties": true,
"description": "Complete replacement brief document for agent writes, limited to 262144 serialized bytes. Known sections use the canonical nested shapes; unknown metadata and _draft remain round-trippable."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Human-readable title displayed in Semel. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 500, inclusive."
},
"ifVersionNum": {
"type": "integer",
"description": "Optional optimistic precondition using the current brief contract version number. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"clearDraft": {
"type": "boolean",
"description": "When true, explicitly clears draft state after the complete document update; omission leaves it unchanged. Omit the field when it does not apply; omission is distinct from an empty value."
},
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; the caller must have access to its project. Supply a non-empty identifier."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"content",
"briefId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"title": "Retry-safe checkout",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
},
{
"id": "AC-02",
"text": "The response identifies the original payment intent."
}
],
"checklist": [
{
"text": "API contract reviewed",
"checked": false
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"ifVersionNum": 3,
"idempotencyKey": "recipe-brief-update-v1"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"title": "{{briefTitle}}",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
},
{
"id": "AC-02",
"text": "The response identifies the original payment intent."
}
],
"checklist": [
{
"text": "API contract reviewed",
"checked": false
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"ifVersionNum": 3,
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `brief` — object; required. Current brief record returned by the operation.
- `brief.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `brief.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `brief.title` — string; required. Human-readable title displayed in Semel.
- `brief.state` — "drafting" | "in_review" | "baselined" | "in_development" | "checked" | "superseded" | "closed"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "drafting", "in_review", "baselined", "in_development", "checked", "superseded", "closed".
- `brief.currentVersionHash` — string | null; required. Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available.
- `brief.content` — object; required. Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable.
- `brief.content{key}` — JSON value; optional.
- `brief.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `brief.delivery` — object; optional. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value.
- `brief.delivery.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `brief.delivery.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `brief.delivery.deliveryStatus (anyOf branch 2)` — null; required.
- `brief.delivery.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `brief.delivery.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `brief.delivery.changedAt (anyOf branch 1)` — string; required; format date-time.
- `brief.delivery.changedAt (anyOf branch 2)` — null; required.
- `brief.delivery.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `brief.delivery.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `brief.delivery.source (anyOf branch 1)` — "web" | "mcp"; required.
- `brief.delivery.source (anyOf branch 2)` — null; required.
- `brief.createdNewVersion` — boolean; required. Whether the write changed canonical content and minted a new immutable brief version.
- `brief.staledApprovals` — integer; required. Number of prior approval rows made stale by this content change. The value must be an integer.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"brief": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"title": {
"type": "string",
"description": "Human-readable title displayed in Semel."
},
"state": {
"type": "string",
"enum": [
"drafting",
"in_review",
"baselined",
"in_development",
"checked",
"superseded",
"closed"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"drafting\", \"in_review\", \"baselined\", \"in_development\", \"checked\", \"superseded\", \"closed\"."
},
"currentVersionHash": {
"type": [
"string",
"null"
],
"description": "Hash of the current canonical brief version; null means no canonical version exists yet. A null value explicitly means no current value is available."
},
"content": {
"type": "object",
"additionalProperties": {},
"description": "Complete brief logical document for writes, or the stored snapshot on reads; unknown metadata remains round-trippable."
},
"versionNum": {
"type": "integer",
"description": "Monotonic brief contract version number assigned by Semel. The value must be an integer."
},
"delivery": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value."
},
"createdNewVersion": {
"type": "boolean",
"description": "Whether the write changed canonical content and minted a new immutable brief version."
},
"staledApprovals": {
"type": "integer",
"description": "Number of prior approval rows made stale by this content change. The value must be an integer."
}
},
"required": [
"id",
"projectId",
"title",
"state",
"currentVersionHash",
"content",
"versionNum",
"createdNewVersion",
"staledApprovals"
],
"additionalProperties": false,
"description": "Current brief record returned by the operation."
}
},
"required": [
"brief"
],
"additionalProperties": false
}
```
**Example structured result (brief-updated)**
```json
{
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
},
{
"id": "AC-02",
"text": "The response identifies the original payment intent."
}
],
"checklist": [
{
"text": "API contract reviewed",
"checked": false
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"versionNum": 4,
"createdNewVersion": true,
"staledApprovals": 0
}
}
```
Bindings: versionNum from structuredContent.brief.versionNum.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"brief\":{\"id\":\"brf_fixture_checkout\",\"projectId\":\"prj_fixture_checkout\",\"title\":\"Retry-safe checkout\",\"state\":\"drafting\",\"currentVersionHash\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"content\":{\"goal\":\"Prevent duplicate charges when checkout retries.\",\"requirements\":[\"Reuse one payment intent for retried submissions.\"],\"acceptanceCriteria\":[{\"id\":\"AC-01\",\"text\":\"A retried request returns the original successful result.\"},{\"id\":\"AC-02\",\"text\":\"The response identifies the original payment intent.\"}],\"checklist\":[{\"text\":\"API contract reviewed\",\"checked\":false}],\"sourceArtifactLinks\":[{\"label\":\"Linear ENG-42\",\"kind\":\"linear\"}]},\"versionNum\":4,\"createdNewVersion\":true,\"staledApprovals\":0}}"
}
],
"structuredContent": {
"brief": {
"id": "brf_fixture_checkout",
"projectId": "prj_fixture_checkout",
"title": "Retry-safe checkout",
"state": "drafting",
"currentVersionHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"content": {
"goal": "Prevent duplicate charges when checkout retries.",
"requirements": [
"Reuse one payment intent for retried submissions."
],
"acceptanceCriteria": [
{
"id": "AC-01",
"text": "A retried request returns the original successful result."
},
{
"id": "AC-02",
"text": "The response identifies the original payment intent."
}
],
"checklist": [
{
"text": "API contract reviewed",
"checked": false
}
],
"sourceArtifactLinks": [
{
"label": "Linear ENG-42",
"kind": "linear"
}
]
},
"versionNum": 4,
"createdNewVersion": true,
"staledApprovals": 0
}
}
}
```
Next permitted action: Inspect createdNewVersion and the returned current version.
**Example requests**
- “/semel update the checkout brief with the new acceptance criteria”
- “/semel revise the requirements on this brief”
Errors: `PROJECT_ACCESS_DENIED`, `BRIEF_VERSION_CONFLICT`.
Related operations: `brief_create`, `brief_get_full`, `brief_checklist_update`.
---
### cascade_default_get
Inspect the exact personal and team default bindings and optimistic revisions before changing a default.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `skills:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `{}` — no arguments.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {},
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{}
```
**Binding template**
```json
{}
```
**Returns**
- `personal` — object; required. Caller-owned cascade default state, including its optimistic revision and exact preset binding when selected.
- `personal.revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `personal.binding` — JSON value; required. Current exact preset binding after the default mutation; null means the default is reset. A null value explicitly means no current value is available.
- `personal.binding (anyOf branch 1)` — object; required.
- `personal.binding (anyOf branch 1).id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `personal.binding (anyOf branch 1).audience` — "personal" | "team"; required. Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: "personal", "team".
- `personal.binding (anyOf branch 1).ownerUserId` — string | null; required. Accountable owner of a personal reviewer skill; null identifies a workspace-team skill. A null value explicitly means no current value is available.
- `personal.binding (anyOf branch 1).revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `personal.binding (anyOf branch 1).presetId` — string; required. Stable cascade preset identifier returned by an exact preset save, list, or read.
- `personal.binding (anyOf branch 1).presetVersionId` — string; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset.
- `personal.binding (anyOf branch 1).presetName` — string; required. Human-readable name of the exact preset currently bound as a default.
- `personal.binding (anyOf branch 1).updatedAt` — string; required. RFC 3339 timestamp when this record was last updated.
- `personal.binding (anyOf branch 2)` — null; required.
- `team` — object; required. Workspace team cascade default state, including its optimistic revision and exact preset binding when selected.
- `team.revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `team.binding` — JSON value; required. Current exact preset binding after the default mutation; null means the default is reset. A null value explicitly means no current value is available.
- `team.binding (anyOf branch 1)` — object; required.
- `team.binding (anyOf branch 1).id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `team.binding (anyOf branch 1).audience` — "personal" | "team"; required. Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: "personal", "team".
- `team.binding (anyOf branch 1).ownerUserId` — string | null; required. Accountable owner of a personal reviewer skill; null identifies a workspace-team skill. A null value explicitly means no current value is available.
- `team.binding (anyOf branch 1).revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `team.binding (anyOf branch 1).presetId` — string; required. Stable cascade preset identifier returned by an exact preset save, list, or read.
- `team.binding (anyOf branch 1).presetVersionId` — string; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset.
- `team.binding (anyOf branch 1).presetName` — string; required. Human-readable name of the exact preset currently bound as a default.
- `team.binding (anyOf branch 1).updatedAt` — string; required. RFC 3339 timestamp when this record was last updated.
- `team.binding (anyOf branch 2)` — null; required.
- `effective` — object; required. Exact cascade selection that a newly created project would inherit after this operation.
- `effective.origin` — "project" | "personal_default" | "team_default" | "builtin_fallback" | "explicit_override"; required. Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: "project", "personal_default", "team_default", "builtin_fallback", "explicit_override".
- `effective.presetVersionId` — string | null; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available.
- `effective.payload` — object; required. Complete ordered cascade selection preserved in this immutable preset or configuration version.
- `effective.payload.schemaVersion` — constant 1; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1.
- `effective.payload.occurrences` — array; required; minimum items 1; maximum items 20. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `effective.payload.occurrences[]` — object; required.
- `effective.payload.occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `effective.payload.occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `effective.payload.occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `effective.payload.occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `effective.payload.occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `effective.payload.occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `effective.payload.occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `effective.payload.occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `effective.payload.occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `effective.payload.occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `effective.payload.occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `effective.payload.occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `effective.payload.occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `effective.payload.occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `effective.payload.occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `effective.payload.occurrences[].model` — object; required. Optional model name declared by the harness.
- `effective.payload.occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `effective.payload.occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `effective.payload.occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `effective.payload.occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `effective.payload.occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `canEditTeam` — boolean; required. Whether the current authenticated caller may change the workspace team cascade default.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"personal": {
"type": "object",
"properties": {
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"binding": {
"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."
},
"audience": {
"type": "string",
"enum": [
"personal",
"team"
],
"description": "Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: \"personal\", \"team\"."
},
"ownerUserId": {
"type": [
"string",
"null"
],
"description": "Accountable owner of a personal reviewer skill; null identifies a workspace-team skill. A null value explicitly means no current value is available."
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"presetId": {
"type": "string",
"description": "Stable cascade preset identifier returned by an exact preset save, list, or read."
},
"presetVersionId": {
"type": "string",
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset."
},
"presetName": {
"type": "string",
"description": "Human-readable name of the exact preset currently bound as a default."
},
"updatedAt": {
"type": "string",
"description": "RFC 3339 timestamp when this record was last updated."
}
},
"required": [
"id",
"audience",
"ownerUserId",
"revision",
"presetId",
"presetVersionId",
"presetName",
"updatedAt"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Current exact preset binding after the default mutation; null means the default is reset. A null value explicitly means no current value is available."
}
},
"required": [
"revision",
"binding"
],
"additionalProperties": false,
"description": "Caller-owned cascade default state, including its optimistic revision and exact preset binding when selected."
},
"team": {
"type": "object",
"properties": {
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"binding": {
"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."
},
"audience": {
"type": "string",
"enum": [
"personal",
"team"
],
"description": "Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: \"personal\", \"team\"."
},
"ownerUserId": {
"type": [
"string",
"null"
],
"description": "Accountable owner of a personal reviewer skill; null identifies a workspace-team skill. A null value explicitly means no current value is available."
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"presetId": {
"type": "string",
"description": "Stable cascade preset identifier returned by an exact preset save, list, or read."
},
"presetVersionId": {
"type": "string",
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset."
},
"presetName": {
"type": "string",
"description": "Human-readable name of the exact preset currently bound as a default."
},
"updatedAt": {
"type": "string",
"description": "RFC 3339 timestamp when this record was last updated."
}
},
"required": [
"id",
"audience",
"ownerUserId",
"revision",
"presetId",
"presetVersionId",
"presetName",
"updatedAt"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Current exact preset binding after the default mutation; null means the default is reset. A null value explicitly means no current value is available."
}
},
"required": [
"revision",
"binding"
],
"additionalProperties": false,
"description": "Workspace team cascade default state, including its optimistic revision and exact preset binding when selected."
},
"effective": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"enum": [
"project",
"personal_default",
"team_default",
"builtin_fallback",
"explicit_override"
],
"description": "Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: \"project\", \"personal_default\", \"team_default\", \"builtin_fallback\", \"explicit_override\"."
},
"presetVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available."
},
"payload": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 1,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"schemaVersion",
"occurrences"
],
"additionalProperties": false,
"description": "Complete ordered cascade selection preserved in this immutable preset or configuration version."
}
},
"required": [
"origin",
"presetVersionId",
"payload"
],
"additionalProperties": false,
"description": "Exact cascade selection that a newly created project would inherit after this operation."
},
"canEditTeam": {
"type": "boolean",
"description": "Whether the current authenticated caller may change the workspace team cascade default."
}
},
"required": [
"personal",
"team",
"effective",
"canEditTeam"
],
"additionalProperties": false
}
```
**Example structured result (cascade-defaults)**
```json
{
"personal": {
"revision": "0",
"binding": null
},
"team": {
"revision": "0",
"binding": null
},
"effective": {
"origin": "builtin_fallback",
"presetVersionId": null,
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
}
},
"canEditTeam": true
}
```
Bindings: personalDefaultRevision from structuredContent.personal.revision.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"personal\":{\"revision\":\"0\",\"binding\":null},\"team\":{\"revision\":\"0\",\"binding\":null},\"effective\":{\"origin\":\"builtin_fallback\",\"presetVersionId\":null,\"payload\":{\"schemaVersion\":1,\"occurrences\":[{\"occurrenceId\":\"checkout-reliability\",\"reviewerRef\":{\"kind\":\"custom\",\"skillId\":\"skl_recipe_checkout\",\"versionId\":\"skv_recipe_checkout_1\"},\"label\":\"Checkout reliability\",\"enabled\":true,\"skill\":{\"version\":\"skv_recipe_checkout_1\",\"sha256\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\"},\"model\":{\"provider\":\"openai\",\"model\":\"gpt-5.2\",\"reasoning\":\"high\"}}]}},\"canEditTeam\":true}"
}
],
"structuredContent": {
"personal": {
"revision": "0",
"binding": null
},
"team": {
"revision": "0",
"binding": null
},
"effective": {
"origin": "builtin_fallback",
"presetVersionId": null,
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
}
},
"canEditTeam": true
}
}
```
Next permitted action: Read the current personal default revision before the guarded update.
**Example requests**
- “/semel inspect the exact saved reviewer cascade preset”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `cascade_default_set`, `cascade_preset_get`.
---
### cascade_default_set
Set or reset the caller personal default, or the workspace-owner team default, to one exact immutable preset version for future projects.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:configure`, `skills:read`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `audience` — "personal" | "team"; required. Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: "personal", "team".
- `expectedRevision` — string; required; minimum length 1; maximum length 20. Optimistic concurrency value copied from the latest preset, default, or project configuration read. Accepted length or value is 1 through 20, inclusive.
- `presetVersionId` — JSON value; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available. Minimum accepted length or value is 1.
- `presetVersionId (anyOf branch 1)` — string; required; minimum length 1.
- `presetVersionId (anyOf branch 2)` — null; required.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"audience": {
"type": "string",
"enum": [
"personal",
"team"
],
"description": "Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: \"personal\", \"team\"."
},
"expectedRevision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Optimistic concurrency value copied from the latest preset, default, or project configuration read. Accepted length or value is 1 through 20, inclusive."
},
"presetVersionId": {
"anyOf": [
{
"type": "string",
"minLength": 1
},
{
"type": "null"
}
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available. 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": [
"audience",
"expectedRevision",
"presetVersionId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"audience": "personal",
"expectedRevision": "0",
"presetVersionId": "cpv_recipe_checkout_1",
"idempotencyKey": "recipe-cascade-default-set-v1"
}
```
**Binding template**
```json
{
"audience": "personal",
"expectedRevision": "{{personalDefaultRevision}}",
"presetVersionId": "{{cascadePresetVersionId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `operationId` — string; required. Stable identifier for this mutation attempt and its durable idempotent receipt.
- `binding` — JSON value; required. Current exact preset binding after the default mutation; null means the default is reset. A null value explicitly means no current value is available.
- `binding (anyOf branch 1)` — object; required.
- `binding (anyOf branch 1).id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `binding (anyOf branch 1).audience` — "personal" | "team"; required. Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: "personal", "team".
- `binding (anyOf branch 1).ownerUserId` — string | null; required. Accountable owner of a personal reviewer skill; null identifies a workspace-team skill. A null value explicitly means no current value is available.
- `binding (anyOf branch 1).revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `binding (anyOf branch 1).presetId` — string; required. Stable cascade preset identifier returned by an exact preset save, list, or read.
- `binding (anyOf branch 1).presetVersionId` — string; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset.
- `binding (anyOf branch 1).presetName` — string; required. Human-readable name of the exact preset currently bound as a default.
- `binding (anyOf branch 1).updatedAt` — string; required. RFC 3339 timestamp when this record was last updated.
- `binding (anyOf branch 2)` — null; required.
- `effective` — object; required. Exact cascade selection that a newly created project would inherit after this operation.
- `effective.origin` — "project" | "personal_default" | "team_default" | "builtin_fallback" | "explicit_override"; required. Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: "project", "personal_default", "team_default", "builtin_fallback", "explicit_override".
- `effective.presetVersionId` — string | null; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available.
- `effective.payload` — object; required. Complete ordered cascade selection preserved in this immutable preset or configuration version.
- `effective.payload.schemaVersion` — constant 1; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1.
- `effective.payload.occurrences` — array; required; minimum items 1; maximum items 20. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `effective.payload.occurrences[]` — object; required.
- `effective.payload.occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `effective.payload.occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `effective.payload.occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `effective.payload.occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `effective.payload.occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `effective.payload.occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `effective.payload.occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `effective.payload.occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `effective.payload.occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `effective.payload.occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `effective.payload.occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `effective.payload.occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `effective.payload.occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `effective.payload.occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `effective.payload.occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `effective.payload.occurrences[].model` — object; required. Optional model name declared by the harness.
- `effective.payload.occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `effective.payload.occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `effective.payload.occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `effective.payload.occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `effective.payload.occurrences[].model.reasoning (anyOf branch 2)` — null; required.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"operationId": {
"type": "string",
"description": "Stable identifier for this mutation attempt and its durable idempotent receipt."
},
"binding": {
"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."
},
"audience": {
"type": "string",
"enum": [
"personal",
"team"
],
"description": "Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: \"personal\", \"team\"."
},
"ownerUserId": {
"type": [
"string",
"null"
],
"description": "Accountable owner of a personal reviewer skill; null identifies a workspace-team skill. A null value explicitly means no current value is available."
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"presetId": {
"type": "string",
"description": "Stable cascade preset identifier returned by an exact preset save, list, or read."
},
"presetVersionId": {
"type": "string",
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset."
},
"presetName": {
"type": "string",
"description": "Human-readable name of the exact preset currently bound as a default."
},
"updatedAt": {
"type": "string",
"description": "RFC 3339 timestamp when this record was last updated."
}
},
"required": [
"id",
"audience",
"ownerUserId",
"revision",
"presetId",
"presetVersionId",
"presetName",
"updatedAt"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Current exact preset binding after the default mutation; null means the default is reset. A null value explicitly means no current value is available."
},
"effective": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"enum": [
"project",
"personal_default",
"team_default",
"builtin_fallback",
"explicit_override"
],
"description": "Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: \"project\", \"personal_default\", \"team_default\", \"builtin_fallback\", \"explicit_override\"."
},
"presetVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available."
},
"payload": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 1,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"schemaVersion",
"occurrences"
],
"additionalProperties": false,
"description": "Complete ordered cascade selection preserved in this immutable preset or configuration version."
}
},
"required": [
"origin",
"presetVersionId",
"payload"
],
"additionalProperties": false,
"description": "Exact cascade selection that a newly created project would inherit after this operation."
}
},
"required": [
"operationId",
"binding",
"effective"
],
"additionalProperties": false
}
```
**Example structured result (cascade-default)**
```json
{
"operationId": "example",
"binding": {
"id": "record_fixture_01",
"audience": "personal",
"ownerUserId": "example",
"revision": "1",
"presetId": "example",
"presetVersionId": "cpv_recipe_checkout_1",
"presetName": "example",
"updatedAt": "example"
},
"effective": {
"origin": "personal_default",
"presetVersionId": "cpv_recipe_checkout_1",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
}
}
}
```
Bindings: defaultPresetVersionId from structuredContent.binding.presetVersionId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"operationId\":\"example\",\"binding\":{\"id\":\"record_fixture_01\",\"audience\":\"personal\",\"ownerUserId\":\"example\",\"revision\":\"1\",\"presetId\":\"example\",\"presetVersionId\":\"cpv_recipe_checkout_1\",\"presetName\":\"example\",\"updatedAt\":\"example\"},\"effective\":{\"origin\":\"personal_default\",\"presetVersionId\":\"cpv_recipe_checkout_1\",\"payload\":{\"schemaVersion\":1,\"occurrences\":[{\"occurrenceId\":\"checkout-reliability\",\"reviewerRef\":{\"kind\":\"custom\",\"skillId\":\"skl_recipe_checkout\",\"versionId\":\"skv_recipe_checkout_1\"},\"label\":\"Checkout reliability\",\"enabled\":true,\"skill\":{\"version\":\"skv_recipe_checkout_1\",\"sha256\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\"},\"model\":{\"provider\":\"openai\",\"model\":\"gpt-5.2\",\"reasoning\":\"high\"}}]}}}"
}
],
"structuredContent": {
"operationId": "example",
"binding": {
"id": "record_fixture_01",
"audience": "personal",
"ownerUserId": "example",
"revision": "1",
"presetId": "example",
"presetVersionId": "cpv_recipe_checkout_1",
"presetName": "example",
"updatedAt": "example"
},
"effective": {
"origin": "personal_default",
"presetVersionId": "cpv_recipe_checkout_1",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
}
}
}
}
```
Next permitted action: Preview the exact preset version against the project revision before saving it.
**Example requests**
- “/semel save this exact published reviewer sequence as my default”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`, `CONFLICTING_IDEMPOTENCY_REPLAY`, `VALIDATION_FAILED`.
Related operations: `cascade_preset_get`, `cascade_preset_save`.
---
### cascade_preset_get
Inspect one currently authorized preset and one exact immutable saved version without loading reviewer source bytes.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `skills:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `presetId` — string; required; minimum length 1. Stable cascade preset identifier returned by an exact preset save, list, or read. Minimum accepted length or value is 1.
- `versionId` — string; optional; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"presetId": {
"type": "string",
"minLength": 1,
"description": "Stable cascade preset identifier returned by an exact preset save, list, or read. Minimum accepted length or value is 1."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1."
}
},
"required": [
"presetId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"presetId": "cpr_recipe_checkout",
"versionId": "cpv_recipe_checkout_1"
}
```
**Binding template**
```json
{
"presetId": "{{cascadePresetId}}",
"versionId": "{{cascadePresetVersionId}}"
}
```
**Returns**
- `preset` — object; required. Authorized cascade preset metadata and its exact immutable selected version.
- `preset.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `preset.audience` — "personal" | "team"; required. Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: "personal", "team".
- `preset.ownerUserId` — string | null; required. Accountable owner of a personal reviewer skill; null identifies a workspace-team skill. A null value explicitly means no current value is available.
- `preset.name` — string; required. Human-readable name displayed in Semel.
- `preset.revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `preset.archivedAt` — string | null; required. RFC 3339 archive timestamp; null means the preset remains available for new selection. A null value explicitly means no current value is available.
- `preset.currentVersion` — object; required. Current immutable version of this cascade preset, including its exact reviewer pins.
- `preset.currentVersion.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `preset.currentVersion.presetId` — string; required. Stable cascade preset identifier returned by an exact preset save, list, or read.
- `preset.currentVersion.versionNumber` — string; required; minimum length 1; maximum length 20. Positive monotonic publication number assigned to this immutable reviewer-skill version. Accepted length or value is 1 through 20, inclusive.
- `preset.currentVersion.payload` — object; required. Complete ordered cascade selection preserved in this immutable preset or configuration version.
- `preset.currentVersion.payload.schemaVersion` — constant 1; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1.
- `preset.currentVersion.payload.occurrences` — array; required; minimum items 1; maximum items 20. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `preset.currentVersion.payload.occurrences[]` — object; required.
- `preset.currentVersion.payload.occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `preset.currentVersion.payload.occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `preset.currentVersion.payload.occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `preset.currentVersion.payload.occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `preset.currentVersion.payload.occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `preset.currentVersion.payload.occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `preset.currentVersion.payload.occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `preset.currentVersion.payload.occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `preset.currentVersion.payload.occurrences[].model` — object; required. Optional model name declared by the harness.
- `preset.currentVersion.payload.occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `preset.currentVersion.payload.occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `preset.currentVersion.payload.occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `preset.currentVersion.payload.occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `preset.currentVersion.payload.occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `preset.currentVersion.createdById` — string; required. Semel user identifier recorded as the initiating creator.
- `preset.currentVersion.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `preset.canEdit` — boolean; required. Whether the current authenticated principal may edit this reviewer skill.
- `preset.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `preset.updatedAt` — string; required. RFC 3339 timestamp when this record was last updated.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"preset": {
"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."
},
"audience": {
"type": "string",
"enum": [
"personal",
"team"
],
"description": "Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: \"personal\", \"team\"."
},
"ownerUserId": {
"type": [
"string",
"null"
],
"description": "Accountable owner of a personal reviewer skill; null identifies a workspace-team skill. A null value explicitly means no current value is available."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"archivedAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 archive timestamp; null means the preset remains available for new selection. A null value explicitly means no current value is available."
},
"currentVersion": {
"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."
},
"presetId": {
"type": "string",
"description": "Stable cascade preset identifier returned by an exact preset save, list, or read."
},
"versionNumber": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Positive monotonic publication number assigned to this immutable reviewer-skill version. Accepted length or value is 1 through 20, inclusive."
},
"payload": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 1,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"schemaVersion",
"occurrences"
],
"additionalProperties": false,
"description": "Complete ordered cascade selection preserved in this immutable preset or configuration version."
},
"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",
"presetId",
"versionNumber",
"payload",
"createdById",
"createdAt"
],
"additionalProperties": false,
"description": "Current immutable version of this cascade preset, including its exact reviewer pins."
},
"canEdit": {
"type": "boolean",
"description": "Whether the current authenticated principal may edit this reviewer skill."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
},
"updatedAt": {
"type": "string",
"description": "RFC 3339 timestamp when this record was last updated."
}
},
"required": [
"id",
"audience",
"ownerUserId",
"name",
"revision",
"archivedAt",
"currentVersion",
"canEdit",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "Authorized cascade preset metadata and its exact immutable selected version."
}
},
"required": [
"preset"
],
"additionalProperties": false
}
```
**Example structured result (cascade-preset)**
```json
{
"preset": {
"id": "cpr_recipe_checkout",
"audience": "personal",
"ownerUserId": "example",
"name": "Checkout reliability",
"revision": "1",
"archivedAt": "example",
"currentVersion": {
"id": "cpv_recipe_checkout_1",
"presetId": "cpr_recipe_checkout",
"versionNumber": "1",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
},
"createdById": "example",
"createdAt": "example"
},
"canEdit": false,
"createdAt": "example",
"updatedAt": "example"
}
}
```
Bindings: inspectedPresetVersionId from structuredContent.preset.currentVersion.id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"preset\":{\"id\":\"cpr_recipe_checkout\",\"audience\":\"personal\",\"ownerUserId\":\"example\",\"name\":\"Checkout reliability\",\"revision\":\"1\",\"archivedAt\":\"example\",\"currentVersion\":{\"id\":\"cpv_recipe_checkout_1\",\"presetId\":\"cpr_recipe_checkout\",\"versionNumber\":\"1\",\"payload\":{\"schemaVersion\":1,\"occurrences\":[{\"occurrenceId\":\"checkout-reliability\",\"reviewerRef\":{\"kind\":\"custom\",\"skillId\":\"skl_recipe_checkout\",\"versionId\":\"skv_recipe_checkout_1\"},\"label\":\"Checkout reliability\",\"enabled\":true,\"skill\":{\"version\":\"skv_recipe_checkout_1\",\"sha256\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\"},\"model\":{\"provider\":\"openai\",\"model\":\"gpt-5.2\",\"reasoning\":\"high\"}}]},\"createdById\":\"example\",\"createdAt\":\"example\"},\"canEdit\":false,\"createdAt\":\"example\",\"updatedAt\":\"example\"}}"
}
],
"structuredContent": {
"preset": {
"id": "cpr_recipe_checkout",
"audience": "personal",
"ownerUserId": "example",
"name": "Checkout reliability",
"revision": "1",
"archivedAt": "example",
"currentVersion": {
"id": "cpv_recipe_checkout_1",
"presetId": "cpr_recipe_checkout",
"versionNumber": "1",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
},
"createdById": "example",
"createdAt": "example"
},
"canEdit": false,
"createdAt": "example",
"updatedAt": "example"
}
}
}
```
Next permitted action: Set the personal default to that exact inspected version.
**Example requests**
- “/semel inspect the exact saved reviewer cascade preset”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `cascade_preset_save`, `cascade_default_set`.
---
### cascade_preset_save
Create or version a personal or team preset from exact published reviewer pins; this does not change defaults, projects, or start a review.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:configure`, `skills:read`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `presetId` — string; optional; minimum length 1. Stable cascade preset identifier returned by an exact preset save, list, or read. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
- `name` — string; required; minimum length 1. Human-readable name displayed in Semel. Minimum accepted length or value is 1.
- `audience` — "personal" | "team"; required. Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: "personal", "team".
- `expectedRevision` — string; optional; minimum length 1; maximum length 20. Optimistic concurrency value copied from the latest preset, default, or project configuration read. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 20, inclusive.
- `occurrences` — array; required; minimum items 1; maximum items 20. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `occurrences[]` — object; required.
- `occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `occurrences[].model` — object; required. Optional model name declared by the harness.
- `occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"presetId": {
"type": "string",
"minLength": 1,
"description": "Stable cascade preset identifier returned by an exact preset save, list, or read. Omit the field when it does not apply; omission is distinct from an empty value. 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."
},
"audience": {
"type": "string",
"enum": [
"personal",
"team"
],
"description": "Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: \"personal\", \"team\"."
},
"expectedRevision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Optimistic concurrency value copied from the latest preset, default, or project configuration read. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 20, inclusive."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"name",
"audience",
"occurrences",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"name": "Checkout reliability cascade",
"audience": "personal",
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
],
"idempotencyKey": "recipe-cascade-preset-save-v1"
}
```
**Binding template**
```json
{
"name": "Checkout reliability cascade",
"audience": "personal",
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "{{skillId}}",
"versionId": "{{publishedSkillVersionId}}"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "{{publishedSkillVersionId}}",
"sha256": "{{publishedSkillHash}}"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
],
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `operationId` — string; required. Stable identifier for this mutation attempt and its durable idempotent receipt.
- `preset` — object; required. Authorized cascade preset metadata and its exact immutable selected version.
- `preset.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `preset.audience` — "personal" | "team"; required. Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: "personal", "team".
- `preset.ownerUserId` — string | null; required. Accountable owner of a personal reviewer skill; null identifies a workspace-team skill. A null value explicitly means no current value is available.
- `preset.name` — string; required. Human-readable name displayed in Semel.
- `preset.revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `preset.archivedAt` — string | null; required. RFC 3339 archive timestamp; null means the preset remains available for new selection. A null value explicitly means no current value is available.
- `preset.currentVersion` — object; required. Current immutable version of this cascade preset, including its exact reviewer pins.
- `preset.currentVersion.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `preset.currentVersion.presetId` — string; required. Stable cascade preset identifier returned by an exact preset save, list, or read.
- `preset.currentVersion.versionNumber` — string; required; minimum length 1; maximum length 20. Positive monotonic publication number assigned to this immutable reviewer-skill version. Accepted length or value is 1 through 20, inclusive.
- `preset.currentVersion.payload` — object; required. Complete ordered cascade selection preserved in this immutable preset or configuration version.
- `preset.currentVersion.payload.schemaVersion` — constant 1; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1.
- `preset.currentVersion.payload.occurrences` — array; required; minimum items 1; maximum items 20. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `preset.currentVersion.payload.occurrences[]` — object; required.
- `preset.currentVersion.payload.occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `preset.currentVersion.payload.occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `preset.currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `preset.currentVersion.payload.occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `preset.currentVersion.payload.occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `preset.currentVersion.payload.occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `preset.currentVersion.payload.occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `preset.currentVersion.payload.occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `preset.currentVersion.payload.occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `preset.currentVersion.payload.occurrences[].model` — object; required. Optional model name declared by the harness.
- `preset.currentVersion.payload.occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `preset.currentVersion.payload.occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `preset.currentVersion.payload.occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `preset.currentVersion.payload.occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `preset.currentVersion.payload.occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `preset.currentVersion.createdById` — string; required. Semel user identifier recorded as the initiating creator.
- `preset.currentVersion.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `preset.canEdit` — boolean; required. Whether the current authenticated principal may edit this reviewer skill.
- `preset.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `preset.updatedAt` — string; required. RFC 3339 timestamp when this record was last updated.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"operationId": {
"type": "string",
"description": "Stable identifier for this mutation attempt and its durable idempotent receipt."
},
"preset": {
"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."
},
"audience": {
"type": "string",
"enum": [
"personal",
"team"
],
"description": "Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: \"personal\", \"team\"."
},
"ownerUserId": {
"type": [
"string",
"null"
],
"description": "Accountable owner of a personal reviewer skill; null identifies a workspace-team skill. A null value explicitly means no current value is available."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"archivedAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 archive timestamp; null means the preset remains available for new selection. A null value explicitly means no current value is available."
},
"currentVersion": {
"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."
},
"presetId": {
"type": "string",
"description": "Stable cascade preset identifier returned by an exact preset save, list, or read."
},
"versionNumber": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Positive monotonic publication number assigned to this immutable reviewer-skill version. Accepted length or value is 1 through 20, inclusive."
},
"payload": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 1,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"schemaVersion",
"occurrences"
],
"additionalProperties": false,
"description": "Complete ordered cascade selection preserved in this immutable preset or configuration version."
},
"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",
"presetId",
"versionNumber",
"payload",
"createdById",
"createdAt"
],
"additionalProperties": false,
"description": "Current immutable version of this cascade preset, including its exact reviewer pins."
},
"canEdit": {
"type": "boolean",
"description": "Whether the current authenticated principal may edit this reviewer skill."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
},
"updatedAt": {
"type": "string",
"description": "RFC 3339 timestamp when this record was last updated."
}
},
"required": [
"id",
"audience",
"ownerUserId",
"name",
"revision",
"archivedAt",
"currentVersion",
"canEdit",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "Authorized cascade preset metadata and its exact immutable selected version."
}
},
"required": [
"operationId",
"preset"
],
"additionalProperties": false
}
```
**Example structured result (cascade-preset-saved)**
```json
{
"operationId": "example",
"preset": {
"id": "cpr_recipe_checkout",
"audience": "personal",
"ownerUserId": "example",
"name": "Checkout reliability cascade",
"revision": "1",
"archivedAt": "example",
"currentVersion": {
"id": "cpv_recipe_checkout_1",
"presetId": "example",
"versionNumber": "1",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
},
"createdById": "example",
"createdAt": "example"
},
"canEdit": false,
"createdAt": "example",
"updatedAt": "example"
}
}
```
Bindings: cascadePresetId from structuredContent.preset.id; cascadePresetVersionId from structuredContent.preset.currentVersion.id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"operationId\":\"example\",\"preset\":{\"id\":\"cpr_recipe_checkout\",\"audience\":\"personal\",\"ownerUserId\":\"example\",\"name\":\"Checkout reliability cascade\",\"revision\":\"1\",\"archivedAt\":\"example\",\"currentVersion\":{\"id\":\"cpv_recipe_checkout_1\",\"presetId\":\"example\",\"versionNumber\":\"1\",\"payload\":{\"schemaVersion\":1,\"occurrences\":[{\"occurrenceId\":\"checkout-reliability\",\"reviewerRef\":{\"kind\":\"custom\",\"skillId\":\"skl_recipe_checkout\",\"versionId\":\"skv_recipe_checkout_1\"},\"label\":\"Checkout reliability\",\"enabled\":true,\"skill\":{\"version\":\"skv_recipe_checkout_1\",\"sha256\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\"},\"model\":{\"provider\":\"openai\",\"model\":\"gpt-5.2\",\"reasoning\":\"high\"}}]},\"createdById\":\"example\",\"createdAt\":\"example\"},\"canEdit\":false,\"createdAt\":\"example\",\"updatedAt\":\"example\"}}"
}
],
"structuredContent": {
"operationId": "example",
"preset": {
"id": "cpr_recipe_checkout",
"audience": "personal",
"ownerUserId": "example",
"name": "Checkout reliability cascade",
"revision": "1",
"archivedAt": "example",
"currentVersion": {
"id": "cpv_recipe_checkout_1",
"presetId": "example",
"versionNumber": "1",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
},
"createdById": "example",
"createdAt": "example"
},
"canEdit": false,
"createdAt": "example",
"updatedAt": "example"
}
}
}
```
Next permitted action: Inspect the exact immutable preset version before selecting it as a default.
**Example requests**
- “/semel save this exact published reviewer sequence as my default”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`, `CONFLICTING_IDEMPOTENCY_REPLAY`, `VALIDATION_FAILED`.
Related operations: `cascade_preset_get`, `cascade_default_set`.
---
### project_cascade_get
Inspect the exact current reviewer cascade and optimistic revision for one project before previewing or saving a change.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `skills:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier whose exact current reviewer cascade should be inspected.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier whose exact current reviewer cascade should be inspected."
}
},
"required": [
"projectId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}"
}
```
**Returns**
- `value (anyOf branch 1)` — object; optional.
- `value (anyOf branch 1).kind` — constant "versioned"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "versioned".
- `value (anyOf branch 1).projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `value (anyOf branch 1).revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `value (anyOf branch 1).currentVersion` — object; required. Current immutable version of this cascade preset, including its exact reviewer pins.
- `value (anyOf branch 1).currentVersion.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `value (anyOf branch 1).currentVersion.revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `value (anyOf branch 1).currentVersion.origin` — "project" | "personal_default" | "team_default" | "builtin_fallback" | "explicit_override"; required. Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: "project", "personal_default", "team_default", "builtin_fallback", "explicit_override".
- `value (anyOf branch 1).currentVersion.presetVersionId` — string | null; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available.
- `value (anyOf branch 1).currentVersion.sourcePresetId` — string | null; optional. Preset identifier from which this project configuration was explicitly adopted; null identifies a manual selection. 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.
- `value (anyOf branch 1).currentVersion.payload` — object; required. Complete ordered cascade selection preserved in this immutable preset or configuration version.
- `value (anyOf branch 1).currentVersion.payload.schemaVersion` — constant 1; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1.
- `value (anyOf branch 1).currentVersion.payload.occurrences` — array; required; minimum items 1. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `value (anyOf branch 1).currentVersion.payload.occurrences[]` — object; required.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `value (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `value (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `value (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].model` — object; required. Optional model name declared by the harness.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `value (anyOf branch 1).currentVersion.payload.occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `value (anyOf branch 1).currentVersion.createdById` — string; required. Semel user identifier recorded as the initiating creator.
- `value (anyOf branch 1).currentVersion.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `value (anyOf branch 1).canEdit` — boolean; required. Whether the current authenticated principal may edit this reviewer skill.
- `value (anyOf branch 2)` — object; optional.
- `value (anyOf branch 2).kind` — constant "legacy"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "legacy".
- `value (anyOf branch 2).projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `value (anyOf branch 2).revision` — constant "0"; required. Indexed repository revision used for this evidence result. This branch always uses "0".
- `value (anyOf branch 2).steps` — array; required. Configured cascade steps in execution order with their latest run state. An empty array explicitly means no matching items.
- `value (anyOf branch 2).steps[]` — object; required.
- `value (anyOf branch 2).steps[].stepId` — string; required. Identifier of one legacy reviewer-cascade step returned by the current project configuration.
- `value (anyOf branch 2).steps[].position` — integer; required; minimum 0. Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer.
- `value (anyOf branch 2).steps[].reviewer` — string; required. Reviewer role responsible for this submitted result.
- `value (anyOf branch 2).steps[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `value (anyOf branch 2).steps[].provider` — string | null; required. Resolved inference provider preserved in the immutable reviewer execution pin. A null value explicitly means no current value is available.
- `value (anyOf branch 2).steps[].model` — string | null; required. Optional model name declared by the harness. A null value explicitly means no current value is available.
- `value (anyOf branch 2).steps[].reasoning` — string | null; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available.
- `value (anyOf branch 2).canEdit` — boolean; required. Whether the current authenticated principal may edit this reviewer skill.
**Complete raw result schema**
```json
{
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "versioned",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"versioned\"."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"currentVersion": {
"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."
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"origin": {
"type": "string",
"enum": [
"project",
"personal_default",
"team_default",
"builtin_fallback",
"explicit_override"
],
"description": "Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: \"project\", \"personal_default\", \"team_default\", \"builtin_fallback\", \"explicit_override\"."
},
"presetVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available."
},
"sourcePresetId": {
"type": [
"string",
"null"
],
"description": "Preset identifier from which this project configuration was explicitly adopted; null identifies a manual selection. 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."
},
"payload": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 1,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"schemaVersion",
"occurrences"
],
"additionalProperties": false,
"description": "Complete ordered cascade selection preserved in this immutable preset or configuration version."
},
"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",
"revision",
"origin",
"presetVersionId",
"payload",
"createdById",
"createdAt"
],
"additionalProperties": false,
"description": "Current immutable version of this cascade preset, including its exact reviewer pins."
},
"canEdit": {
"type": "boolean",
"description": "Whether the current authenticated principal may edit this reviewer skill."
}
},
"required": [
"kind",
"projectId",
"revision",
"currentVersion",
"canEdit"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "legacy",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"legacy\"."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"revision": {
"type": "string",
"const": "0",
"description": "Indexed repository revision used for this evidence result. This branch always uses \"0\"."
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stepId": {
"type": "string",
"description": "Identifier of one legacy reviewer-cascade step returned by the current project configuration."
},
"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."
},
"reviewer": {
"type": "string",
"description": "Reviewer role responsible for this submitted result."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"provider": {
"type": [
"string",
"null"
],
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. A null value explicitly means no current value is available."
},
"model": {
"type": [
"string",
"null"
],
"description": "Optional model name declared by the harness. A null value explicitly means no current value is available."
},
"reasoning": {
"type": [
"string",
"null"
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available."
}
},
"required": [
"stepId",
"position",
"reviewer",
"enabled",
"provider",
"model",
"reasoning"
],
"additionalProperties": false
},
"description": "Configured cascade steps in execution order with their latest run state. An empty array explicitly means no matching items."
},
"canEdit": {
"type": "boolean",
"description": "Whether the current authenticated principal may edit this reviewer skill."
}
},
"required": [
"kind",
"projectId",
"revision",
"steps",
"canEdit"
],
"additionalProperties": false
}
]
}
```
**Example structured result (project-cascade)**
```json
{
"kind": "versioned",
"projectId": "prj_fixture_checkout",
"revision": "1",
"currentVersion": {
"id": "pcv_recipe_checkout_1",
"revision": "1",
"origin": "explicit_override",
"presetVersionId": "cpv_recipe_checkout_1",
"sourcePresetId": "cpr_recipe_checkout",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
},
"createdById": "usr_recipe_owner",
"createdAt": "2026-09-07T16:00:00.000Z"
},
"canEdit": true
}
```
Bindings: projectCascadeKind from structuredContent.kind; projectCascadeRevision from structuredContent.revision.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"kind\":\"versioned\",\"projectId\":\"prj_fixture_checkout\",\"revision\":\"1\",\"currentVersion\":{\"id\":\"pcv_recipe_checkout_1\",\"revision\":\"1\",\"origin\":\"explicit_override\",\"presetVersionId\":\"cpv_recipe_checkout_1\",\"sourcePresetId\":\"cpr_recipe_checkout\",\"payload\":{\"schemaVersion\":1,\"occurrences\":[{\"occurrenceId\":\"checkout-reliability\",\"reviewerRef\":{\"kind\":\"custom\",\"skillId\":\"skl_recipe_checkout\",\"versionId\":\"skv_recipe_checkout_1\"},\"label\":\"Checkout reliability\",\"enabled\":true,\"skill\":{\"version\":\"skv_recipe_checkout_1\",\"sha256\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\"},\"model\":{\"provider\":\"openai\",\"model\":\"gpt-5.2\",\"reasoning\":\"high\"}}]},\"createdById\":\"usr_recipe_owner\",\"createdAt\":\"2026-09-07T16:00:00.000Z\"},\"canEdit\":true}"
}
],
"structuredContent": {
"kind": "versioned",
"projectId": "prj_fixture_checkout",
"revision": "1",
"currentVersion": {
"id": "pcv_recipe_checkout_1",
"revision": "1",
"origin": "explicit_override",
"presetVersionId": "cpv_recipe_checkout_1",
"sourcePresetId": "cpr_recipe_checkout",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
},
"createdById": "usr_recipe_owner",
"createdAt": "2026-09-07T16:00:00.000Z"
},
"canEdit": true
}
}
```
Next permitted action: Use the returned revision for an exact preview; read legacy step IDs only when kind is legacy.
**Example requests**
- “/semel inspect the exact saved reviewer cascade preset”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `project_cascade_preview`, `project_cascade_save`.
---
### project_cascade_preview
Resolve a preset, explicit override, or reset into exact immutable reviewer pins and validate it before saving.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:configure`, `skills:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `expectedRevision` — string; required; minimum length 1; maximum length 20. Optimistic concurrency value copied from the latest preset, default, or project configuration read. Accepted length or value is 1 through 20, inclusive.
- `candidate` — JSON value; required. Proposed project cascade source to resolve and validate: an immutable preset, explicit occurrence override, or default reset.
- `candidate (anyOf branch 1)` — object; required.
- `candidate (anyOf branch 1).kind` — constant "preset"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "preset".
- `candidate (anyOf branch 1).presetVersionId` — string; required; minimum length 1. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. Minimum accepted length or value is 1.
- `candidate (anyOf branch 2)` — object; required.
- `candidate (anyOf branch 2).kind` — constant "override"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "override".
- `candidate (anyOf branch 2).occurrences` — array; required; minimum items 1; maximum items 20. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `candidate (anyOf branch 2).occurrences[]` — object; required.
- `candidate (anyOf branch 2).occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `candidate (anyOf branch 2).occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `candidate (anyOf branch 2).occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `candidate (anyOf branch 2).occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `candidate (anyOf branch 2).occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `candidate (anyOf branch 2).occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `candidate (anyOf branch 2).occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `candidate (anyOf branch 2).occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `candidate (anyOf branch 2).occurrences[].model` — object; required. Optional model name declared by the harness.
- `candidate (anyOf branch 2).occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `candidate (anyOf branch 2).occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `candidate (anyOf branch 2).occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `candidate (anyOf branch 2).occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `candidate (anyOf branch 2).occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `candidate (anyOf branch 3)` — object; required.
- `candidate (anyOf branch 3).kind` — constant "reset"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "reset".
- `candidate (anyOf branch 3).expectedSelection` — object; optional. Exact default selection returned by preview; include it when saving a reset so an unseen default change cannot be substituted. Omit the field when it does not apply; omission is distinct from an empty value.
- `candidate (anyOf branch 3).expectedSelection.origin` — "project" | "personal_default" | "team_default" | "builtin_fallback" | "explicit_override"; required. Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: "project", "personal_default", "team_default", "builtin_fallback", "explicit_override".
- `candidate (anyOf branch 3).expectedSelection.presetVersionId` — string | null; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available.
- `candidate (anyOf branch 3).expectedSelection.payloadSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the canonical submitted payload.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"expectedRevision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Optimistic concurrency value copied from the latest preset, default, or project configuration read. Accepted length or value is 1 through 20, inclusive."
},
"candidate": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "preset",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"preset\"."
},
"presetVersionId": {
"type": "string",
"minLength": 1,
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. Minimum accepted length or value is 1."
}
},
"required": [
"kind",
"presetVersionId"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "override",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"override\"."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"kind",
"occurrences"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "reset",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"reset\"."
},
"expectedSelection": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"enum": [
"project",
"personal_default",
"team_default",
"builtin_fallback",
"explicit_override"
],
"description": "Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: \"project\", \"personal_default\", \"team_default\", \"builtin_fallback\", \"explicit_override\"."
},
"presetVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available."
},
"payloadSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest of the canonical submitted payload."
}
},
"required": [
"origin",
"presetVersionId",
"payloadSha256"
],
"additionalProperties": false,
"description": "Exact default selection returned by preview; include it when saving a reset so an unseen default change cannot be substituted. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"kind"
],
"additionalProperties": false
}
],
"description": "Proposed project cascade source to resolve and validate: an immutable preset, explicit occurrence override, or default reset."
}
},
"required": [
"projectId",
"expectedRevision",
"candidate"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"expectedRevision": "1",
"candidate": {
"kind": "preset",
"presetVersionId": "cpv_recipe_checkout_1"
}
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"expectedRevision": "{{projectCascadeRevision}}",
"candidate": {
"kind": "preset",
"presetVersionId": "{{cascadePresetVersionId}}"
}
}
```
**Returns**
- `projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `expectedRevision` — string; required; minimum length 1; maximum length 20. Optimistic concurrency value copied from the latest preset, default, or project configuration read. Accepted length or value is 1 through 20, inclusive.
- `before` — JSON value; required. Exact earlier reviewer-skill revision selected as the before side of this comparison.
- `before (anyOf branch 1)` — object; required.
- `before (anyOf branch 1).kind` — constant "versioned"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "versioned".
- `before (anyOf branch 1).projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `before (anyOf branch 1).revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `before (anyOf branch 1).currentVersion` — object; required. Current immutable version of this cascade preset, including its exact reviewer pins.
- `before (anyOf branch 1).currentVersion.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `before (anyOf branch 1).currentVersion.revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `before (anyOf branch 1).currentVersion.origin` — "project" | "personal_default" | "team_default" | "builtin_fallback" | "explicit_override"; required. Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: "project", "personal_default", "team_default", "builtin_fallback", "explicit_override".
- `before (anyOf branch 1).currentVersion.presetVersionId` — string | null; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available.
- `before (anyOf branch 1).currentVersion.sourcePresetId` — string | null; optional. Preset identifier from which this project configuration was explicitly adopted; null identifies a manual selection. 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.
- `before (anyOf branch 1).currentVersion.payload` — object; required. Complete ordered cascade selection preserved in this immutable preset or configuration version.
- `before (anyOf branch 1).currentVersion.payload.schemaVersion` — constant 1; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1.
- `before (anyOf branch 1).currentVersion.payload.occurrences` — array; required; minimum items 1. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `before (anyOf branch 1).currentVersion.payload.occurrences[]` — object; required.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `before (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `before (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `before (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].model` — object; required. Optional model name declared by the harness.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `before (anyOf branch 1).currentVersion.payload.occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `before (anyOf branch 1).currentVersion.createdById` — string; required. Semel user identifier recorded as the initiating creator.
- `before (anyOf branch 1).currentVersion.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `before (anyOf branch 1).canEdit` — boolean; required. Whether the current authenticated principal may edit this reviewer skill.
- `before (anyOf branch 2)` — object; required.
- `before (anyOf branch 2).kind` — constant "legacy"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "legacy".
- `before (anyOf branch 2).projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `before (anyOf branch 2).revision` — constant "0"; required. Indexed repository revision used for this evidence result. This branch always uses "0".
- `before (anyOf branch 2).steps` — array; required. Configured cascade steps in execution order with their latest run state. An empty array explicitly means no matching items.
- `before (anyOf branch 2).steps[]` — object; required.
- `before (anyOf branch 2).steps[].stepId` — string; required. Identifier of one legacy reviewer-cascade step returned by the current project configuration.
- `before (anyOf branch 2).steps[].position` — integer; required; minimum 0. Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer.
- `before (anyOf branch 2).steps[].reviewer` — string; required. Reviewer role responsible for this submitted result.
- `before (anyOf branch 2).steps[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `before (anyOf branch 2).steps[].provider` — string | null; required. Resolved inference provider preserved in the immutable reviewer execution pin. A null value explicitly means no current value is available.
- `before (anyOf branch 2).steps[].model` — string | null; required. Optional model name declared by the harness. A null value explicitly means no current value is available.
- `before (anyOf branch 2).steps[].reasoning` — string | null; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available.
- `before (anyOf branch 2).canEdit` — boolean; required. Whether the current authenticated principal may edit this reviewer skill.
- `after` — object; required. Exact later reviewer-skill revision selected as the after side of this comparison.
- `after.origin` — "project" | "personal_default" | "team_default" | "builtin_fallback" | "explicit_override"; required. Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: "project", "personal_default", "team_default", "builtin_fallback", "explicit_override".
- `after.presetVersionId` — string | null; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available.
- `after.payload` — object; required. Complete ordered cascade selection preserved in this immutable preset or configuration version.
- `after.payload.schemaVersion` — constant 1; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1.
- `after.payload.occurrences` — array; required; minimum items 1; maximum items 20. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `after.payload.occurrences[]` — object; required.
- `after.payload.occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `after.payload.occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `after.payload.occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `after.payload.occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `after.payload.occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `after.payload.occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `after.payload.occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `after.payload.occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `after.payload.occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `after.payload.occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `after.payload.occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `after.payload.occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `after.payload.occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `after.payload.occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `after.payload.occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `after.payload.occurrences[].model` — object; required. Optional model name declared by the harness.
- `after.payload.occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `after.payload.occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `after.payload.occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `after.payload.occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `after.payload.occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `resolvedSelection` — object; required. Exact previewed default or preset identity that Save must match before committing the project configuration.
- `resolvedSelection.origin` — "project" | "personal_default" | "team_default" | "builtin_fallback" | "explicit_override"; required. Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: "project", "personal_default", "team_default", "builtin_fallback", "explicit_override".
- `resolvedSelection.presetVersionId` — string | null; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available.
- `resolvedSelection.payloadSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the canonical submitted payload.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"expectedRevision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Optimistic concurrency value copied from the latest preset, default, or project configuration read. Accepted length or value is 1 through 20, inclusive."
},
"before": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "versioned",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"versioned\"."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"currentVersion": {
"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."
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"origin": {
"type": "string",
"enum": [
"project",
"personal_default",
"team_default",
"builtin_fallback",
"explicit_override"
],
"description": "Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: \"project\", \"personal_default\", \"team_default\", \"builtin_fallback\", \"explicit_override\"."
},
"presetVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available."
},
"sourcePresetId": {
"type": [
"string",
"null"
],
"description": "Preset identifier from which this project configuration was explicitly adopted; null identifies a manual selection. 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."
},
"payload": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 1,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"schemaVersion",
"occurrences"
],
"additionalProperties": false,
"description": "Complete ordered cascade selection preserved in this immutable preset or configuration version."
},
"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",
"revision",
"origin",
"presetVersionId",
"payload",
"createdById",
"createdAt"
],
"additionalProperties": false,
"description": "Current immutable version of this cascade preset, including its exact reviewer pins."
},
"canEdit": {
"type": "boolean",
"description": "Whether the current authenticated principal may edit this reviewer skill."
}
},
"required": [
"kind",
"projectId",
"revision",
"currentVersion",
"canEdit"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "legacy",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"legacy\"."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"revision": {
"type": "string",
"const": "0",
"description": "Indexed repository revision used for this evidence result. This branch always uses \"0\"."
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stepId": {
"type": "string",
"description": "Identifier of one legacy reviewer-cascade step returned by the current project configuration."
},
"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."
},
"reviewer": {
"type": "string",
"description": "Reviewer role responsible for this submitted result."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"provider": {
"type": [
"string",
"null"
],
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. A null value explicitly means no current value is available."
},
"model": {
"type": [
"string",
"null"
],
"description": "Optional model name declared by the harness. A null value explicitly means no current value is available."
},
"reasoning": {
"type": [
"string",
"null"
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available."
}
},
"required": [
"stepId",
"position",
"reviewer",
"enabled",
"provider",
"model",
"reasoning"
],
"additionalProperties": false
},
"description": "Configured cascade steps in execution order with their latest run state. An empty array explicitly means no matching items."
},
"canEdit": {
"type": "boolean",
"description": "Whether the current authenticated principal may edit this reviewer skill."
}
},
"required": [
"kind",
"projectId",
"revision",
"steps",
"canEdit"
],
"additionalProperties": false
}
],
"description": "Exact earlier reviewer-skill revision selected as the before side of this comparison."
},
"after": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"enum": [
"project",
"personal_default",
"team_default",
"builtin_fallback",
"explicit_override"
],
"description": "Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: \"project\", \"personal_default\", \"team_default\", \"builtin_fallback\", \"explicit_override\"."
},
"presetVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available."
},
"payload": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 1,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"schemaVersion",
"occurrences"
],
"additionalProperties": false,
"description": "Complete ordered cascade selection preserved in this immutable preset or configuration version."
}
},
"required": [
"origin",
"presetVersionId",
"payload"
],
"additionalProperties": false,
"description": "Exact later reviewer-skill revision selected as the after side of this comparison."
},
"resolvedSelection": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"enum": [
"project",
"personal_default",
"team_default",
"builtin_fallback",
"explicit_override"
],
"description": "Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: \"project\", \"personal_default\", \"team_default\", \"builtin_fallback\", \"explicit_override\"."
},
"presetVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available."
},
"payloadSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest of the canonical submitted payload."
}
},
"required": [
"origin",
"presetVersionId",
"payloadSha256"
],
"additionalProperties": false,
"description": "Exact previewed default or preset identity that Save must match before committing the project configuration."
}
},
"required": [
"projectId",
"expectedRevision",
"before",
"after",
"resolvedSelection"
],
"additionalProperties": false
}
```
**Example structured result (project-cascade-preview)**
```json
{
"projectId": "prj_fixture_checkout",
"expectedRevision": "1",
"before": {
"kind": "versioned",
"projectId": "prj_fixture_checkout",
"revision": "1",
"currentVersion": {
"id": "pcv_recipe_checkout_1",
"revision": "1",
"origin": "explicit_override",
"presetVersionId": "cpv_recipe_checkout_1",
"sourcePresetId": "cpr_recipe_checkout",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
},
"createdById": "usr_recipe_owner",
"createdAt": "2026-09-07T16:00:00.000Z"
},
"canEdit": true
},
"after": {
"origin": "project",
"presetVersionId": "cpv_recipe_checkout_1",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
}
},
"resolvedSelection": {
"origin": "project",
"presetVersionId": "cpv_recipe_checkout_1",
"payloadSha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
}
}
```
Bindings: projectCascadePayloadSha256 from structuredContent.resolvedSelection.payloadSha256.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"projectId\":\"prj_fixture_checkout\",\"expectedRevision\":\"1\",\"before\":{\"kind\":\"versioned\",\"projectId\":\"prj_fixture_checkout\",\"revision\":\"1\",\"currentVersion\":{\"id\":\"pcv_recipe_checkout_1\",\"revision\":\"1\",\"origin\":\"explicit_override\",\"presetVersionId\":\"cpv_recipe_checkout_1\",\"sourcePresetId\":\"cpr_recipe_checkout\",\"payload\":{\"schemaVersion\":1,\"occurrences\":[{\"occurrenceId\":\"checkout-reliability\",\"reviewerRef\":{\"kind\":\"custom\",\"skillId\":\"skl_recipe_checkout\",\"versionId\":\"skv_recipe_checkout_1\"},\"label\":\"Checkout reliability\",\"enabled\":true,\"skill\":{\"version\":\"skv_recipe_checkout_1\",\"sha256\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\"},\"model\":{\"provider\":\"openai\",\"model\":\"gpt-5.2\",\"reasoning\":\"high\"}}]},\"createdById\":\"usr_recipe_owner\",\"createdAt\":\"2026-09-07T16:00:00.000Z\"},\"canEdit\":true},\"after\":{\"origin\":\"project\",\"presetVersionId\":\"cpv_recipe_checkout_1\",\"payload\":{\"schemaVersion\":1,\"occurrences\":[{\"occurrenceId\":\"checkout-reliability\",\"reviewerRef\":{\"kind\":\"custom\",\"skillId\":\"skl_recipe_checkout\",\"versionId\":\"skv_recipe_checkout_1\"},\"label\":\"Checkout reliability\",\"enabled\":true,\"skill\":{\"version\":\"skv_recipe_checkout_1\",\"sha256\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\"},\"model\":{\"provider\":\"openai\",\"model\":\"gpt-5.2\",\"reasoning\":\"high\"}}]}},\"resolvedSelection\":{\"origin\":\"project\",\"presetVersionId\":\"cpv_recipe_checkout_1\",\"payloadSha256\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\"}}"
}
],
"structuredContent": {
"projectId": "prj_fixture_checkout",
"expectedRevision": "1",
"before": {
"kind": "versioned",
"projectId": "prj_fixture_checkout",
"revision": "1",
"currentVersion": {
"id": "pcv_recipe_checkout_1",
"revision": "1",
"origin": "explicit_override",
"presetVersionId": "cpv_recipe_checkout_1",
"sourcePresetId": "cpr_recipe_checkout",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
},
"createdById": "usr_recipe_owner",
"createdAt": "2026-09-07T16:00:00.000Z"
},
"canEdit": true
},
"after": {
"origin": "project",
"presetVersionId": "cpv_recipe_checkout_1",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
}
},
"resolvedSelection": {
"origin": "project",
"presetVersionId": "cpv_recipe_checkout_1",
"payloadSha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
}
}
}
```
Next permitted action: Save the identical candidate and expected revision only after inspecting the resolved pins.
**Example requests**
- “/semel inspect the exact saved reviewer cascade preset”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `project_cascade_get`, `project_cascade_save`.
---
### project_cascade_save
Persist the exact preset, override, or reset candidate already inspected through project_cascade_preview, using optimistic revision and idempotency checks.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:configure`, `skills:read`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `expectedRevision` — string; required; minimum length 1; maximum length 20. Optimistic concurrency value copied from the latest preset, default, or project configuration read. Accepted length or value is 1 through 20, inclusive.
- `candidate` — JSON value; required. Proposed project cascade source to resolve and validate: an immutable preset, explicit occurrence override, or default reset.
- `candidate (anyOf branch 1)` — object; required.
- `candidate (anyOf branch 1).kind` — constant "preset"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "preset".
- `candidate (anyOf branch 1).presetVersionId` — string; required; minimum length 1. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. Minimum accepted length or value is 1.
- `candidate (anyOf branch 2)` — object; required.
- `candidate (anyOf branch 2).kind` — constant "override"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "override".
- `candidate (anyOf branch 2).occurrences` — array; required; minimum items 1; maximum items 20. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `candidate (anyOf branch 2).occurrences[]` — object; required.
- `candidate (anyOf branch 2).occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `candidate (anyOf branch 2).occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `candidate (anyOf branch 2).occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `candidate (anyOf branch 2).occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `candidate (anyOf branch 2).occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `candidate (anyOf branch 2).occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `candidate (anyOf branch 2).occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `candidate (anyOf branch 2).occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `candidate (anyOf branch 2).occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `candidate (anyOf branch 2).occurrences[].model` — object; required. Optional model name declared by the harness.
- `candidate (anyOf branch 2).occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `candidate (anyOf branch 2).occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `candidate (anyOf branch 2).occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `candidate (anyOf branch 2).occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `candidate (anyOf branch 2).occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `candidate (anyOf branch 3)` — object; required.
- `candidate (anyOf branch 3).kind` — constant "reset"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "reset".
- `candidate (anyOf branch 3).expectedSelection` — object; optional. Exact default selection returned by preview; include it when saving a reset so an unseen default change cannot be substituted. Omit the field when it does not apply; omission is distinct from an empty value.
- `candidate (anyOf branch 3).expectedSelection.origin` — "project" | "personal_default" | "team_default" | "builtin_fallback" | "explicit_override"; required. Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: "project", "personal_default", "team_default", "builtin_fallback", "explicit_override".
- `candidate (anyOf branch 3).expectedSelection.presetVersionId` — string | null; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available.
- `candidate (anyOf branch 3).expectedSelection.payloadSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the canonical submitted payload.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"expectedRevision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Optimistic concurrency value copied from the latest preset, default, or project configuration read. Accepted length or value is 1 through 20, inclusive."
},
"candidate": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "preset",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"preset\"."
},
"presetVersionId": {
"type": "string",
"minLength": 1,
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. Minimum accepted length or value is 1."
}
},
"required": [
"kind",
"presetVersionId"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "override",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"override\"."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"kind",
"occurrences"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "reset",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"reset\"."
},
"expectedSelection": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"enum": [
"project",
"personal_default",
"team_default",
"builtin_fallback",
"explicit_override"
],
"description": "Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: \"project\", \"personal_default\", \"team_default\", \"builtin_fallback\", \"explicit_override\"."
},
"presetVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available."
},
"payloadSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest of the canonical submitted payload."
}
},
"required": [
"origin",
"presetVersionId",
"payloadSha256"
],
"additionalProperties": false,
"description": "Exact default selection returned by preview; include it when saving a reset so an unseen default change cannot be substituted. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"kind"
],
"additionalProperties": false
}
],
"description": "Proposed project cascade source to resolve and validate: an immutable preset, explicit occurrence override, or default reset."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"projectId",
"expectedRevision",
"candidate",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"expectedRevision": "1",
"candidate": {
"kind": "preset",
"presetVersionId": "cpv_recipe_checkout_1"
},
"idempotencyKey": "recipe-project-cascade-save-v1"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"expectedRevision": "{{projectCascadeRevision}}",
"candidate": {
"kind": "preset",
"presetVersionId": "{{cascadePresetVersionId}}"
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `operationId` — string; required. Stable identifier for this mutation attempt and its durable idempotent receipt.
- `config` — JSON value; required. Exact current project reviewer configuration returned after authorization or a successful save.
- `config (anyOf branch 1)` — object; required.
- `config (anyOf branch 1).kind` — constant "versioned"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "versioned".
- `config (anyOf branch 1).projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `config (anyOf branch 1).revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `config (anyOf branch 1).currentVersion` — object; required. Current immutable version of this cascade preset, including its exact reviewer pins.
- `config (anyOf branch 1).currentVersion.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `config (anyOf branch 1).currentVersion.revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `config (anyOf branch 1).currentVersion.origin` — "project" | "personal_default" | "team_default" | "builtin_fallback" | "explicit_override"; required. Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: "project", "personal_default", "team_default", "builtin_fallback", "explicit_override".
- `config (anyOf branch 1).currentVersion.presetVersionId` — string | null; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available.
- `config (anyOf branch 1).currentVersion.sourcePresetId` — string | null; optional. Preset identifier from which this project configuration was explicitly adopted; null identifies a manual selection. 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.
- `config (anyOf branch 1).currentVersion.payload` — object; required. Complete ordered cascade selection preserved in this immutable preset or configuration version.
- `config (anyOf branch 1).currentVersion.payload.schemaVersion` — constant 1; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1.
- `config (anyOf branch 1).currentVersion.payload.occurrences` — array; required; minimum items 1. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `config (anyOf branch 1).currentVersion.payload.occurrences[]` — object; required.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `config (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `config (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `config (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].model` — object; required. Optional model name declared by the harness.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `config (anyOf branch 1).currentVersion.payload.occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `config (anyOf branch 1).currentVersion.createdById` — string; required. Semel user identifier recorded as the initiating creator.
- `config (anyOf branch 1).currentVersion.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `config (anyOf branch 1).canEdit` — boolean; required. Whether the current authenticated principal may edit this reviewer skill.
- `config (anyOf branch 2)` — object; required.
- `config (anyOf branch 2).kind` — constant "legacy"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "legacy".
- `config (anyOf branch 2).projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `config (anyOf branch 2).revision` — constant "0"; required. Indexed repository revision used for this evidence result. This branch always uses "0".
- `config (anyOf branch 2).steps` — array; required. Configured cascade steps in execution order with their latest run state. An empty array explicitly means no matching items.
- `config (anyOf branch 2).steps[]` — object; required.
- `config (anyOf branch 2).steps[].stepId` — string; required. Identifier of one legacy reviewer-cascade step returned by the current project configuration.
- `config (anyOf branch 2).steps[].position` — integer; required; minimum 0. Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer.
- `config (anyOf branch 2).steps[].reviewer` — string; required. Reviewer role responsible for this submitted result.
- `config (anyOf branch 2).steps[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `config (anyOf branch 2).steps[].provider` — string | null; required. Resolved inference provider preserved in the immutable reviewer execution pin. A null value explicitly means no current value is available.
- `config (anyOf branch 2).steps[].model` — string | null; required. Optional model name declared by the harness. A null value explicitly means no current value is available.
- `config (anyOf branch 2).steps[].reasoning` — string | null; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available.
- `config (anyOf branch 2).canEdit` — boolean; required. Whether the current authenticated principal may edit this reviewer skill.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"operationId": {
"type": "string",
"description": "Stable identifier for this mutation attempt and its durable idempotent receipt."
},
"config": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "versioned",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"versioned\"."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"currentVersion": {
"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."
},
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"origin": {
"type": "string",
"enum": [
"project",
"personal_default",
"team_default",
"builtin_fallback",
"explicit_override"
],
"description": "Immutable source from which this cascade configuration was adopted; it never consults a current default. Allowed values: \"project\", \"personal_default\", \"team_default\", \"builtin_fallback\", \"explicit_override\"."
},
"presetVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available."
},
"sourcePresetId": {
"type": [
"string",
"null"
],
"description": "Preset identifier from which this project configuration was explicitly adopted; null identifies a manual selection. 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."
},
"payload": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 1,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"schemaVersion",
"occurrences"
],
"additionalProperties": false,
"description": "Complete ordered cascade selection preserved in this immutable preset or configuration version."
},
"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",
"revision",
"origin",
"presetVersionId",
"payload",
"createdById",
"createdAt"
],
"additionalProperties": false,
"description": "Current immutable version of this cascade preset, including its exact reviewer pins."
},
"canEdit": {
"type": "boolean",
"description": "Whether the current authenticated principal may edit this reviewer skill."
}
},
"required": [
"kind",
"projectId",
"revision",
"currentVersion",
"canEdit"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "legacy",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"legacy\"."
},
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"revision": {
"type": "string",
"const": "0",
"description": "Indexed repository revision used for this evidence result. This branch always uses \"0\"."
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stepId": {
"type": "string",
"description": "Identifier of one legacy reviewer-cascade step returned by the current project configuration."
},
"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."
},
"reviewer": {
"type": "string",
"description": "Reviewer role responsible for this submitted result."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"provider": {
"type": [
"string",
"null"
],
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. A null value explicitly means no current value is available."
},
"model": {
"type": [
"string",
"null"
],
"description": "Optional model name declared by the harness. A null value explicitly means no current value is available."
},
"reasoning": {
"type": [
"string",
"null"
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available."
}
},
"required": [
"stepId",
"position",
"reviewer",
"enabled",
"provider",
"model",
"reasoning"
],
"additionalProperties": false
},
"description": "Configured cascade steps in execution order with their latest run state. An empty array explicitly means no matching items."
},
"canEdit": {
"type": "boolean",
"description": "Whether the current authenticated principal may edit this reviewer skill."
}
},
"required": [
"kind",
"projectId",
"revision",
"steps",
"canEdit"
],
"additionalProperties": false
}
],
"description": "Exact current project reviewer configuration returned after authorization or a successful save."
}
},
"required": [
"operationId",
"config"
],
"additionalProperties": false
}
```
**Example structured result (project-cascade-saved)**
```json
{
"operationId": "example",
"config": {
"kind": "versioned",
"projectId": "prj_fixture_checkout",
"revision": "2",
"currentVersion": {
"id": "pcv_recipe_checkout_2",
"revision": "2",
"origin": "explicit_override",
"presetVersionId": "cpv_recipe_checkout_1",
"sourcePresetId": "cpr_recipe_checkout",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
},
"createdById": "usr_recipe_owner",
"createdAt": "2026-09-07T16:00:00.000Z"
},
"canEdit": true
}
}
```
Bindings: savedProjectCascadeRevision from structuredContent.config.revision.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"operationId\":\"example\",\"config\":{\"kind\":\"versioned\",\"projectId\":\"prj_fixture_checkout\",\"revision\":\"2\",\"currentVersion\":{\"id\":\"pcv_recipe_checkout_2\",\"revision\":\"2\",\"origin\":\"explicit_override\",\"presetVersionId\":\"cpv_recipe_checkout_1\",\"sourcePresetId\":\"cpr_recipe_checkout\",\"payload\":{\"schemaVersion\":1,\"occurrences\":[{\"occurrenceId\":\"checkout-reliability\",\"reviewerRef\":{\"kind\":\"custom\",\"skillId\":\"skl_recipe_checkout\",\"versionId\":\"skv_recipe_checkout_1\"},\"label\":\"Checkout reliability\",\"enabled\":true,\"skill\":{\"version\":\"skv_recipe_checkout_1\",\"sha256\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\"},\"model\":{\"provider\":\"openai\",\"model\":\"gpt-5.2\",\"reasoning\":\"high\"}}]},\"createdById\":\"usr_recipe_owner\",\"createdAt\":\"2026-09-07T16:00:00.000Z\"},\"canEdit\":true}}"
}
],
"structuredContent": {
"operationId": "example",
"config": {
"kind": "versioned",
"projectId": "prj_fixture_checkout",
"revision": "2",
"currentVersion": {
"id": "pcv_recipe_checkout_2",
"revision": "2",
"origin": "explicit_override",
"presetVersionId": "cpv_recipe_checkout_1",
"sourcePresetId": "cpr_recipe_checkout",
"payload": {
"schemaVersion": 1,
"occurrences": [
{
"occurrenceId": "checkout-reliability",
"reviewerRef": {
"kind": "custom",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1"
},
"label": "Checkout reliability",
"enabled": true,
"skill": {
"version": "skv_recipe_checkout_1",
"sha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd"
},
"model": {
"provider": "openai",
"model": "gpt-5.2",
"reasoning": "high"
}
}
]
},
"createdById": "usr_recipe_owner",
"createdAt": "2026-09-07T16:00:00.000Z"
},
"canEdit": true
}
}
}
```
Next permitted action: Read the project cascade again and verify the saved revision and exact preset pins.
**Example requests**
- “/semel save this exact published reviewer sequence as my default”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`, `CONFLICTING_IDEMPOTENCY_REPLAY`, `VALIDATION_FAILED`.
Related operations: `project_cascade_get`, `project_cascade_preview`.
---
### project_codebase_link
Turn on one already-connected codebase for a project after the agent inventories plausible repositories and the user confirms the proposed scope.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `repositoryId` — string; required; minimum length 1. Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"repositoryId": {
"type": "string",
"minLength": 1,
"description": "Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"projectId",
"repositoryId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"repositoryId": "repo_fixture_throughline",
"idempotencyKey": "recipe-project-codebase-link-v1"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"repositoryId": "{{repositoryId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `projectCodebase` — object; required. Project-to-repository link returned by the operation.
- `projectCodebase.projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `projectCodebase.repositoryId` — string; required; minimum length 1. Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
- `projectCodebase.linked` — constant true; required. Whether the repository is currently linked to the project. This branch always uses true.
- `projectCodebase.newlyLinked` — boolean; required. Whether this call created the project-to-repository link instead of replaying an existing link.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"projectCodebase": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"repositoryId": {
"type": "string",
"minLength": 1,
"description": "Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1."
},
"linked": {
"type": "boolean",
"const": true,
"description": "Whether the repository is currently linked to the project. This branch always uses true."
},
"newlyLinked": {
"type": "boolean",
"description": "Whether this call created the project-to-repository link instead of replaying an existing link."
}
},
"required": [
"projectId",
"repositoryId",
"linked",
"newlyLinked"
],
"additionalProperties": false,
"description": "Project-to-repository link returned by the operation."
}
},
"required": [
"projectCodebase"
],
"additionalProperties": false
}
```
**Example structured result (codebase-linked)**
```json
{
"projectCodebase": {
"projectId": "prj_fixture_checkout",
"repositoryId": "repo_fixture_throughline",
"linked": true,
"newlyLinked": true
}
}
```
Bindings: linked from structuredContent.projectCodebase.linked.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"projectCodebase\":{\"projectId\":\"prj_fixture_checkout\",\"repositoryId\":\"repo_fixture_throughline\",\"linked\":true,\"newlyLinked\":true}}"
}
],
"structuredContent": {
"projectCodebase": {
"projectId": "prj_fixture_checkout",
"repositoryId": "repo_fixture_throughline",
"linked": true,
"newlyLinked": true
}
}
}
```
Next permitted action: Proceed with the confirmed repository in project scope.
**Example requests**
- “/semel add the throughlineos codebase to this project”
- “/semel use this connected repository as project evidence”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `project_codebases_list`, `project_context_sources_list`, `brief_create`.
---
### project_codebases_list
List connected workspace codebases, including unselected ones, and show which are currently in a project so the user can confirm repository scope before brief creation or review. Follow nextCursor until it is null before treating the inventory as complete.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `cursor` — string; optional; minimum length 1. Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
- `limit` — integer; optional; minimum 1; maximum 200. Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer."
}
},
"required": [
"projectId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"limit": 50
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"limit": 50
}
```
**Returns**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `codebases` — array; required. Connected repository options visible to this project actor. An empty array explicitly means no matching items.
- `codebases[]` — object; required.
- `codebases[].repositoryId` — string; required; minimum length 1. Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
- `codebases[].owner` — string; required; minimum length 1. Repository owner or organization slug returned by the connected source provider; pair it with repository name. Minimum accepted length or value is 1.
- `codebases[].name` — string; required; minimum length 1. Human-readable name displayed in Semel. Minimum accepted length or value is 1.
- `codebases[].trackingBranch` — string; required; minimum length 1. Repository branch configured for indexing and review evidence. Minimum accepted length or value is 1.
- `codebases[].selected` — boolean; required. Whether this connected repository is selected for the project.
- `codebases[].selectionStatus` — "available" | "access_unavailable" | "removing"; required. Current availability state of a connected repository for project selection; unavailable or removing repositories cannot be newly selected. Allowed values: "available", "access_unavailable", "removing".
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"codebases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"repositoryId": {
"type": "string",
"minLength": 1,
"description": "Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1."
},
"owner": {
"type": "string",
"minLength": 1,
"description": "Repository owner or organization slug returned by the connected source provider; pair it with repository name. Minimum accepted length or value is 1."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable name displayed in Semel. Minimum accepted length or value is 1."
},
"trackingBranch": {
"type": "string",
"minLength": 1,
"description": "Repository branch configured for indexing and review evidence. Minimum accepted length or value is 1."
},
"selected": {
"type": "boolean",
"description": "Whether this connected repository is selected for the project."
},
"selectionStatus": {
"type": "string",
"enum": [
"available",
"access_unavailable",
"removing"
],
"description": "Current availability state of a connected repository for project selection; unavailable or removing repositories cannot be newly selected. Allowed values: \"available\", \"access_unavailable\", \"removing\"."
}
},
"required": [
"repositoryId",
"owner",
"name",
"trackingBranch",
"selected",
"selectionStatus"
],
"additionalProperties": false
},
"description": "Connected repository options visible to this project actor. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"projectId",
"codebases",
"nextCursor"
],
"additionalProperties": false
}
```
**Example structured result (codebase-inventory)**
```json
{
"projectId": "prj_fixture_checkout",
"codebases": [
{
"repositoryId": "repo_fixture_throughline",
"owner": "throughline",
"name": "throughlineos",
"trackingBranch": "main",
"selected": false,
"selectionStatus": "available"
}
],
"nextCursor": null
}
```
Bindings: codebases from structuredContent.codebases.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"projectId\":\"prj_fixture_checkout\",\"codebases\":[{\"repositoryId\":\"repo_fixture_throughline\",\"owner\":\"throughline\",\"name\":\"throughlineos\",\"trackingBranch\":\"main\",\"selected\":false,\"selectionStatus\":\"available\"}],\"nextCursor\":null}"
}
],
"structuredContent": {
"projectId": "prj_fixture_checkout",
"codebases": [
{
"repositoryId": "repo_fixture_throughline",
"owner": "throughline",
"name": "throughlineos",
"trackingBranch": "main",
"selected": false,
"selectionStatus": "available"
}
],
"nextCursor": null
}
}
```
Next permitted action: Follow nextCursor until null before proposing repository scope.
**Example requests**
- “/semel which connected codebases may be relevant to this project?”
- “/semel show the selected and available repositories for this project”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `project_get`, `project_codebase_link`, `brief_create`.
---
### project_context_evidence_get
Fetch the bounded excerpt or statement a search result cited, preserving its source/version/provenance.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `citationHandle` — string; required; minimum length 1. Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"citationHandle": {
"type": "string",
"minLength": 1,
"description": "Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1."
}
},
"required": [
"projectId",
"citationHandle"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"citationHandle": "ctx1.repository.fixture"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"citationHandle": "{{citationHandle}}"
}
```
**Returns**
- `citation` — JSON value; required. Durable citation metadata for the returned evidence excerpt.
- `citation (anyOf branch 1)` — object; required.
- `citation (anyOf branch 1).citationHandle` — string; required; minimum length 1. Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.
- `citation (anyOf branch 1).sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `citation (anyOf branch 1).provenance` — "semel_indexed" | "local_harness"; required. Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".
- `citation (anyOf branch 1).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `citation (anyOf branch 1).score` — number; required. Retrieval relevance score used to order evidence results.
- `citation (anyOf branch 1).kind` — constant "repository"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "repository".
- `citation (anyOf branch 1).repository` — object; required. Connected repository identity and provider metadata.
- `citation (anyOf branch 1).repository.owner` — string; required. Repository owner or organization slug returned by the connected source provider; pair it with repository name.
- `citation (anyOf branch 1).repository.name` — string; required. Human-readable name displayed in Semel.
- `citation (anyOf branch 1).revision` — object; required. Indexed repository revision used for this evidence result.
- `citation (anyOf branch 1).revision.commitSha` — string; required. Git commit SHA pinned by the evidence manifest.
- `citation (anyOf branch 1).revision.revisionId` — string; required. Immutable indexed repository revision identifier.
- `citation (anyOf branch 1).path` — string; required. Repository-relative source path; it never denotes an arbitrary local filesystem path.
- `citation (anyOf branch 1).startLine` — integer; required. One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `citation (anyOf branch 1).endLine` — integer; required. One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `citation (anyOf branch 2)` — object; required.
- `citation (anyOf branch 2).citationHandle` — string; required; minimum length 1. Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.
- `citation (anyOf branch 2).sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `citation (anyOf branch 2).provenance` — "semel_indexed" | "local_harness"; required. Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".
- `citation (anyOf branch 2).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `citation (anyOf branch 2).score` — number; required. Retrieval relevance score used to order evidence results.
- `citation (anyOf branch 2).kind` — constant "knowledge_collection"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "knowledge_collection".
- `citation (anyOf branch 2).collection` — object; required. Named durable brief collection to page; use one of the documented enum values.
- `citation (anyOf branch 2).collection.scopeKind` — "workspace" | "project" | "repository"; required. Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: "workspace", "project", "repository".
- `citation (anyOf branch 2).collection.scopeId` — string; required. Stable identifier of the repository scope that produced this evidence.
- `citation (anyOf branch 2).collection.snapshotId` — string; required. Immutable export snapshot identifier used to reproduce the exported brief state.
- `citation (anyOf branch 2).collection.version` — integer; required; minimum 0. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer.
- `citation (anyOf branch 2).sectionKey` — string; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result.
- `citation (anyOf branch 2).statementIndex` — integer; required; minimum 0. Zero-based statement position within the cited brief section. Minimum accepted length or value is 0. The value must be an integer.
- `excerpt` — string; required. Bounded source excerpt authorized for this result; an empty string means no excerpt text was returned.
- `truncated` — boolean; required. Whether the returned excerpt was shortened to the response limit.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"citation": {
"anyOf": [
{
"type": "object",
"properties": {
"citationHandle": {
"type": "string",
"minLength": 1,
"description": "Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1."
},
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"provenance": {
"type": "string",
"enum": [
"semel_indexed",
"local_harness"
],
"description": "Immutable repository revision and evidence-source provenance. Allowed values: \"semel_indexed\", \"local_harness\"."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"score": {
"type": "number",
"description": "Retrieval relevance score used to order evidence results."
},
"kind": {
"type": "string",
"const": "repository",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"repository\"."
},
"repository": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"description": "Repository owner or organization slug returned by the connected source provider; pair it with repository name."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
}
},
"required": [
"owner",
"name"
],
"additionalProperties": false,
"description": "Connected repository identity and provider metadata."
},
"revision": {
"type": "object",
"properties": {
"commitSha": {
"type": "string",
"description": "Git commit SHA pinned by the evidence manifest."
},
"revisionId": {
"type": "string",
"description": "Immutable indexed repository revision identifier."
}
},
"required": [
"commitSha",
"revisionId"
],
"additionalProperties": false,
"description": "Indexed repository revision used for this evidence result."
},
"path": {
"type": "string",
"description": "Repository-relative source path; it never denotes an arbitrary local filesystem path."
},
"startLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
},
"endLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"citationHandle",
"sourceId",
"provenance",
"route",
"score",
"kind",
"repository",
"revision",
"path",
"startLine",
"endLine"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"citationHandle": {
"type": "string",
"minLength": 1,
"description": "Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1."
},
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"provenance": {
"type": "string",
"enum": [
"semel_indexed",
"local_harness"
],
"description": "Immutable repository revision and evidence-source provenance. Allowed values: \"semel_indexed\", \"local_harness\"."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"score": {
"type": "number",
"description": "Retrieval relevance score used to order evidence results."
},
"kind": {
"type": "string",
"const": "knowledge_collection",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"knowledge_collection\"."
},
"collection": {
"type": "object",
"properties": {
"scopeKind": {
"type": "string",
"enum": [
"workspace",
"project",
"repository"
],
"description": "Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: \"workspace\", \"project\", \"repository\"."
},
"scopeId": {
"type": "string",
"description": "Stable identifier of the repository scope that produced this evidence."
},
"snapshotId": {
"type": "string",
"description": "Immutable export snapshot identifier used to reproduce the exported brief state."
},
"version": {
"type": "integer",
"minimum": 0,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"scopeKind",
"scopeId",
"snapshotId",
"version"
],
"additionalProperties": false,
"description": "Named durable brief collection to page; use one of the documented enum values."
},
"sectionKey": {
"type": "string",
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result."
},
"statementIndex": {
"type": "integer",
"minimum": 0,
"description": "Zero-based statement position within the cited brief section. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"citationHandle",
"sourceId",
"provenance",
"route",
"score",
"kind",
"collection",
"sectionKey",
"statementIndex"
],
"additionalProperties": false
}
],
"description": "Durable citation metadata for the returned evidence excerpt."
},
"excerpt": {
"type": "string",
"description": "Bounded source excerpt authorized for this result; an empty string means no excerpt text was returned."
},
"truncated": {
"type": "boolean",
"description": "Whether the returned excerpt was shortened to the response limit."
}
},
"required": [
"citation",
"excerpt",
"truncated"
],
"additionalProperties": false
}
```
**Example structured result (bounded-evidence)**
```json
{
"citation": {
"citationHandle": "ctx1.repository.fixture",
"sourceId": "src_fixture_repository",
"provenance": "semel_indexed",
"route": "exact",
"score": 0,
"kind": "repository",
"repository": {
"owner": "throughline",
"name": "throughlineos"
},
"revision": {
"commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"revisionId": "rev_fixture_checkout"
},
"path": "services/api/src/checkout.ts",
"startLine": 42,
"endLine": 58
},
"excerpt": "The checkout handler reuses the payment intent for a repeated idempotency key.",
"truncated": false
}
```
Bindings: excerpt from structuredContent.excerpt.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"citation\":{\"citationHandle\":\"ctx1.repository.fixture\",\"sourceId\":\"src_fixture_repository\",\"provenance\":\"semel_indexed\",\"route\":\"exact\",\"score\":0,\"kind\":\"repository\",\"repository\":{\"owner\":\"throughline\",\"name\":\"throughlineos\"},\"revision\":{\"commitSha\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"revisionId\":\"rev_fixture_checkout\"},\"path\":\"services/api/src/checkout.ts\",\"startLine\":42,\"endLine\":58},\"excerpt\":\"The checkout handler reuses the payment intent for a repeated idempotency key.\",\"truncated\":false}"
}
],
"structuredContent": {
"citation": {
"citationHandle": "ctx1.repository.fixture",
"sourceId": "src_fixture_repository",
"provenance": "semel_indexed",
"route": "exact",
"score": 0,
"kind": "repository",
"repository": {
"owner": "throughline",
"name": "throughlineos"
},
"revision": {
"commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"revisionId": "rev_fixture_checkout"
},
"path": "services/api/src/checkout.ts",
"startLine": 42,
"endLine": 58
},
"excerpt": "The checkout handler reuses the payment intent for a repeated idempotency key.",
"truncated": false
}
}
```
Next permitted action: Cite the returned provenance/revision/path and disclose truncated when true.
**Example requests**
- “show me the code that matched that last search result”
Errors: `AUTHORIZATION_SCOPE_MISSING`, `PROJECT_ACCESS_DENIED`, `CONTEXT_FORBIDDEN`, `CONTEXT_UNAVAILABLE`.
Related operations: `project_context_search`.
---
### project_context_search
Search one or more already-listed context sources for evidence relevant to the active reviewer skill’s question.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `sourceIds` — array; required; minimum items 1; maximum items 5. Source identifiers returned by project_context_sources_list that bound this search. An empty array explicitly means no matching items.
- `sourceIds[]` — string; required; minimum length 1.
- `query` — string; required; minimum length 1; maximum length 500. Natural-language or code search query evaluated only against the selected project context sources. Accepted length or value is 1 through 500, inclusive.
- `limit` — integer; optional; minimum 1; maximum 200. Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"sourceIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"maxItems": 5,
"description": "Source identifiers returned by project_context_sources_list that bound this search. An empty array explicitly means no matching items."
},
"query": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Natural-language or code search query evaluated only against the selected project context sources. Accepted length or value is 1 through 500, inclusive."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer."
}
},
"required": [
"projectId",
"sourceIds",
"query"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"sourceIds": [
"src_fixture_repository"
],
"query": "payment retry idempotency",
"limit": 20
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"sourceIds": [
"{{sourceId}}"
],
"query": "payment retry idempotency",
"limit": 20
}
```
**Returns**
- `results` — array; required. Ranked evidence matches for the requested sources and query. An empty array explicitly means no matching items.
- `results[]` — object; required.
- `results[].citation` — JSON value; required. Durable citation metadata for the returned evidence excerpt.
- `results[].citation (anyOf branch 1)` — object; required.
- `results[].citation (anyOf branch 1).citationHandle` — string; required; minimum length 1. Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.
- `results[].citation (anyOf branch 1).sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `results[].citation (anyOf branch 1).provenance` — "semel_indexed" | "local_harness"; required. Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".
- `results[].citation (anyOf branch 1).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `results[].citation (anyOf branch 1).score` — number; required. Retrieval relevance score used to order evidence results.
- `results[].citation (anyOf branch 1).kind` — constant "repository"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "repository".
- `results[].citation (anyOf branch 1).repository` — object; required. Connected repository identity and provider metadata.
- `results[].citation (anyOf branch 1).repository.owner` — string; required. Repository owner or organization slug returned by the connected source provider; pair it with repository name.
- `results[].citation (anyOf branch 1).repository.name` — string; required. Human-readable name displayed in Semel.
- `results[].citation (anyOf branch 1).revision` — object; required. Indexed repository revision used for this evidence result.
- `results[].citation (anyOf branch 1).revision.commitSha` — string; required. Git commit SHA pinned by the evidence manifest.
- `results[].citation (anyOf branch 1).revision.revisionId` — string; required. Immutable indexed repository revision identifier.
- `results[].citation (anyOf branch 1).path` — string; required. Repository-relative source path; it never denotes an arbitrary local filesystem path.
- `results[].citation (anyOf branch 1).startLine` — integer; required. One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `results[].citation (anyOf branch 1).endLine` — integer; required. One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `results[].citation (anyOf branch 2)` — object; required.
- `results[].citation (anyOf branch 2).citationHandle` — string; required; minimum length 1. Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1.
- `results[].citation (anyOf branch 2).sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `results[].citation (anyOf branch 2).provenance` — "semel_indexed" | "local_harness"; required. Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".
- `results[].citation (anyOf branch 2).route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `results[].citation (anyOf branch 2).score` — number; required. Retrieval relevance score used to order evidence results.
- `results[].citation (anyOf branch 2).kind` — constant "knowledge_collection"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "knowledge_collection".
- `results[].citation (anyOf branch 2).collection` — object; required. Named durable brief collection to page; use one of the documented enum values.
- `results[].citation (anyOf branch 2).collection.scopeKind` — "workspace" | "project" | "repository"; required. Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: "workspace", "project", "repository".
- `results[].citation (anyOf branch 2).collection.scopeId` — string; required. Stable identifier of the repository scope that produced this evidence.
- `results[].citation (anyOf branch 2).collection.snapshotId` — string; required. Immutable export snapshot identifier used to reproduce the exported brief state.
- `results[].citation (anyOf branch 2).collection.version` — integer; required; minimum 0. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer.
- `results[].citation (anyOf branch 2).sectionKey` — string; required. Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result.
- `results[].citation (anyOf branch 2).statementIndex` — integer; required; minimum 0. Zero-based statement position within the cited brief section. Minimum accepted length or value is 0. The value must be an integer.
- `searchedSources` — array; required. Source identifiers actually searched after authorization and availability checks. An empty array explicitly means no matching items.
- `searchedSources[]` — object; required.
- `searchedSources[].sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `searchedSources[].route` — "exact" | "lexical" | "hybrid"; required. Repository route or evidence route label recorded with the citation. Allowed values: "exact", "lexical", "hybrid".
- `searchedSources[].resultCount` — integer; required; minimum 0. Number of evidence matches returned in this response. Minimum accepted length or value is 0. The value must be an integer.
- `searchedSources[].abstained` — boolean; required. Whether search deliberately returned no evidence because trust or relevance requirements were unmet.
- `searchedSources[].abstentionReason` — string; optional. Safe explanation for why evidence search abstained; null means it returned normally. Omit the field when it does not apply; omission is distinct from an empty value.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"properties": {
"citation": {
"anyOf": [
{
"type": "object",
"properties": {
"citationHandle": {
"type": "string",
"minLength": 1,
"description": "Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1."
},
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"provenance": {
"type": "string",
"enum": [
"semel_indexed",
"local_harness"
],
"description": "Immutable repository revision and evidence-source provenance. Allowed values: \"semel_indexed\", \"local_harness\"."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"score": {
"type": "number",
"description": "Retrieval relevance score used to order evidence results."
},
"kind": {
"type": "string",
"const": "repository",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"repository\"."
},
"repository": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"description": "Repository owner or organization slug returned by the connected source provider; pair it with repository name."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
}
},
"required": [
"owner",
"name"
],
"additionalProperties": false,
"description": "Connected repository identity and provider metadata."
},
"revision": {
"type": "object",
"properties": {
"commitSha": {
"type": "string",
"description": "Git commit SHA pinned by the evidence manifest."
},
"revisionId": {
"type": "string",
"description": "Immutable indexed repository revision identifier."
}
},
"required": [
"commitSha",
"revisionId"
],
"additionalProperties": false,
"description": "Indexed repository revision used for this evidence result."
},
"path": {
"type": "string",
"description": "Repository-relative source path; it never denotes an arbitrary local filesystem path."
},
"startLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
},
"endLine": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"citationHandle",
"sourceId",
"provenance",
"route",
"score",
"kind",
"repository",
"revision",
"path",
"startLine",
"endLine"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"citationHandle": {
"type": "string",
"minLength": 1,
"description": "Opaque evidence handle returned by project_context_search; pass it unchanged to evidence_get. Minimum accepted length or value is 1."
},
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"provenance": {
"type": "string",
"enum": [
"semel_indexed",
"local_harness"
],
"description": "Immutable repository revision and evidence-source provenance. Allowed values: \"semel_indexed\", \"local_harness\"."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"score": {
"type": "number",
"description": "Retrieval relevance score used to order evidence results."
},
"kind": {
"type": "string",
"const": "knowledge_collection",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"knowledge_collection\"."
},
"collection": {
"type": "object",
"properties": {
"scopeKind": {
"type": "string",
"enum": [
"workspace",
"project",
"repository"
],
"description": "Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: \"workspace\", \"project\", \"repository\"."
},
"scopeId": {
"type": "string",
"description": "Stable identifier of the repository scope that produced this evidence."
},
"snapshotId": {
"type": "string",
"description": "Immutable export snapshot identifier used to reproduce the exported brief state."
},
"version": {
"type": "integer",
"minimum": 0,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"scopeKind",
"scopeId",
"snapshotId",
"version"
],
"additionalProperties": false,
"description": "Named durable brief collection to page; use one of the documented enum values."
},
"sectionKey": {
"type": "string",
"description": "Canonical brief or knowledge-section key that locates the cited statement; copy it from the source schema or search result."
},
"statementIndex": {
"type": "integer",
"minimum": 0,
"description": "Zero-based statement position within the cited brief section. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"citationHandle",
"sourceId",
"provenance",
"route",
"score",
"kind",
"collection",
"sectionKey",
"statementIndex"
],
"additionalProperties": false
}
],
"description": "Durable citation metadata for the returned evidence excerpt."
}
},
"required": [
"citation"
],
"additionalProperties": false
},
"description": "Ranked evidence matches for the requested sources and query. An empty array explicitly means no matching items."
},
"searchedSources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"route": {
"type": "string",
"enum": [
"exact",
"lexical",
"hybrid"
],
"description": "Repository route or evidence route label recorded with the citation. Allowed values: \"exact\", \"lexical\", \"hybrid\"."
},
"resultCount": {
"type": "integer",
"minimum": 0,
"description": "Number of evidence matches returned in this response. Minimum accepted length or value is 0. The value must be an integer."
},
"abstained": {
"type": "boolean",
"description": "Whether search deliberately returned no evidence because trust or relevance requirements were unmet."
},
"abstentionReason": {
"type": "string",
"description": "Safe explanation for why evidence search abstained; null means it returned normally. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sourceId",
"route",
"resultCount",
"abstained"
],
"additionalProperties": false
},
"description": "Source identifiers actually searched after authorization and availability checks. An empty array explicitly means no matching items."
}
},
"required": [
"results",
"searchedSources"
],
"additionalProperties": false
}
```
**Example structured result (search-results)**
```json
{
"results": [
{
"citation": {
"citationHandle": "ctx1.repository.fixture",
"sourceId": "src_fixture_repository",
"provenance": "semel_indexed",
"route": "exact",
"score": 0.93,
"kind": "repository",
"repository": {
"owner": "throughline",
"name": "throughlineos"
},
"revision": {
"commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"revisionId": "rev_fixture_checkout"
},
"path": "services/api/src/checkout.ts",
"startLine": 42,
"endLine": 58
}
}
],
"searchedSources": [
{
"sourceId": "src_fixture_repository",
"route": "exact",
"resultCount": 1,
"abstained": false
}
]
}
```
Bindings: citationHandle from structuredContent.results[0].citation.citationHandle.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"results\":[{\"citation\":{\"citationHandle\":\"ctx1.repository.fixture\",\"sourceId\":\"src_fixture_repository\",\"provenance\":\"semel_indexed\",\"route\":\"exact\",\"score\":0.93,\"kind\":\"repository\",\"repository\":{\"owner\":\"throughline\",\"name\":\"throughlineos\"},\"revision\":{\"commitSha\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"revisionId\":\"rev_fixture_checkout\"},\"path\":\"services/api/src/checkout.ts\",\"startLine\":42,\"endLine\":58}}],\"searchedSources\":[{\"sourceId\":\"src_fixture_repository\",\"route\":\"exact\",\"resultCount\":1,\"abstained\":false}]}"
}
],
"structuredContent": {
"results": [
{
"citation": {
"citationHandle": "ctx1.repository.fixture",
"sourceId": "src_fixture_repository",
"provenance": "semel_indexed",
"route": "exact",
"score": 0.93,
"kind": "repository",
"repository": {
"owner": "throughline",
"name": "throughlineos"
},
"revision": {
"commitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"revisionId": "rev_fixture_checkout"
},
"path": "services/api/src/checkout.ts",
"startLine": 42,
"endLine": 58
}
}
],
"searchedSources": [
{
"sourceId": "src_fixture_repository",
"route": "exact",
"resultCount": 1,
"abstained": false
}
]
}
}
```
Next permitted action: Preserve the returned citationHandle exactly; inspect abstention metadata when no result exists.
**Example requests**
- “search the indexed repository for the retry handler”
- “have we recorded any prior decisions about pricing?”
Errors: `AUTHORIZATION_SCOPE_MISSING`, `PROJECT_ACCESS_DENIED`, `CONTEXT_FORBIDDEN`, `CONTEXT_UNAVAILABLE`.
Related operations: `project_context_sources_list`, `project_context_evidence_get`.
---
### project_context_sources_list
Discover which repositories and knowledge collections this project can search before claiming absence.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1.
- `cursor` — string; optional; minimum length 1. Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
- `limit` — integer; optional; minimum 1; maximum 200. Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Minimum accepted length or value is 1."
},
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 200,
"description": "Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive. The value must be an integer."
}
},
"required": [
"projectId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"limit": 50
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"limit": 50
}
```
**Returns**
- `sources` — array; required. Connected repository sources currently authorized for this project. An empty array explicitly means no matching items.
- `sources[]` — object; required.
- `sources[].sourceId` — string; required; minimum length 1. Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1.
- `sources[].kind` — "repository" | "knowledge_collection"; required. Discriminator identifying the typed variant represented by this object. Allowed values: "repository", "knowledge_collection".
- `sources[].label` — string; required. Human-readable label displayed for this record.
- `sources[].scope` — object; required. Work explicitly included in this brief.
- `sources[].scope.kind` — "workspace" | "project" | "repository"; required. Discriminator identifying the typed variant represented by this object. Allowed values: "workspace", "project", "repository".
- `sources[].scope.id` — string | null; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. A null value explicitly means no current value is available.
- `sources[].repository` — object; optional. Connected repository identity and provider metadata. Omit the field when it does not apply; omission is distinct from an empty value.
- `sources[].repository.owner` — string; required. Repository owner or organization slug returned by the connected source provider; pair it with repository name.
- `sources[].repository.name` — string; required. Human-readable name displayed in Semel.
- `sources[].repository.defaultBranch` — string; required. Repository default branch reported by the connected provider.
- `sources[].repository.trackingBranch` — string; required. Repository branch configured for indexing and review evidence.
- `sources[].repository.commitSha` — string | null; required. Git commit SHA pinned by the evidence manifest. A null value explicitly means no current value is available.
- `sources[].repository.revisionId` — string | null; required. Immutable indexed repository revision identifier. A null value explicitly means no current value is available.
- `sources[].collection` — object; optional. Named durable brief collection to page; use one of the documented enum values. Omit the field when it does not apply; omission is distinct from an empty value.
- `sources[].collection.scopeKind` — "workspace" | "project" | "repository"; required. Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: "workspace", "project", "repository".
- `sources[].collection.version` — integer; required; minimum 0. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer.
- `sources[].collection.snapshotId` — string; required. Immutable export snapshot identifier used to reproduce the exported brief state.
- `sources[].status` — "ready" | "syncing" | "stale" | "degraded" | "unavailable"; required. Current typed status; the schema enum or union branch lists every allowed value. Allowed values: "ready", "syncing", "stale", "degraded", "unavailable".
- `sources[].freshness` — object; required. Repository indexing freshness and configured tracking branch.
- `sources[].freshness.asOf` — string | null; required. RFC 3339 timestamp describing evidence freshness. A null value explicitly means no current value is available.
- `sources[].freshness.coverage` — "full" | "partial" | "unknown"; required. Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence. Allowed values: "full", "partial", "unknown".
- `sources[].provenance` — "semel_indexed" | "local_harness"; required. Immutable repository revision and evidence-source provenance. Allowed values: "semel_indexed", "local_harness".
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"sources": {
"type": "array",
"items": {
"type": "object",
"properties": {
"sourceId": {
"type": "string",
"minLength": 1,
"description": "Opaque source identifier returned by project_context_sources_list; pass it back unchanged. Minimum accepted length or value is 1."
},
"kind": {
"type": "string",
"enum": [
"repository",
"knowledge_collection"
],
"description": "Discriminator identifying the typed variant represented by this object. Allowed values: \"repository\", \"knowledge_collection\"."
},
"label": {
"type": "string",
"description": "Human-readable label displayed for this record."
},
"scope": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"workspace",
"project",
"repository"
],
"description": "Discriminator identifying the typed variant represented by this object. Allowed values: \"workspace\", \"project\", \"repository\"."
},
"id": {
"type": [
"string",
"null"
],
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. A null value explicitly means no current value is available."
}
},
"required": [
"kind",
"id"
],
"additionalProperties": false,
"description": "Work explicitly included in this brief."
},
"repository": {
"type": "object",
"properties": {
"owner": {
"type": "string",
"description": "Repository owner or organization slug returned by the connected source provider; pair it with repository name."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"defaultBranch": {
"type": "string",
"description": "Repository default branch reported by the connected provider."
},
"trackingBranch": {
"type": "string",
"description": "Repository branch configured for indexing and review evidence."
},
"commitSha": {
"type": [
"string",
"null"
],
"description": "Git commit SHA pinned by the evidence manifest. A null value explicitly means no current value is available."
},
"revisionId": {
"type": [
"string",
"null"
],
"description": "Immutable indexed repository revision identifier. A null value explicitly means no current value is available."
}
},
"required": [
"owner",
"name",
"defaultBranch",
"trackingBranch",
"commitSha",
"revisionId"
],
"additionalProperties": false,
"description": "Connected repository identity and provider metadata. Omit the field when it does not apply; omission is distinct from an empty value."
},
"collection": {
"type": "object",
"properties": {
"scopeKind": {
"type": "string",
"enum": [
"workspace",
"project",
"repository"
],
"description": "Ownership boundary for a knowledge collection: workspace, project, or repository. Allowed values: \"workspace\", \"project\", \"repository\"."
},
"version": {
"type": "integer",
"minimum": 0,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 0. The value must be an integer."
},
"snapshotId": {
"type": "string",
"description": "Immutable export snapshot identifier used to reproduce the exported brief state."
}
},
"required": [
"scopeKind",
"version",
"snapshotId"
],
"additionalProperties": false,
"description": "Named durable brief collection to page; use one of the documented enum values. Omit the field when it does not apply; omission is distinct from an empty value."
},
"status": {
"type": "string",
"enum": [
"ready",
"syncing",
"stale",
"degraded",
"unavailable"
],
"description": "Current typed status; the schema enum or union branch lists every allowed value. Allowed values: \"ready\", \"syncing\", \"stale\", \"degraded\", \"unavailable\"."
},
"freshness": {
"type": "object",
"properties": {
"asOf": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp describing evidence freshness. A null value explicitly means no current value is available."
},
"coverage": {
"type": "string",
"enum": [
"full",
"partial",
"unknown"
],
"description": "Evidence coverage metadata or typed completeness level for the cited source; unknown or partial coverage must not imply absence. Allowed values: \"full\", \"partial\", \"unknown\"."
}
},
"required": [
"asOf",
"coverage"
],
"additionalProperties": false,
"description": "Repository indexing freshness and configured tracking branch."
},
"provenance": {
"type": "string",
"enum": [
"semel_indexed",
"local_harness"
],
"description": "Immutable repository revision and evidence-source provenance. Allowed values: \"semel_indexed\", \"local_harness\"."
}
},
"required": [
"sourceId",
"kind",
"label",
"scope",
"status",
"freshness",
"provenance"
],
"additionalProperties": false
},
"description": "Connected repository sources currently authorized for this project. An empty array explicitly means no matching items."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
}
},
"required": [
"sources",
"nextCursor"
],
"additionalProperties": false
}
```
**Example structured result (source-list)**
```json
{
"sources": [
{
"sourceId": "src_fixture_repository",
"kind": "repository",
"label": "throughlineos repository",
"scope": {
"kind": "project",
"id": "prj_fixture_checkout"
},
"status": "ready",
"freshness": {
"asOf": "2026-09-07T16:00:00.000Z",
"coverage": "full"
},
"provenance": "semel_indexed"
}
],
"nextCursor": null
}
```
Bindings: sourceId from structuredContent.sources[0].sourceId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"sources\":[{\"sourceId\":\"src_fixture_repository\",\"kind\":\"repository\",\"label\":\"throughlineos repository\",\"scope\":{\"kind\":\"project\",\"id\":\"prj_fixture_checkout\"},\"status\":\"ready\",\"freshness\":{\"asOf\":\"2026-09-07T16:00:00.000Z\",\"coverage\":\"full\"},\"provenance\":\"semel_indexed\"}],\"nextCursor\":null}"
}
],
"structuredContent": {
"sources": [
{
"sourceId": "src_fixture_repository",
"kind": "repository",
"label": "throughlineos repository",
"scope": {
"kind": "project",
"id": "prj_fixture_checkout"
},
"status": "ready",
"freshness": {
"asOf": "2026-09-07T16:00:00.000Z",
"coverage": "full"
},
"provenance": "semel_indexed"
}
],
"nextCursor": null
}
}
```
Next permitted action: Follow nextCursor to completion and distinguish ready, stale, degraded, and unavailable sources.
**Example requests**
- “what context sources do I have for this project?”
- “is there an indexed repository for the checkout project?”
Errors: `AUTHORIZATION_SCOPE_MISSING`, `PROJECT_ACCESS_DENIED`.
Related operations: `project_context_search`, `project_context_evidence_get`.
---
### project_create
Create a new project (a fresh, independent effort) and seed its recommended pre-build review cascade. Use for any net-new effort; reuse an existing project only on considerable overlap.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `name` — string; required; minimum length 1; maximum length 200. Human-readable name displayed in Semel. Accepted length or value is 1 through 200, inclusive.
- `reviewMode` — "direct" | "propose"; optional. Project review interaction mode configured in Semel. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: "direct", "propose".
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Human-readable name displayed in Semel. Accepted length or value is 1 through 200, inclusive."
},
"reviewMode": {
"type": "string",
"enum": [
"direct",
"propose"
],
"description": "Project review interaction mode configured in Semel. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: \"direct\", \"propose\"."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"name",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"name": "Checkout reliability",
"reviewMode": "direct",
"idempotencyKey": "recipe-project-create-v1"
}
```
**Binding template**
```json
{
"name": "{{projectName}}",
"reviewMode": "direct",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `project` — object; required. Project record returned by the operation.
- `project.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `project.workspaceId` — string; required. Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
- `project.name` — string; required. Human-readable name displayed in Semel.
- `project.reviewMode` — "direct" | "propose"; required. Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
- `project.ownerId` — string; optional. Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value.
- `project.delivery` — object; optional. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value.
- `project.delivery.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `project.delivery.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `project.delivery.deliveryStatus (anyOf branch 2)` — null; required.
- `project.delivery.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `project.delivery.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `project.delivery.changedAt (anyOf branch 1)` — string; required; format date-time.
- `project.delivery.changedAt (anyOf branch 2)` — null; required.
- `project.delivery.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `project.delivery.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `project.delivery.source (anyOf branch 1)` — "web" | "mcp"; required.
- `project.delivery.source (anyOf branch 2)` — null; required.
- `project.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"project": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"workspaceId": {
"type": "string",
"description": "Workspace identifier that owns the record; it is resolved from authenticated Semel membership."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"reviewMode": {
"type": "string",
"enum": [
"direct",
"propose"
],
"description": "Project review interaction mode configured in Semel. Allowed values: \"direct\", \"propose\"."
},
"ownerId": {
"type": "string",
"description": "Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value."
},
"delivery": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"workspaceId",
"name",
"reviewMode",
"createdAt"
],
"additionalProperties": false,
"description": "Project record returned by the operation."
}
},
"required": [
"project"
],
"additionalProperties": false
}
```
**Example structured result (project-created)**
```json
{
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
```
Bindings: projectId from structuredContent.project.id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"project\":{\"id\":\"prj_fixture_checkout\",\"workspaceId\":\"ws_fixture_primary\",\"name\":\"Checkout reliability\",\"reviewMode\":\"direct\",\"createdAt\":\"2026-09-07T16:00:00.000Z\"}}"
}
],
"structuredContent": {
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
}
```
Next permitted action: Carry project.id into every project-scoped call.
**Example requests**
- “/semel create a project for the new onboarding flow”
- “/semel start a new project called Checkout v2”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `project_list`, `project_get`, `brief_create`.
---
### project_delivery_status_set
Set or correct an explicit project delivery status. This never advances review state or changes briefs.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `deliveryStatus` — JSON value; required. Desired explicit delivery state; null deliberately clears the marker and does not alter review, approval, or contract state.
- `deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `deliveryStatus (anyOf branch 2)` — null; required.
- `ifDeliveryStatusVersion` — integer; required; minimum 0. Required optimistic-concurrency precondition copied from the latest deliveryStatusVersion returned by Semel.
- `correctionReason` — string; optional; minimum length 1; maximum length 500. Trimmed audit reason required for backward transitions and clears; tabs and line breaks are allowed but other control characters are rejected.
- `projectId` — string; required; minimum length 1. Project identifier whose explicit delivery status should be changed.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Desired explicit delivery state; null deliberately clears the marker and does not alter review, approval, or contract state."
},
"ifDeliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Required optimistic-concurrency precondition copied from the latest deliveryStatusVersion returned by Semel."
},
"correctionReason": {
"type": "string",
"minLength": 1,
"maxLength": 500,
"description": "Trimmed audit reason required for backward transitions and clears; tabs and line breaks are allowed but other control characters are rejected."
},
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier whose explicit delivery status should be changed."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"deliveryStatus",
"ifDeliveryStatusVersion",
"projectId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"deliveryStatus": "built",
"ifDeliveryStatusVersion": 0,
"idempotencyKey": "recipe-project-delivery-status-set-v1"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"deliveryStatus": "{{projectDeliveryStatus}}",
"ifDeliveryStatusVersion": 0,
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `project` — object; required. Project record returned by the operation.
- `project.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `project.workspaceId` — string; required. Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
- `project.name` — string; required. Human-readable name displayed in Semel.
- `project.reviewMode` — "direct" | "propose"; required. Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
- `project.ownerId` — string; optional. Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value.
- `project.delivery` — object; optional. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value.
- `project.delivery.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `project.delivery.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `project.delivery.deliveryStatus (anyOf branch 2)` — null; required.
- `project.delivery.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `project.delivery.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `project.delivery.changedAt (anyOf branch 1)` — string; required; format date-time.
- `project.delivery.changedAt (anyOf branch 2)` — null; required.
- `project.delivery.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `project.delivery.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `project.delivery.source (anyOf branch 1)` — "web" | "mcp"; required.
- `project.delivery.source (anyOf branch 2)` — null; required.
- `project.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `delivery` — object; required. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state.
- `delivery.projection` — object; required. Authoritative delivery projection after the operation, including an exact no-op response.
- `delivery.projection.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `delivery.projection.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `delivery.projection.deliveryStatus (anyOf branch 2)` — null; required.
- `delivery.projection.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `delivery.projection.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `delivery.projection.changedAt (anyOf branch 1)` — string; required; format date-time.
- `delivery.projection.changedAt (anyOf branch 2)` — null; required.
- `delivery.projection.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `delivery.projection.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `delivery.projection.source (anyOf branch 1)` — "web" | "mcp"; required.
- `delivery.projection.source (anyOf branch 2)` — null; required.
- `delivery.changed` — boolean; required. True when projection and audit event were committed; false for an exact event-free no-op.
- `delivery.eventId` — string | null; required. Immutable delivery-status audit event identifier for a committed change; null for an exact no-op.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"project": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"workspaceId": {
"type": "string",
"description": "Workspace identifier that owns the record; it is resolved from authenticated Semel membership."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"reviewMode": {
"type": "string",
"enum": [
"direct",
"propose"
],
"description": "Project review interaction mode configured in Semel. Allowed values: \"direct\", \"propose\"."
},
"ownerId": {
"type": "string",
"description": "Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value."
},
"delivery": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. 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."
},
"delivery": {
"type": "object",
"properties": {
"projection": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Authoritative delivery projection after the operation, including an exact no-op response."
},
"changed": {
"type": "boolean",
"description": "True when projection and audit event were committed; false for an exact event-free no-op."
},
"eventId": {
"type": [
"string",
"null"
],
"description": "Immutable delivery-status audit event identifier for a committed change; null for an exact no-op."
}
},
"required": [
"projection",
"changed",
"eventId"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state."
}
},
"required": [
"project",
"delivery"
],
"additionalProperties": false
}
```
**Example structured result (project-delivery-status-set)**
```json
{
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "example",
"delivery": {
"deliveryStatus": "built",
"deliveryStatusVersion": 1,
"changedAt": "2026-09-07T16:00:00.000Z",
"changedById": "example",
"source": "mcp"
}
},
"delivery": {
"projection": {
"deliveryStatus": "built",
"deliveryStatusVersion": 1,
"changedAt": "2026-09-07T16:00:00.000Z",
"changedById": "example",
"source": "mcp"
},
"changed": true,
"eventId": "example"
}
}
```
Bindings: projectDeliveryStatus from structuredContent.delivery.projection.deliveryStatus.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"project\":{\"id\":\"prj_fixture_checkout\",\"workspaceId\":\"ws_fixture_primary\",\"name\":\"Checkout reliability\",\"reviewMode\":\"direct\",\"createdAt\":\"example\",\"delivery\":{\"deliveryStatus\":\"built\",\"deliveryStatusVersion\":1,\"changedAt\":\"2026-09-07T16:00:00.000Z\",\"changedById\":\"example\",\"source\":\"mcp\"}},\"delivery\":{\"projection\":{\"deliveryStatus\":\"built\",\"deliveryStatusVersion\":1,\"changedAt\":\"2026-09-07T16:00:00.000Z\",\"changedById\":\"example\",\"source\":\"mcp\"},\"changed\":true,\"eventId\":\"example\"}}"
}
],
"structuredContent": {
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "example",
"delivery": {
"deliveryStatus": "built",
"deliveryStatusVersion": 1,
"changedAt": "2026-09-07T16:00:00.000Z",
"changedById": "example",
"source": "mcp"
}
},
"delivery": {
"projection": {
"deliveryStatus": "built",
"deliveryStatusVersion": 1,
"changedAt": "2026-09-07T16:00:00.000Z",
"changedById": "example",
"source": "mcp"
},
"changed": true,
"eventId": "example"
}
}
}
```
Next permitted action: Use the returned projection and deliveryStatusVersion as the only committed delivery truth.
**Example requests**
- “/semel mark this project built”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `project_get`, `brief_delivery_status_set`.
---
### project_get
Read a single project by id — its name, review mode, creator, and created-at. Use to inspect one project's details, for example after finding it with project_list.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the caller must have access to that project. Supply a non-empty identifier.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project. Supply a non-empty identifier."
}
},
"required": [
"projectId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}"
}
```
**Returns**
- `project` — object; required. Canonical project record returned after authorization and, for project_rename, after the durable name update succeeds.
- `project.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `project.workspaceId` — string; required. Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
- `project.name` — string; required. Human-readable name displayed in Semel.
- `project.reviewMode` — "direct" | "propose"; required. Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
- `project.ownerId` — string; optional. Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value.
- `project.delivery` — object; optional. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value.
- `project.delivery.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `project.delivery.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `project.delivery.deliveryStatus (anyOf branch 2)` — null; required.
- `project.delivery.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `project.delivery.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `project.delivery.changedAt (anyOf branch 1)` — string; required; format date-time.
- `project.delivery.changedAt (anyOf branch 2)` — null; required.
- `project.delivery.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `project.delivery.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `project.delivery.source (anyOf branch 1)` — "web" | "mcp"; required.
- `project.delivery.source (anyOf branch 2)` — null; required.
- `project.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"project": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"workspaceId": {
"type": "string",
"description": "Workspace identifier that owns the record; it is resolved from authenticated Semel membership."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"reviewMode": {
"type": "string",
"enum": [
"direct",
"propose"
],
"description": "Project review interaction mode configured in Semel. Allowed values: \"direct\", \"propose\"."
},
"ownerId": {
"type": "string",
"description": "Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value."
},
"delivery": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"workspaceId",
"name",
"reviewMode",
"createdAt"
],
"additionalProperties": false,
"description": "Canonical project record returned after authorization and, for project_rename, after the durable name update succeeds."
}
},
"required": [
"project"
],
"additionalProperties": false
}
```
**Example structured result (project)**
```json
{
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
```
Bindings: project from structuredContent.project.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"project\":{\"id\":\"prj_fixture_checkout\",\"workspaceId\":\"ws_fixture_primary\",\"name\":\"Checkout reliability\",\"reviewMode\":\"direct\",\"createdAt\":\"2026-09-07T16:00:00.000Z\"}}"
}
],
"structuredContent": {
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Checkout reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
}
```
Next permitted action: Confirm the resolved project details before mutation.
**Example requests**
- “/semel show me the details of this project”
- “/semel what is the review mode for the checkout project?”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `project_list`, `project_rename`.
---
### project_list
List the projects this principal may reach (project-allowlist filtered), newest first. Use to confirm no considerably-overlapping project already exists before creating one.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `{}` — no arguments.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {},
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{}
```
**Binding template**
```json
{}
```
**Returns**
- `projects` — array; required. Projects reachable by the authenticated principal, filtered by its project allowlist and ordered newest first. An empty array means none are reachable.
- `projects[]` — object; required.
- `projects[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `projects[].workspaceId` — string; required. Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
- `projects[].name` — string; required. Human-readable name displayed in Semel.
- `projects[].reviewMode` — "direct" | "propose"; required. Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
- `projects[].ownerId` — string; optional. Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value.
- `projects[].delivery` — object; optional. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value.
- `projects[].delivery.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `projects[].delivery.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `projects[].delivery.deliveryStatus (anyOf branch 2)` — null; required.
- `projects[].delivery.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `projects[].delivery.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `projects[].delivery.changedAt (anyOf branch 1)` — string; required; format date-time.
- `projects[].delivery.changedAt (anyOf branch 2)` — null; required.
- `projects[].delivery.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `projects[].delivery.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `projects[].delivery.source (anyOf branch 1)` — "web" | "mcp"; required.
- `projects[].delivery.source (anyOf branch 2)` — null; required.
- `projects[].createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"projects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"workspaceId": {
"type": "string",
"description": "Workspace identifier that owns the record; it is resolved from authenticated Semel membership."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"reviewMode": {
"type": "string",
"enum": [
"direct",
"propose"
],
"description": "Project review interaction mode configured in Semel. Allowed values: \"direct\", \"propose\"."
},
"ownerId": {
"type": "string",
"description": "Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value."
},
"delivery": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"workspaceId",
"name",
"reviewMode",
"createdAt"
],
"additionalProperties": false
},
"description": "Projects reachable by the authenticated principal, filtered by its project allowlist and ordered newest first. An empty array means none are reachable."
}
},
"required": [
"projects"
],
"additionalProperties": false
}
```
**Example structured result (project-list)**
```json
{
"projects": []
}
```
Bindings: projects from structuredContent.projects.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"projects\":[]}"
}
],
"structuredContent": {
"projects": []
}
}
```
Next permitted action: Reuse one exact match, ask about ambiguity, or prepare project_create.
**Example requests**
- “/semel list my projects”
- “/semel what projects do I have?”
Errors: universal authentication and validation errors only.
Related operations: `project_get`, `project_create`.
---
### project_rename
Rename a project (name only). Requires the accountable human to be the project creator or the workspace owner (the same guard as the portal). Use to correct or update a project's display name.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `brief:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project identifier returned by project_create or project_list; the accountable human must be the project creator or workspace owner.
- `name` — string; required; minimum length 1; maximum length 200. Replacement project display name after trimming, from 1 through 200 characters. A successful call durably renames the project.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project identifier returned by project_create or project_list; the accountable human must be the project creator or workspace owner."
},
"name": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Replacement project display name after trimming, from 1 through 200 characters. A successful call durably renames the project."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"projectId",
"name",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"name": "Payments reliability",
"idempotencyKey": "recipe-project-rename-v1"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"name": "Payments reliability",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `project` — object; required. Canonical project record returned after authorization and, for project_rename, after the durable name update succeeds.
- `project.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `project.workspaceId` — string; required. Workspace identifier that owns the record; it is resolved from authenticated Semel membership.
- `project.name` — string; required. Human-readable name displayed in Semel.
- `project.reviewMode` — "direct" | "propose"; required. Project review interaction mode configured in Semel. Allowed values: "direct", "propose".
- `project.ownerId` — string; optional. Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value.
- `project.delivery` — object; optional. Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value.
- `project.delivery.deliveryStatus` — JSON value; required. Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state.
- `project.delivery.deliveryStatus (anyOf branch 1)` — "built" | "shipped" | "deployed"; required.
- `project.delivery.deliveryStatus (anyOf branch 2)` — null; required.
- `project.delivery.deliveryStatusVersion` — integer; required; minimum 0. Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write.
- `project.delivery.changedAt` — JSON value; required. RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero.
- `project.delivery.changedAt (anyOf branch 1)` — string; required; format date-time.
- `project.delivery.changedAt (anyOf branch 2)` — null; required.
- `project.delivery.changedById` — string | null; required. Accountable user identifier for the latest committed delivery change; null while no change has been recorded.
- `project.delivery.source` — JSON value; required. Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset.
- `project.delivery.source (anyOf branch 1)` — "web" | "mcp"; required.
- `project.delivery.source (anyOf branch 2)` — null; required.
- `project.createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"project": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"workspaceId": {
"type": "string",
"description": "Workspace identifier that owns the record; it is resolved from authenticated Semel membership."
},
"name": {
"type": "string",
"description": "Human-readable name displayed in Semel."
},
"reviewMode": {
"type": "string",
"enum": [
"direct",
"propose"
],
"description": "Project review interaction mode configured in Semel. Allowed values: \"direct\", \"propose\"."
},
"ownerId": {
"type": "string",
"description": "Accountable Semel user identifier recorded as the project owner. Omit the field when it does not apply; omission is distinct from an empty value."
},
"delivery": {
"type": "object",
"properties": {
"deliveryStatus": {
"anyOf": [
{
"type": "string",
"enum": [
"built",
"shipped",
"deployed"
]
},
{
"type": "null"
}
],
"description": "Explicit operator-asserted delivery state; null means it has not been marked and never implies review or approval state."
},
"deliveryStatusVersion": {
"type": "integer",
"minimum": 0,
"description": "Monotonic optimistic-concurrency version; copy this value into ifDeliveryStatusVersion for the next deliberate write."
},
"changedAt": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"description": "RFC 3339 time of the latest committed delivery change; null while delivery status remains unset at version zero."
},
"changedById": {
"type": [
"string",
"null"
],
"description": "Accountable user identifier for the latest committed delivery change; null while no change has been recorded."
},
"source": {
"anyOf": [
{
"type": "string",
"enum": [
"web",
"mcp"
]
},
{
"type": "null"
}
],
"description": "Trusted transport that committed the latest delivery change: web for a human request, MCP for an agent request, or null when unset."
}
},
"required": [
"deliveryStatus",
"deliveryStatusVersion",
"changedAt",
"changedById",
"source"
],
"additionalProperties": false,
"description": "Current explicit delivery-status projection; it is independent from brief review, approval, and contract-version state. Omit the field when it does not apply; omission is distinct from an empty value."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
}
},
"required": [
"id",
"workspaceId",
"name",
"reviewMode",
"createdAt"
],
"additionalProperties": false,
"description": "Canonical project record returned after authorization and, for project_rename, after the durable name update succeeds."
}
},
"required": [
"project"
],
"additionalProperties": false
}
```
**Example structured result (project-renamed)**
```json
{
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Payments reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
```
Bindings: renamedProject from structuredContent.project.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"project\":{\"id\":\"prj_fixture_checkout\",\"workspaceId\":\"ws_fixture_primary\",\"name\":\"Payments reliability\",\"reviewMode\":\"direct\",\"createdAt\":\"2026-09-07T16:00:00.000Z\"}}"
}
],
"structuredContent": {
"project": {
"id": "prj_fixture_checkout",
"workspaceId": "ws_fixture_primary",
"name": "Payments reliability",
"reviewMode": "direct",
"createdAt": "2026-09-07T16:00:00.000Z"
}
}
}
```
Next permitted action: Keep the same project id after the rename.
**Example requests**
- “/semel rename this project to Checkout v2”
- “/semel change the billing project name to Payments”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `project_get`, `project_list`.
---
### review_cancel
Cancel a review the agent originated — directly for an inert pre-claim local-intent run, by requesting cancellation of an in-progress run (a live harness finishes it), or by finalizing a released local run now.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:run`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `runId` — string; required; minimum length 1. Review-run identifier returned by a review start, status, or cascade handoff result. Minimum accepted length or value is 1.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"runId": {
"type": "string",
"minLength": 1,
"description": "Review-run identifier returned by a review start, status, or cascade handoff result. Minimum accepted length or value is 1."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"runId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"runId": "run_fixture_followup",
"idempotencyKey": "recipe-review-cancel-v1"
}
```
**Binding template**
```json
{
"runId": "{{newRunId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `outcome` — "cancelled" | "cancel_requested"; required. Typed result of this operation; union branches define the follow-up action for each value. Allowed values: "cancelled", "cancel_requested".
- `status` — "queued" | "invoking" | "running" | "waiting_input" | "completed" | "failed" | "cancelled" | "needs_attention" | "suspended"; required. Current typed status; the schema enum or union branch lists every allowed value. Allowed values: "queued", "invoking", "running", "waiting_input", "completed", "failed", "cancelled", "needs_attention", "suspended".
- `claimed` — boolean; optional. Whether the external execution currently has an active claimed epoch. Omit the field when it does not apply; omission is distinct from an empty value.
- `finalized` — boolean; optional. Whether this run has reached its terminal finalization step. Omit the field when it does not apply; omission is distinct from an empty value.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"runId": {
"type": "string",
"description": "Review-run identifier returned by a review start, status, or cascade handoff result."
},
"outcome": {
"type": "string",
"enum": [
"cancelled",
"cancel_requested"
],
"description": "Typed result of this operation; union branches define the follow-up action for each value. Allowed values: \"cancelled\", \"cancel_requested\"."
},
"status": {
"type": "string",
"enum": [
"queued",
"invoking",
"running",
"waiting_input",
"completed",
"failed",
"cancelled",
"needs_attention",
"suspended"
],
"description": "Current typed status; the schema enum or union branch lists every allowed value. Allowed values: \"queued\", \"invoking\", \"running\", \"waiting_input\", \"completed\", \"failed\", \"cancelled\", \"needs_attention\", \"suspended\"."
},
"claimed": {
"type": "boolean",
"description": "Whether the external execution currently has an active claimed epoch. Omit the field when it does not apply; omission is distinct from an empty value."
},
"finalized": {
"type": "boolean",
"description": "Whether this run has reached its terminal finalization step. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"runId",
"outcome",
"status"
],
"additionalProperties": false
}
```
**Example structured result (cancel-requested)**
```json
{
"runId": "run_fixture_followup",
"outcome": "cancel_requested",
"status": "queued"
}
```
Bindings: cancelOutcome from structuredContent.outcome.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"runId\":\"run_fixture_followup\",\"outcome\":\"cancel_requested\",\"status\":\"queued\"}"
}
],
"structuredContent": {
"runId": "run_fixture_followup",
"outcome": "cancel_requested",
"status": "queued"
}
}
```
Next permitted action: Stop local work and follow the authoritative returned status.
**Example requests**
- “/semel cancel that review — I did not mean to start it”
Errors: `RUN_ALREADY_TERMINAL`, `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `review_start`, `review_status`, `review_execution_release`.
---
### review_config_get
Inspect the configured reviewers before editing or starting a cascade.
- Mode: read
- Risk: low
- Scopes: `brief:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project whose review cascade is being inspected or configured.
- `phase` — "pre_build" | "staging" | "post_deploy"; required. Cascade phase to inspect or configure: pre_build, staging, or post_deploy.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project whose review cascade is being inspected or configured."
},
"phase": {
"type": "string",
"enum": [
"pre_build",
"staging",
"post_deploy"
],
"description": "Cascade phase to inspect or configure: pre_build, staging, or post_deploy."
}
},
"required": [
"projectId",
"phase"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"phase": "pre_build"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"phase": "pre_build"
}
```
**Returns**
- `phase` — "pre_build" | "staging" | "post_deploy"; required. Cascade phase to inspect or configure: pre_build, staging, or post_deploy.
- `steps` — array; required. All configured steps in this phase, sorted by their execution position.
- `steps[]` — object; required.
- `steps[].id` — string; required. Stable identifier of this cascade step or human review assignment.
- `steps[].projectId` — string; required. Project whose review cascade is being inspected or configured.
- `steps[].phase` — "pre_build" | "staging" | "post_deploy"; required. Cascade phase to inspect or configure: pre_build, staging, or post_deploy.
- `steps[].position` — integer; required. Zero-based position used to order the steps within this phase.
- `steps[].kind` — "ai" | "human"; required. Step execution kind: an AI reviewer or a human approval gate.
- `steps[].config` — JSON value; optional. Executable reviewer settings or identity-bound human approval settings for this step.
- `steps[].config (anyOf branch 1)` — JSON value; optional.
- `steps[].config (anyOf branch 2)` — null; optional.
- `steps[].status` — "pending" | "active" | "done" | "skipped"; required. Current lifecycle status of the cascade step or human review assignment.
- `steps[].createdAt` — string; required. Timestamp when this cascade configuration step was created.
- `steps[].updatedAt` — string; required. Timestamp of the most recent change to this cascade step.
- `watchers` — array; optional; default []. Project-level document watchers; these people do not participate as cascade steps.
- `watchers[]` — object; required.
- `watchers[].id` — string; required. Stable identifier of this cascade step or human review assignment.
- `watchers[].assigneeEmail` — string; required; format email. Email address of the human assigned to this review or approval.
- `watchers[].assigneeUserId` — string | null; required. Workspace user assigned to this human review, or null when an invitation is pending.
- `watchers[].status` — "pending" | "assigned" | "completed" | "revoked"; required. Current lifecycle status of the cascade step or human review assignment.
- `watchers[].inviteId` — string | null; required. Active invitation identifier for a pending human reviewer, when one exists.
- `watchers[].inviteSentAt` — string | null; required. Timestamp of the most recent send for the active invitation, or null if not sent.
- `anyRunActive` — boolean; required. Whether any phase of this project has a nonterminal review run; MCP writes refuse while true.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"pre_build",
"staging",
"post_deploy"
],
"description": "Cascade phase to inspect or configure: pre_build, staging, or post_deploy."
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier of this cascade step or human review assignment."
},
"projectId": {
"type": "string",
"description": "Project whose review cascade is being inspected or configured."
},
"phase": {
"type": "string",
"enum": [
"pre_build",
"staging",
"post_deploy"
],
"description": "Cascade phase to inspect or configure: pre_build, staging, or post_deploy."
},
"position": {
"type": "integer",
"description": "Zero-based position used to order the steps within this phase."
},
"kind": {
"type": "string",
"enum": [
"ai",
"human"
],
"description": "Step execution kind: an AI reviewer or a human approval gate."
},
"config": {
"anyOf": [
{},
{
"type": "null"
}
],
"description": "Executable reviewer settings or identity-bound human approval settings for this step."
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"done",
"skipped"
],
"description": "Current lifecycle status of the cascade step or human review assignment."
},
"createdAt": {
"type": "string",
"description": "Timestamp when this cascade configuration step was created."
},
"updatedAt": {
"type": "string",
"description": "Timestamp of the most recent change to this cascade step."
}
},
"required": [
"id",
"projectId",
"phase",
"position",
"kind",
"status",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
"description": "All configured steps in this phase, sorted by their execution position."
},
"watchers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier of this cascade step or human review assignment."
},
"assigneeEmail": {
"type": "string",
"format": "email",
"description": "Email address of the human assigned to this review or approval."
},
"assigneeUserId": {
"type": [
"string",
"null"
],
"description": "Workspace user assigned to this human review, or null when an invitation is pending."
},
"status": {
"type": "string",
"enum": [
"pending",
"assigned",
"completed",
"revoked"
],
"description": "Current lifecycle status of the cascade step or human review assignment."
},
"inviteId": {
"type": [
"string",
"null"
],
"description": "Active invitation identifier for a pending human reviewer, when one exists."
},
"inviteSentAt": {
"type": [
"string",
"null"
],
"description": "Timestamp of the most recent send for the active invitation, or null if not sent."
}
},
"required": [
"id",
"assigneeEmail",
"assigneeUserId",
"status",
"inviteId",
"inviteSentAt"
],
"additionalProperties": false
},
"default": [],
"description": "Project-level document watchers; these people do not participate as cascade steps."
},
"anyRunActive": {
"type": "boolean",
"description": "Whether any phase of this project has a nonterminal review run; MCP writes refuse while true."
}
},
"required": [
"phase",
"steps",
"anyRunActive"
],
"additionalProperties": false
}
```
**Example structured result (idle-configuration)**
```json
{
"phase": "pre_build",
"steps": [
{
"id": "cst_fixture_product",
"projectId": "prj_fixture_checkout",
"phase": "pre_build",
"position": 0,
"kind": "ai",
"status": "pending",
"createdAt": "example",
"updatedAt": "example",
"config": {
"reviewers": [
"product"
]
}
}
],
"anyRunActive": false
}
```
Bindings: existingConfigStepId from structuredContent.steps[0].id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"phase\":\"pre_build\",\"steps\":[{\"id\":\"cst_fixture_product\",\"projectId\":\"prj_fixture_checkout\",\"phase\":\"pre_build\",\"position\":0,\"kind\":\"ai\",\"status\":\"pending\",\"createdAt\":\"example\",\"updatedAt\":\"example\",\"config\":{\"reviewers\":[\"product\"]}}],\"anyRunActive\":false}"
}
],
"structuredContent": {
"phase": "pre_build",
"steps": [
{
"id": "cst_fixture_product",
"projectId": "prj_fixture_checkout",
"phase": "pre_build",
"position": 0,
"kind": "ai",
"status": "pending",
"createdAt": "example",
"updatedAt": "example",
"config": {
"reviewers": [
"product"
]
}
}
],
"anyRunActive": false
}
}
```
Next permitted action: Use the returned step IDs. Preserve all returned IDs when reordering a larger cascade.
**Example requests**
- “/semel show this project’s reviewers”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `review_config_get`, `review_start`.
---
### review_config_reorder
Set the reviewer order while the project cascade is idle; include every step ID exactly once.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:configure`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `phase` — "pre_build" | "staging" | "post_deploy"; required. Cascade phase to inspect or configure: pre_build, staging, or post_deploy.
- `stepIds` — array; required; minimum items 1. Every current step ID in the phase exactly once, in the desired execution order.
- `stepIds[]` — string; required.
- `projectId` — string; required; minimum length 1. Project whose review cascade is being inspected or configured.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"pre_build",
"staging",
"post_deploy"
],
"description": "Cascade phase to inspect or configure: pre_build, staging, or post_deploy."
},
"stepIds": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "Every current step ID in the phase exactly once, in the desired execution order."
},
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project whose review cascade is being inspected or configured."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"phase",
"stepIds",
"projectId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"phase": "pre_build",
"stepIds": [
"cst_fixture_security",
"cst_fixture_product"
],
"idempotencyKey": "recipe-configuration-reorder-v1"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"phase": "pre_build",
"stepIds": [
"{{addedConfigStepId}}",
"{{existingConfigStepId}}"
],
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `phase` — "pre_build" | "staging" | "post_deploy"; required. Cascade phase to inspect or configure: pre_build, staging, or post_deploy.
- `steps` — array; required. All configured steps in this phase, sorted by their execution position.
- `steps[]` — object; required.
- `steps[].id` — string; required. Stable identifier of this cascade step or human review assignment.
- `steps[].projectId` — string; required. Project whose review cascade is being inspected or configured.
- `steps[].phase` — "pre_build" | "staging" | "post_deploy"; required. Cascade phase to inspect or configure: pre_build, staging, or post_deploy.
- `steps[].position` — integer; required. Zero-based position used to order the steps within this phase.
- `steps[].kind` — "ai" | "human"; required. Step execution kind: an AI reviewer or a human approval gate.
- `steps[].config` — JSON value; optional. Executable reviewer settings or identity-bound human approval settings for this step.
- `steps[].config (anyOf branch 1)` — JSON value; optional.
- `steps[].config (anyOf branch 2)` — null; optional.
- `steps[].status` — "pending" | "active" | "done" | "skipped"; required. Current lifecycle status of the cascade step or human review assignment.
- `steps[].createdAt` — string; required. Timestamp when this cascade configuration step was created.
- `steps[].updatedAt` — string; required. Timestamp of the most recent change to this cascade step.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"pre_build",
"staging",
"post_deploy"
],
"description": "Cascade phase to inspect or configure: pre_build, staging, or post_deploy."
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier of this cascade step or human review assignment."
},
"projectId": {
"type": "string",
"description": "Project whose review cascade is being inspected or configured."
},
"phase": {
"type": "string",
"enum": [
"pre_build",
"staging",
"post_deploy"
],
"description": "Cascade phase to inspect or configure: pre_build, staging, or post_deploy."
},
"position": {
"type": "integer",
"description": "Zero-based position used to order the steps within this phase."
},
"kind": {
"type": "string",
"enum": [
"ai",
"human"
],
"description": "Step execution kind: an AI reviewer or a human approval gate."
},
"config": {
"anyOf": [
{},
{
"type": "null"
}
],
"description": "Executable reviewer settings or identity-bound human approval settings for this step."
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"done",
"skipped"
],
"description": "Current lifecycle status of the cascade step or human review assignment."
},
"createdAt": {
"type": "string",
"description": "Timestamp when this cascade configuration step was created."
},
"updatedAt": {
"type": "string",
"description": "Timestamp of the most recent change to this cascade step."
}
},
"required": [
"id",
"projectId",
"phase",
"position",
"kind",
"status",
"createdAt",
"updatedAt"
],
"additionalProperties": false
},
"description": "All configured steps in this phase, sorted by their execution position."
}
},
"required": [
"phase",
"steps"
],
"additionalProperties": false
}
```
**Example structured result (reviewers-reordered)**
```json
{
"phase": "pre_build",
"steps": [
{
"id": "cst_fixture_security",
"projectId": "prj_fixture_checkout",
"phase": "pre_build",
"position": 0,
"kind": "ai",
"status": "pending",
"createdAt": "example",
"updatedAt": "example",
"config": {
"reviewers": [
"security"
]
}
},
{
"id": "cst_fixture_product",
"projectId": "prj_fixture_checkout",
"phase": "pre_build",
"position": 1,
"kind": "ai",
"status": "pending",
"createdAt": "example",
"updatedAt": "example",
"config": {
"reviewers": [
"product"
]
}
}
]
}
```
Bindings: addedConfigStepId from structuredContent.steps[0].id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"phase\":\"pre_build\",\"steps\":[{\"id\":\"cst_fixture_security\",\"projectId\":\"prj_fixture_checkout\",\"phase\":\"pre_build\",\"position\":0,\"kind\":\"ai\",\"status\":\"pending\",\"createdAt\":\"example\",\"updatedAt\":\"example\",\"config\":{\"reviewers\":[\"security\"]}},{\"id\":\"cst_fixture_product\",\"projectId\":\"prj_fixture_checkout\",\"phase\":\"pre_build\",\"position\":1,\"kind\":\"ai\",\"status\":\"pending\",\"createdAt\":\"example\",\"updatedAt\":\"example\",\"config\":{\"reviewers\":[\"product\"]}}]}"
}
],
"structuredContent": {
"phase": "pre_build",
"steps": [
{
"id": "cst_fixture_security",
"projectId": "prj_fixture_checkout",
"phase": "pre_build",
"position": 0,
"kind": "ai",
"status": "pending",
"createdAt": "example",
"updatedAt": "example",
"config": {
"reviewers": [
"security"
]
}
},
{
"id": "cst_fixture_product",
"projectId": "prj_fixture_checkout",
"phase": "pre_build",
"position": 1,
"kind": "ai",
"status": "pending",
"createdAt": "example",
"updatedAt": "example",
"config": {
"reviewers": [
"product"
]
}
}
]
}
}
```
Next permitted action: Verify the returned order. A later requested removal uses its exact returned step ID.
**Example requests**
- “/semel put Security before Engineering”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `review_config_get`, `review_start`.
---
### review_config_step_add
Append a reviewer while the project cascade is idle, with the same owner or creator permission as the portal.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:configure`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `phase` — "pre_build" | "staging" | "post_deploy"; required. Cascade phase to inspect or configure: pre_build, staging, or post_deploy.
- `kind` — "ai" | "human"; required. Step execution kind: an AI reviewer or a human approval gate.
- `config` — JSON value; required. Settings for the selected step kind; AI steps require exactly one reviewer role.
- `config (anyOf branch 1)` — object; required.
- `config (anyOf branch 1).reviewers` — array; required; minimum items 1; maximum items 1. Exactly one vendor reviewer role for this AI step, such as product or security.
- `config (anyOf branch 1).reviewers[]` — "product" | "engineering" | "design" | "security" | "test"; required.
- `config (anyOf branch 1).provider` — "anthropic" | "openai"; optional. Optional model provider; it must match the provider of the selected exact model.
- `config (anyOf branch 1).model` — string; optional. Optional exact executable model ID from the reviewer model catalog.
- `config (anyOf branch 1).reasoning` — "none" | "low" | "medium" | "high" | "xhigh" | "max"; optional. Optional reasoning level supported by the selected exact model.
- `config (anyOf branch 2)` — JSON value; required.
- `config (anyOf branch 2) (anyOf branch 1)` — object; required.
- `config (anyOf branch 2) (anyOf branch 1).assignmentId` — string; optional; minimum length 1. Identity-bound human review assignment; the server binds newly added gates to the caller.
- `config (anyOf branch 2) (anyOf branch 1).assigneeUserId` — string; optional; minimum length 1. Workspace user assigned to this human review, or null when an invitation is pending.
- `config (anyOf branch 2) (anyOf branch 1).inviteId` — string; optional; minimum length 1. Active invitation identifier for a pending human reviewer, when one exists.
- `config (anyOf branch 2) (anyOf branch 1).assigneeEmail` — string; optional; format email. Email address of the human assigned to this review or approval.
- `config (anyOf branch 2) (anyOf branch 1).duty` — "reviewer" | "approver"; optional. Human participation role: reviewer watches the document; approver owns an approval gate.
- `config (anyOf branch 2) (anyOf branch 1).approverName` — string; optional; minimum length 1; maximum length 200. Optional legacy display name for the human approval gate.
- `config (anyOf branch 2) (anyOf branch 1).approverRole` — string; optional; minimum length 1; maximum length 200. Optional legacy description of the human approver’s role.
- `config (anyOf branch 2) (anyOf branch 2)` — null; required.
- `projectId` — string; required; minimum length 1. Project whose review cascade is being inspected or configured.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"phase": {
"type": "string",
"enum": [
"pre_build",
"staging",
"post_deploy"
],
"description": "Cascade phase to inspect or configure: pre_build, staging, or post_deploy."
},
"kind": {
"type": "string",
"enum": [
"ai",
"human"
],
"description": "Step execution kind: an AI reviewer or a human approval gate."
},
"config": {
"anyOf": [
{
"type": "object",
"properties": {
"reviewers": {
"type": "array",
"items": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
"minItems": 1,
"maxItems": 1,
"description": "Exactly one vendor reviewer role for this AI step, such as product or security."
},
"provider": {
"type": "string",
"enum": [
"anthropic",
"openai"
],
"description": "Optional model provider; it must match the provider of the selected exact model."
},
"model": {
"type": "string",
"description": "Optional exact executable model ID from the reviewer model catalog."
},
"reasoning": {
"type": "string",
"enum": [
"none",
"low",
"medium",
"high",
"xhigh",
"max"
],
"description": "Optional reasoning level supported by the selected exact model."
}
},
"required": [
"reviewers"
],
"additionalProperties": false
},
{
"anyOf": [
{
"type": "object",
"properties": {
"assignmentId": {
"type": "string",
"minLength": 1,
"description": "Identity-bound human review assignment; the server binds newly added gates to the caller."
},
"assigneeUserId": {
"type": "string",
"minLength": 1,
"description": "Workspace user assigned to this human review, or null when an invitation is pending."
},
"inviteId": {
"type": "string",
"minLength": 1,
"description": "Active invitation identifier for a pending human reviewer, when one exists."
},
"assigneeEmail": {
"type": "string",
"format": "email",
"description": "Email address of the human assigned to this review or approval."
},
"duty": {
"type": "string",
"enum": [
"reviewer",
"approver"
],
"description": "Human participation role: reviewer watches the document; approver owns an approval gate."
},
"approverName": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional legacy display name for the human approval gate."
},
"approverRole": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional legacy description of the human approver’s role."
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
],
"description": "Settings for the selected step kind; AI steps require exactly one reviewer role."
},
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project whose review cascade is being inspected or configured."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"phase",
"kind",
"config",
"projectId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"phase": "pre_build",
"kind": "ai",
"config": {
"reviewers": [
"security"
]
},
"idempotencyKey": "recipe-configuration-add-v1"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"phase": "pre_build",
"kind": "ai",
"config": {
"reviewers": [
"security"
]
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `step` — object; required. The persisted cascade step after the requested configuration change.
- `step.id` — string; required. Stable identifier of this cascade step or human review assignment.
- `step.projectId` — string; required. Project whose review cascade is being inspected or configured.
- `step.phase` — "pre_build" | "staging" | "post_deploy"; required. Cascade phase to inspect or configure: pre_build, staging, or post_deploy.
- `step.position` — integer; required. Zero-based position used to order the steps within this phase.
- `step.kind` — "ai" | "human"; required. Step execution kind: an AI reviewer or a human approval gate.
- `step.config` — JSON value; optional. Executable reviewer settings or identity-bound human approval settings for this step.
- `step.config (anyOf branch 1)` — JSON value; optional.
- `step.config (anyOf branch 2)` — null; optional.
- `step.status` — "pending" | "active" | "done" | "skipped"; required. Current lifecycle status of the cascade step or human review assignment.
- `step.createdAt` — string; required. Timestamp when this cascade configuration step was created.
- `step.updatedAt` — string; required. Timestamp of the most recent change to this cascade step.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"step": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier of this cascade step or human review assignment."
},
"projectId": {
"type": "string",
"description": "Project whose review cascade is being inspected or configured."
},
"phase": {
"type": "string",
"enum": [
"pre_build",
"staging",
"post_deploy"
],
"description": "Cascade phase to inspect or configure: pre_build, staging, or post_deploy."
},
"position": {
"type": "integer",
"description": "Zero-based position used to order the steps within this phase."
},
"kind": {
"type": "string",
"enum": [
"ai",
"human"
],
"description": "Step execution kind: an AI reviewer or a human approval gate."
},
"config": {
"anyOf": [
{},
{
"type": "null"
}
],
"description": "Executable reviewer settings or identity-bound human approval settings for this step."
},
"status": {
"type": "string",
"enum": [
"pending",
"active",
"done",
"skipped"
],
"description": "Current lifecycle status of the cascade step or human review assignment."
},
"createdAt": {
"type": "string",
"description": "Timestamp when this cascade configuration step was created."
},
"updatedAt": {
"type": "string",
"description": "Timestamp of the most recent change to this cascade step."
}
},
"required": [
"id",
"projectId",
"phase",
"position",
"kind",
"status",
"createdAt",
"updatedAt"
],
"additionalProperties": false,
"description": "The persisted cascade step after the requested configuration change."
}
},
"required": [
"step"
],
"additionalProperties": false
}
```
**Example structured result (reviewer-added)**
```json
{
"step": {
"id": "cst_fixture_security",
"projectId": "prj_fixture_checkout",
"phase": "pre_build",
"position": 1,
"kind": "ai",
"status": "pending",
"createdAt": "example",
"updatedAt": "example",
"config": {
"reviewers": [
"security"
]
}
}
}
```
Bindings: addedConfigStepId from structuredContent.step.id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"step\":{\"id\":\"cst_fixture_security\",\"projectId\":\"prj_fixture_checkout\",\"phase\":\"pre_build\",\"position\":1,\"kind\":\"ai\",\"status\":\"pending\",\"createdAt\":\"example\",\"updatedAt\":\"example\",\"config\":{\"reviewers\":[\"security\"]}}}"
}
],
"structuredContent": {
"step": {
"id": "cst_fixture_security",
"projectId": "prj_fixture_checkout",
"phase": "pre_build",
"position": 1,
"kind": "ai",
"status": "pending",
"createdAt": "example",
"updatedAt": "example",
"config": {
"reviewers": [
"security"
]
}
}
}
}
```
Next permitted action: Carry the added step ID into the requested reorder.
**Example requests**
- “/semel add an Engineering reviewer”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `review_config_get`, `review_start`.
---
### review_config_step_remove
Remove an untouched pending or skipped reviewer while the project cascade is idle. Steps with run history cannot be removed.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:configure`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `projectId` — string; required; minimum length 1. Project whose review cascade is being inspected or configured.
- `stepId` — string; required; minimum length 1. Identifier of the cascade step to remove, obtained from review_config_get.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"minLength": 1,
"description": "Project whose review cascade is being inspected or configured."
},
"stepId": {
"type": "string",
"minLength": 1,
"description": "Identifier of the cascade step to remove, obtained from review_config_get."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"projectId",
"stepId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"projectId": "prj_fixture_checkout",
"stepId": "cst_fixture_security",
"idempotencyKey": "recipe-configuration-remove-v1"
}
```
**Binding template**
```json
{
"projectId": "{{projectId}}",
"stepId": "{{addedConfigStepId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `deleted` — constant true; required. True only after the untouched cascade step has been removed successfully.
- `stepId` — string; required. Identifier of the cascade step to remove, obtained from review_config_get.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"deleted": {
"type": "boolean",
"const": true,
"description": "True only after the untouched cascade step has been removed successfully."
},
"stepId": {
"type": "string",
"description": "Identifier of the cascade step to remove, obtained from review_config_get."
}
},
"required": [
"deleted",
"stepId"
],
"additionalProperties": false
}
```
**Example structured result (reviewer-removed)**
```json
{
"deleted": true,
"stepId": "cst_fixture_security"
}
```
Bindings: addedConfigStepId from structuredContent.stepId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"deleted\":true,\"stepId\":\"cst_fixture_security\"}"
}
],
"structuredContent": {
"deleted": true,
"stepId": "cst_fixture_security"
}
}
```
Next permitted action: Read review_config_get again to confirm the final cascade before starting it.
**Example requests**
- “/semel remove the Design and Test reviewers”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `review_config_get`, `review_start`.
---
### review_execution_checkpoint_append
Append one bounded semantic checkpoint milestone to the current fenced epoch.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `seq` — integer; required. Positive checkpoint event sequence within the current fence generation. Minimum accepted length or value is 0. The value must be an integer.
- `activeSkillId` — string; optional; minimum length 1; maximum length 200. Pinned active-skill identifier for this checkpoint; omit only before the first skill activation. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `milestoneName` — string; required; minimum length 1; maximum length 200. Short caller-chosen name for the completed execution milestone represented by this checkpoint. Accepted length or value is 1 through 200, inclusive.
- `safeSummary` — string; optional; maximum length 8192. Short progress summary safe for durable storage and display; never include secrets, reasoning, or raw source. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 8192.
- `receipt` — object; optional. Optional structured progress receipt; forbidden reasoning, raw-tool-output, prompt, and source fields are rejected recursively. Omit the field when it does not apply; omission is distinct from an empty value.
- `receipt{key}` — JSON value; optional.
- `clientObservedAt` — string; optional; format date-time. Optional RFC 3339 client timestamp for display only; server sequence controls ordering. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"seq": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Positive checkpoint event sequence within the current fence generation. Minimum accepted length or value is 0. The value must be an integer."
},
"activeSkillId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Pinned active-skill identifier for this checkpoint; omit only before the first skill activation. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"milestoneName": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Short caller-chosen name for the completed execution milestone represented by this checkpoint. Accepted length or value is 1 through 200, inclusive."
},
"safeSummary": {
"type": "string",
"maxLength": 8192,
"description": "Short progress summary safe for durable storage and display; never include secrets, reasoning, or raw source. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 8192."
},
"receipt": {
"type": "object",
"additionalProperties": {},
"description": "Optional structured progress receipt; forbidden reasoning, raw-tool-output, prompt, and source fields are rejected recursively. Omit the field when it does not apply; omission is distinct from an empty value."
},
"clientObservedAt": {
"type": "string",
"format": "date-time",
"description": "Optional RFC 3339 client timestamp for display only; server sequence controls ordering. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"seq",
"milestoneName",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"seq": 1,
"activeSkillId": "engineering",
"milestoneName": "skill_start",
"safeSummary": "Started the pinned engineering skill.",
"receipt": {
"skillRole": "engineering",
"skillSha256": "182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7"
},
"clientObservedAt": "2026-09-07T16:00:00.000Z",
"idempotencyKey": "recipe-execution-checkpoint-skill-start-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"seq": 1,
"activeSkillId": "engineering",
"milestoneName": "skill_start",
"safeSummary": "Started the pinned engineering skill.",
"receipt": {
"skillRole": "engineering",
"skillSha256": "{{skillSha256}}"
},
"clientObservedAt": "2026-09-07T16:00:00.000Z",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `accepted` — constant true; required. Confirms that the checkpoint or answer was durably accepted. This branch always uses true.
- `seq` — integer; required. Positive checkpoint event sequence within the current fence generation. The value must be an integer.
- `highWaterMark` — integer; required. Highest checkpoint sequence durably accepted after this append. The value must be an integer.
- `suggestedNextPollAt` — string; required. RFC 3339 timestamp for the next recommended sync or status poll.
- `coalesce` — boolean; required. Whether Semel recommends coalescing further nonterminal updates for the same stage.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"accepted": {
"type": "boolean",
"const": true,
"description": "Confirms that the checkpoint or answer was durably accepted. This branch always uses true."
},
"seq": {
"type": "integer",
"description": "Positive checkpoint event sequence within the current fence generation. The value must be an integer."
},
"highWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted after this append. The value must be an integer."
},
"suggestedNextPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended sync or status poll."
},
"coalesce": {
"type": "boolean",
"description": "Whether Semel recommends coalescing further nonterminal updates for the same stage."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"accepted",
"seq",
"highWaterMark",
"suggestedNextPollAt",
"coalesce",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (checkpoint-accepted)**
```json
{
"accepted": true,
"seq": 1,
"highWaterMark": 1,
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"coalesce": false,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 1,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Bindings: checkpoint1HighWaterMark from structuredContent.highWaterMark.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"accepted\":true,\"seq\":1,\"highWaterMark\":1,\"suggestedNextPollAt\":\"2026-09-07T16:05:00.000Z\",\"coalesce\":false,\"controlBlock\":{\"state\":{\"sessionState\":\"running\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_skill_get\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_checkpoint_append\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_heartbeat\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_question_open\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_submit\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_release\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_sync\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":1,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}}}"
}
],
"structuredContent": {
"accepted": true,
"seq": 1,
"highWaterMark": 1,
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"coalesce": false,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 1,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Next permitted action: Inspect evidence readiness before drawing conclusions.
**Example requests**
- “report skill_start progress for the active reviewer skill”
Errors: `STALE_FENCE`, `SEQUENCE_GAP`, `CONFLICTING_IDEMPOTENCY_REPLAY`, `PAYLOAD_REJECTED`, `VALIDATION_FAILED`, `EVIDENCE_BINDING_UNKNOWN_REPOSITORY`, `CANCELLED`.
Related operations: `review_execution_sync`, `review_execution_status`.
---
### review_execution_claim
Claim a review session for external execution, pinning the frozen canonical bundle.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:execute`
- Confirmation: implicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `grantId` — string; required; minimum length 1. Execution-grant identifier returned when the human approval boundary is satisfied. Minimum accepted length or value is 1.
- `reviewSessionId` — string; required; minimum length 1. Review-session identifier returned by review_start, review_new_pass, or execution status. Minimum accepted length or value is 1.
- `supportedProtocolVersions` — array; required; minimum items 1. Protocol versions the harness can execute, ordered by its preference. An empty array explicitly means no matching items.
- `supportedProtocolVersions[]` — string; required; minimum length 1.
- `harnessDescriptor` — object; required. Self-declared harness, agent, model, and supported-protocol metadata recorded on the execution claim for compatibility and audit.
- `harnessDescriptor.harness` — string; required; minimum length 1; maximum length 200. Harness product name declared by the caller; Semel does not independently verify it. Accepted length or value is 1 through 200, inclusive.
- `harnessDescriptor.harnessVersion` — string; optional; minimum length 1; maximum length 100. Optional harness version declared by the caller. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `harnessDescriptor.agent` — string; optional; minimum length 1; maximum length 200. Optional agent product name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `harnessDescriptor.agentVersion` — string; optional; minimum length 1; maximum length 100. Optional agent version declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `harnessDescriptor.model` — string; optional; minimum length 1; maximum length 200. Optional model name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `harnessDescriptor.modelProvider` — string; optional; minimum length 1; maximum length 100. Optional model provider declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"grantId": {
"type": "string",
"minLength": 1,
"description": "Execution-grant identifier returned when the human approval boundary is satisfied. Minimum accepted length or value is 1."
},
"reviewSessionId": {
"type": "string",
"minLength": 1,
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. Minimum accepted length or value is 1."
},
"supportedProtocolVersions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"minItems": 1,
"description": "Protocol versions the harness can execute, ordered by its preference. An empty array explicitly means no matching items."
},
"harnessDescriptor": {
"type": "object",
"properties": {
"harness": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Harness product name declared by the caller; Semel does not independently verify it. Accepted length or value is 1 through 200, inclusive."
},
"harnessVersion": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional harness version declared by the caller. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive."
},
"agent": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional agent product name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"agentVersion": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional agent version declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"modelProvider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Optional model provider declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"harness"
],
"additionalProperties": false,
"description": "Self-declared harness, agent, model, and supported-protocol metadata recorded on the execution claim for compatibility and audit."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"grantId",
"reviewSessionId",
"supportedProtocolVersions",
"harnessDescriptor",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"grantId": "xgr_fixture_engineering",
"reviewSessionId": "rs_fixture_engineering",
"supportedProtocolVersions": [
"1.1"
],
"harnessDescriptor": {
"harness": "codex",
"harnessVersion": "1",
"agent": "codex",
"model": "gpt-5"
},
"idempotencyKey": "recipe-execution-claim-v1"
}
```
**Binding template**
```json
{
"grantId": "{{grantId}}",
"reviewSessionId": "{{reviewSessionId}}",
"supportedProtocolVersions": [
"{{protocolVersion}}"
],
"harnessDescriptor": {
"harness": "codex",
"harnessVersion": "1",
"agent": "codex",
"model": "gpt-5"
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `value (anyOf branch 1)` — object; optional.
- `value (anyOf branch 1).bundle` — object; required. Frozen canonical execution bundle returned at claim time.
- `value (anyOf branch 1).bundle.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 1).bundle.instructions` — string; required. Pinned executable runbook instructions for this external execution.
- `value (anyOf branch 1).bundle.schemaHashes` — object; required. Map from frozen schema name to its SHA-256 identity.
- `value (anyOf branch 1).bundle.schemaHashes{key}` — string; optional.
- `value (anyOf branch 1).bundle.session` — object; required. Frozen review-session and run identity plus reviewer position for the claimed external execution.
- `value (anyOf branch 1).bundle.session.reviewSessionId` — string; required. Review-session identifier returned by review_start, review_new_pass, or execution status.
- `value (anyOf branch 1).bundle.session.runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `value (anyOf branch 1).bundle.session.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `value (anyOf branch 1).bundle.session.briefId` — string; required. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary.
- `value (anyOf branch 1).bundle.session.reviewMode` — string; required. Project review interaction mode configured in Semel.
- `value (anyOf branch 1).bundle.session.reviewerSet` — array; required. Ordered reviewer roles configured for this cascade. An empty array explicitly means no matching items.
- `value (anyOf branch 1).bundle.session.reviewerSet[]` — string; required.
- `value (anyOf branch 1).bundle.session.cascadeStepId` — string | null; required. Identifier of the configured reviewer-cascade step associated with this run. A null value explicitly means no current value is available.
- `value (anyOf branch 1).bundle.briefBase` — object; required. Frozen brief identity, version, and content snapshot against which this external execution must produce its result.
- `value (anyOf branch 1).bundle.briefBase.versionId` — string; required. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `value (anyOf branch 1).bundle.briefBase.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `value (anyOf branch 1).bundle.briefBase.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `value (anyOf branch 1).bundle.skills` — array; required. Ordered pinned reviewer-skill manifests required for this execution; fetch each artifact by its returned identifiers before use. An empty array explicitly means no matching items.
- `value (anyOf branch 1).bundle.skills[]` — object; required.
- `value (anyOf branch 1).bundle.skills[].role` — string; required; minimum length 1. Pinned reviewer or artifact role used by the execution bundle. Minimum accepted length or value is 1.
- `value (anyOf branch 1).bundle.skills[].version` — string; required; minimum length 1. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 1.
- `value (anyOf branch 1).bundle.skills[].sha256` — string; required; minimum length 1. Lowercase hexadecimal SHA-256 digest used to verify exact bytes. Minimum accepted length or value is 1.
- `value (anyOf branch 1).bundle.skills[].framingHash` — string; optional. SHA-256 identity of the shared framing artifact; null or omission means none is pinned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).bundle.evidencePolicy` — object; required. Frozen evidence policy map for this execution bundle; keys are versioned by the bundle contract.
- `value (anyOf branch 1).bundle.evidencePolicy{key}` — JSON value; optional.
- `value (anyOf branch 1).bundle.requiredCheckpoints` — array; required. Milestone names that must be checkpointed before final submission. An empty array explicitly means no matching items.
- `value (anyOf branch 1).bundle.requiredCheckpoints[]` — string; required.
- `value (anyOf branch 1).bundle.limits` — object; required. Server-issued byte, count, timeout, and polling limits that the external harness must obey for this execution.
- `value (anyOf branch 1).bundle.limits.checkpointMaxBytes` — integer; required. Maximum serialized checkpoint receipt size in bytes. The value must be an integer.
- `value (anyOf branch 1).bundle.limits.summaryMaxBytes` — integer; required. Maximum safe progress-summary size in UTF-8 bytes. The value must be an integer.
- `value (anyOf branch 1).bundle.limits.sessionEventBudgetBytes` — integer; required. Maximum total persisted external-event payload for one session, in bytes. The value must be an integer.
- `value (anyOf branch 1).bundle.limits.evidenceItemsPerCall` — integer; optional. Maximum local-evidence items accepted by one review_execution_evidence_register call. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 1).bundle.limits.evidenceItemsPerEpoch` — integer; optional. Maximum cumulative local-evidence items accepted for the current execution epoch. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 1).canonicalBundleSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the frozen canonical execution bundle.
- `value (anyOf branch 1).envelope` — object; required. Per-claim execution identity, fence, lease, and harness-attestation fields excluded from the bundle hash.
- `value (anyOf branch 1).envelope.executionId` — string; required. External-execution identifier returned by a successful execution claim or status lookup.
- `value (anyOf branch 1).envelope.fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. The value must be an integer.
- `value (anyOf branch 1).envelope.leaseExpiresAt` — string; required. RFC 3339 lease expiration timestamp; null means no active lease exists.
- `value (anyOf branch 1).envelope.heartbeatRecommendedSeconds` — integer; required. Recommended maximum interval between heartbeats, in seconds. The value must be an integer.
- `value (anyOf branch 1).envelope.harnessDescriptor` — object; required. Self-declared harness, agent, model, and supported-protocol metadata recorded on the execution claim for compatibility and audit.
- `value (anyOf branch 1).envelope.harnessDescriptor.harness` — string; required; minimum length 1; maximum length 200. Harness product name declared by the caller; Semel does not independently verify it. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 1).envelope.harnessDescriptor.harnessVersion` — string; optional; minimum length 1; maximum length 100. Optional harness version declared by the caller. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `value (anyOf branch 1).envelope.harnessDescriptor.agent` — string; optional; minimum length 1; maximum length 200. Optional agent product name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 1).envelope.harnessDescriptor.agentVersion` — string; optional; minimum length 1; maximum length 100. Optional agent version declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `value (anyOf branch 1).envelope.harnessDescriptor.model` — string; optional; minimum length 1; maximum length 200. Optional model name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 1).envelope.harnessDescriptor.modelProvider` — string; optional; minimum length 1; maximum length 100. Optional model provider declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `value (anyOf branch 1).activeSkill` — JSON value; required. Currently active pinned skill role and cursor; null means activation has not begun. A null value explicitly means no current value is available.
- `value (anyOf branch 1).activeSkill (anyOf branch 1)` — object; required.
- `value (anyOf branch 1).activeSkill (anyOf branch 1).role` — string; required. Pinned reviewer or artifact role used by the execution bundle.
- `value (anyOf branch 1).activeSkill (anyOf branch 1).cursor` — string; required. Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning.
- `value (anyOf branch 1).activeSkill (anyOf branch 2)` — null; required.
- `value (anyOf branch 1).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 1).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 1).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 1).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 1).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 1).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 1).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 1).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 1).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 1).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 1).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 1).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 1).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 1).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 1).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 1).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 1).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 1).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 1).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 1).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 1).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 1).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
- `value (anyOf branch 2)` — object; optional.
- `value (anyOf branch 2).bundle` — object; required. Frozen canonical execution bundle returned at claim time.
- `value (anyOf branch 2).bundle.protocolVersion` — constant "1.2"; required. Semel external-execution protocol version used for this bundle or state. This branch always uses "1.2".
- `value (anyOf branch 2).bundle.resultIdentitySchemaVersion` — constant 2; required. Version of the reviewer identity schema required for this execution result. This branch always uses 2.
- `value (anyOf branch 2).bundle.instructions` — string; required. Pinned executable runbook instructions for this external execution.
- `value (anyOf branch 2).bundle.schemaHashes` — object; required. Map from frozen schema name to its SHA-256 identity.
- `value (anyOf branch 2).bundle.schemaHashes{key}` — string; optional.
- `value (anyOf branch 2).bundle.session` — object; required. Frozen review-session and run identity plus reviewer position for the claimed external execution.
- `value (anyOf branch 2).bundle.session.reviewSessionId` — string; required. Review-session identifier returned by review_start, review_new_pass, or execution status.
- `value (anyOf branch 2).bundle.session.runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `value (anyOf branch 2).bundle.session.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `value (anyOf branch 2).bundle.session.briefId` — string; required. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary.
- `value (anyOf branch 2).bundle.session.reviewMode` — string; required. Project review interaction mode configured in Semel.
- `value (anyOf branch 2).bundle.session.cascadeExecutionSnapshotId` — string; required; minimum length 1. Identifier of the immutable cascade snapshot shared by every reviewer session in this pass. Minimum accepted length or value is 1.
- `value (anyOf branch 2).bundle.session.activeReviewerOccurrenceId` — string; required; minimum length 1; maximum length 200. Enabled reviewer occurrence assigned to this individual review session or execution.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences` — array; required; minimum items 1; maximum items 20. Complete ordered reviewer occurrence list preserved in the immutable cascade execution snapshot. An empty array explicitly means no matching items.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[]` — object; required.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].position` — integer; required; minimum 0. Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity` — object; required. Frozen reviewer occurrence identity used for display and exact historical attribution.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.reviewerRef (anyOf branch 1)` — object; required.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.reviewerRef (anyOf branch 2)` — object; required.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.legacyRole` — JSON value; required. Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: "product", "engineering", "design", "security", "test".
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.legacyRole (anyOf branch 1)` — "product" | "engineering" | "design" | "security" | "test"; required.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].identity.legacyRole (anyOf branch 2)` — null; required.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin` — object; required. Exact skill, framing, capability, and model pins for this reviewer occurrence.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.framing` — object; required. Exact shared reviewer framing artifact pin used for this occurrence.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.framing.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.framing.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.capabilities` — array; required; maximum items 32. Ordered exact capability artifact pins available to this reviewer occurrence. An empty array explicitly means no matching items.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.capabilities[]` — object; required.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.capabilities[].id` — string; required; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.capabilities[].version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.capabilities[].sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.model` — object; required. Optional model name declared by the harness.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `value (anyOf branch 2).bundle.session.reviewerOccurrences[].pin.model.reasoning (anyOf branch 2)` — null; required.
- `value (anyOf branch 2).bundle.session.configuration` — object; required. Immutable cascade configuration revision and source captured when the execution snapshot was admitted.
- `value (anyOf branch 2).bundle.session.configuration.revision` — string; required; minimum length 1; maximum length 20. Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive.
- `value (anyOf branch 2).bundle.session.configuration.origin` — object; required. Immutable source from which this cascade configuration was adopted; it never consults a current default.
- `value (anyOf branch 2).bundle.session.configuration.origin.kind` — "project" | "personal_default" | "team_default" | "builtin_fallback" | "explicit_override"; required. Discriminator identifying the typed variant represented by this object. Allowed values: "project", "personal_default", "team_default", "builtin_fallback", "explicit_override".
- `value (anyOf branch 2).bundle.session.configuration.origin.presetVersionId` — JSON value; required. Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 2).bundle.session.configuration.origin.presetVersionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 200.
- `value (anyOf branch 2).bundle.session.configuration.origin.presetVersionId (anyOf branch 2)` — null; required.
- `value (anyOf branch 2).bundle.session.cascadeStepId` — string | null; required. Identifier of the configured reviewer-cascade step associated with this run. A null value explicitly means no current value is available.
- `value (anyOf branch 2).bundle.briefBase` — object; required. Frozen brief identity, version, and content snapshot against which this external execution must produce its result.
- `value (anyOf branch 2).bundle.briefBase.versionId` — string; required. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `value (anyOf branch 2).bundle.briefBase.versionNum` — integer; required. Monotonic brief contract version number assigned by Semel. The value must be an integer.
- `value (anyOf branch 2).bundle.briefBase.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `value (anyOf branch 2).bundle.skills` — array; required. Ordered pinned reviewer-skill manifests required for this execution; fetch each artifact by its returned identifiers before use. An empty array explicitly means no matching items.
- `value (anyOf branch 2).bundle.skills[]` — object; required.
- `value (anyOf branch 2).bundle.skills[].role` — string; required; minimum length 1. Pinned reviewer or artifact role used by the execution bundle. Minimum accepted length or value is 1.
- `value (anyOf branch 2).bundle.skills[].version` — string; required; minimum length 1. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 1.
- `value (anyOf branch 2).bundle.skills[].sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `value (anyOf branch 2).bundle.skills[].framingHash` — string; optional. SHA-256 identity of the shared framing artifact; null or omission means none is pinned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).bundle.skills[].occurrenceId` — JSON value; required. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values. A null value explicitly means no current value is available.
- `value (anyOf branch 2).bundle.skills[].occurrenceId (anyOf branch 1)` — string; required; minimum length 1; maximum length 200.
- `value (anyOf branch 2).bundle.skills[].occurrenceId (anyOf branch 2)` — null; required.
- `value (anyOf branch 2).bundle.evidencePolicy` — object; required. Frozen evidence policy map for this execution bundle; keys are versioned by the bundle contract.
- `value (anyOf branch 2).bundle.evidencePolicy{key}` — JSON value; optional.
- `value (anyOf branch 2).bundle.requiredCheckpoints` — array; required. Milestone names that must be checkpointed before final submission. An empty array explicitly means no matching items.
- `value (anyOf branch 2).bundle.requiredCheckpoints[]` — string; required.
- `value (anyOf branch 2).bundle.limits` — object; required. Server-issued byte, count, timeout, and polling limits that the external harness must obey for this execution.
- `value (anyOf branch 2).bundle.limits.checkpointMaxBytes` — integer; required. Maximum serialized checkpoint receipt size in bytes. The value must be an integer.
- `value (anyOf branch 2).bundle.limits.summaryMaxBytes` — integer; required. Maximum safe progress-summary size in UTF-8 bytes. The value must be an integer.
- `value (anyOf branch 2).bundle.limits.sessionEventBudgetBytes` — integer; required. Maximum total persisted external-event payload for one session, in bytes. The value must be an integer.
- `value (anyOf branch 2).bundle.limits.evidenceItemsPerCall` — integer; optional. Maximum local-evidence items accepted by one review_execution_evidence_register call. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 2).bundle.limits.evidenceItemsPerEpoch` — integer; optional. Maximum cumulative local-evidence items accepted for the current execution epoch. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 2).canonicalBundleSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the frozen canonical execution bundle.
- `value (anyOf branch 2).envelope` — object; required. Per-claim execution identity, fence, lease, and harness-attestation fields excluded from the bundle hash.
- `value (anyOf branch 2).envelope.executionId` — string; required. External-execution identifier returned by a successful execution claim or status lookup.
- `value (anyOf branch 2).envelope.fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. The value must be an integer.
- `value (anyOf branch 2).envelope.leaseExpiresAt` — string; required. RFC 3339 lease expiration timestamp; null means no active lease exists.
- `value (anyOf branch 2).envelope.heartbeatRecommendedSeconds` — integer; required. Recommended maximum interval between heartbeats, in seconds. The value must be an integer.
- `value (anyOf branch 2).envelope.harnessDescriptor` — object; required. Self-declared harness, agent, model, and supported-protocol metadata recorded on the execution claim for compatibility and audit.
- `value (anyOf branch 2).envelope.harnessDescriptor.harness` — string; required; minimum length 1; maximum length 200. Harness product name declared by the caller; Semel does not independently verify it. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 2).envelope.harnessDescriptor.harnessVersion` — string; optional; minimum length 1; maximum length 100. Optional harness version declared by the caller. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `value (anyOf branch 2).envelope.harnessDescriptor.agent` — string; optional; minimum length 1; maximum length 200. Optional agent product name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 2).envelope.harnessDescriptor.agentVersion` — string; optional; minimum length 1; maximum length 100. Optional agent version declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `value (anyOf branch 2).envelope.harnessDescriptor.model` — string; optional; minimum length 1; maximum length 200. Optional model name declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `value (anyOf branch 2).envelope.harnessDescriptor.modelProvider` — string; optional; minimum length 1; maximum length 100. Optional model provider declared by the harness. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 100, inclusive.
- `value (anyOf branch 2).activeSkill` — JSON value; required. Currently active pinned skill role and cursor; null means activation has not begun. A null value explicitly means no current value is available.
- `value (anyOf branch 2).activeSkill (anyOf branch 1)` — object; required.
- `value (anyOf branch 2).activeSkill (anyOf branch 1).occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `value (anyOf branch 2).activeSkill (anyOf branch 1).cursor` — string; required; minimum length 1; maximum length 200. Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning.
- `value (anyOf branch 2).activeSkill (anyOf branch 2)` — null; required.
- `value (anyOf branch 2).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 2).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 2).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 2).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 2).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 2).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 2).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 2).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 2).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 2).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 2).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 2).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 2).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 2).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 2).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 2).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 2).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 2).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 2).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 2).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 2).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 2).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 2).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 2).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"anyOf": [
{
"type": "object",
"properties": {
"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 version identifier returned by the owning brief, reviewer skill, 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."
},
"evidenceItemsPerCall": {
"type": "integer",
"description": "Maximum local-evidence items accepted by one review_execution_evidence_register call. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"evidenceItemsPerEpoch": {
"type": "integer",
"description": "Maximum cumulative local-evidence items accepted for the current execution epoch. Omit the field when it does not apply; omission is distinct from an empty value. 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
},
{
"type": "object",
"properties": {
"bundle": {
"type": "object",
"properties": {
"protocolVersion": {
"type": "string",
"const": "1.2",
"description": "Semel external-execution protocol version used for this bundle or state. This branch always uses \"1.2\"."
},
"resultIdentitySchemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the reviewer identity schema required for this execution result. This branch always uses 2."
},
"instructions": {
"type": "string",
"description": "Pinned executable runbook instructions for this external execution."
},
"schemaHashes": {
"type": "object",
"additionalProperties": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"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."
},
"cascadeExecutionSnapshotId": {
"type": "string",
"minLength": 1,
"description": "Identifier of the immutable cascade snapshot shared by every reviewer session in this pass. Minimum accepted length or value is 1."
},
"activeReviewerOccurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Enabled reviewer occurrence assigned to this individual review session or execution."
},
"reviewerOccurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"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."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"identity": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"legacyRole": {
"anyOf": [
{
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
]
},
{
"type": "null"
}
],
"description": "Closed built-in reviewer-role projection; custom reviewer identities always carry null. A null value explicitly means no current value is available. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"legacyRole"
],
"additionalProperties": false,
"description": "Frozen reviewer occurrence identity used for display and exact historical attribution."
},
"pin": {
"type": "object",
"properties": {
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"framing": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact shared reviewer framing artifact pin used for this occurrence."
},
"capabilities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"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."
},
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"id",
"version",
"sha256"
],
"additionalProperties": false
},
"maxItems": 32,
"description": "Ordered exact capability artifact pins available to this reviewer occurrence. An empty array explicitly means no matching items."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"skill",
"framing",
"capabilities",
"model"
],
"additionalProperties": false,
"description": "Exact skill, framing, capability, and model pins for this reviewer occurrence."
}
},
"required": [
"position",
"enabled",
"identity",
"pin"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Complete ordered reviewer occurrence list preserved in the immutable cascade execution snapshot. An empty array explicitly means no matching items."
},
"configuration": {
"type": "object",
"properties": {
"revision": {
"type": "string",
"minLength": 1,
"maxLength": 20,
"pattern": "^(?:0|[1-9][0-9]*)$",
"description": "Indexed repository revision used for this evidence result. Accepted length or value is 1 through 20, inclusive."
},
"origin": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"project",
"personal_default",
"team_default",
"builtin_fallback",
"explicit_override"
],
"description": "Discriminator identifying the typed variant represented by this object. Allowed values: \"project\", \"personal_default\", \"team_default\", \"builtin_fallback\", \"explicit_override\"."
},
"presetVersionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Immutable preset-version source when configuration was adopted from or explicitly based on a preset. A null value explicitly means no current value is available. Accepted length or value is 1 through 200, inclusive."
}
},
"required": [
"kind",
"presetVersionId"
],
"additionalProperties": false,
"description": "Immutable source from which this cascade configuration was adopted; it never consults a current default."
}
},
"required": [
"revision",
"origin"
],
"additionalProperties": false,
"description": "Immutable cascade configuration revision and source captured when the execution snapshot was admitted."
},
"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",
"cascadeExecutionSnapshotId",
"activeReviewerOccurrenceId",
"reviewerOccurrences",
"configuration",
"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 version identifier returned by the owning brief, reviewer skill, 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",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
},
"framingHash": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"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."
},
"occurrenceId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 200
},
{
"type": "null"
}
],
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values. A null value explicitly means no current value is available."
}
},
"required": [
"role",
"version",
"sha256",
"occurrenceId"
],
"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."
},
"evidenceItemsPerCall": {
"type": "integer",
"description": "Maximum local-evidence items accepted by one review_execution_evidence_register call. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"evidenceItemsPerEpoch": {
"type": "integer",
"description": "Maximum cumulative local-evidence items accepted for the current execution epoch. Omit the field when it does not apply; omission is distinct from an empty value. 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",
"resultIdentitySchemaVersion",
"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": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"cursor": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning."
}
},
"required": [
"occurrenceId",
"cursor"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Currently active pinned skill role and cursor; null means activation has not begun. A null value explicitly means no current value is available."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"bundle",
"canonicalBundleSha256",
"envelope",
"activeSkill",
"controlBlock"
],
"additionalProperties": false
}
]
}
```
**Example structured result (claimed)**
```json
{
"bundle": {
"protocolVersion": "1.1",
"instructions": "Semel external-execution protocol v1: after review_execution_claim pins this bundle, the active skill is exactly one at a time (see the frozen skill order). Fetch the active reviewer lens and its matching shared framing with review_execution_skill_get. Use review_execution_checkpoint_append for bounded semantic milestones, review_question_open/review_question_answer for durable questions, review_execution_sync to discover recorded answers/cancellation/handoff without a persistent session, review_execution_heartbeat to renew the current fenced epoch, and review_execution_submit to finalize against this exact pinned brief base. review_execution_status is always callable and is the documented fail-safe whenever local context is lost. Raw chain-of-thought, source dumps, and hidden reasoning are never accepted fields.",
"schemaHashes": {
"review_execution_grant_request": "e52e7b64d1f1249e1e92c230fe31d7ac8aa504b9e00b154669269ee819d0ce08",
"review_execution_claim": "a124f54e50215258b0b669806e5278f5fcf4a9a1dd9c5501f2cff7ac99345ed7",
"review_execution_skill_get": "fbc91868b45920f159c6e65eccc70fe8d2a5bd107dbece3cceb4f8bf7edaf12c",
"review_execution_checkpoint_append": "023d0a5c99799ffd1734b9ff5c37da0391ab3a80beba895522ee824a171058ad",
"review_question_open": "2304a9fc9feed0e54f96202864f313485028d63f11d9c5bea41bbd8af6ceac2b",
"review_question_answer": "cd82c71b9090d96c9b972b89d22baac83167073503cf06d0efd0eada62e2ba8b",
"review_question_answer_supersede": "8ca9bcface0a212deb4c6595d162fffb06089c278177234ea995228e85277904",
"review_execution_sync": "e3228cdf437c31d501474f2d688e25968a40bce0f1a620000cb8bb0840003907",
"review_execution_wait": "e20acce29a5f9a5a03a0b351866e4df2129e888cabb08777c04ebce1474415a4",
"review_execution_heartbeat": "b9ed5d743c1a9f668eb4ba3a4cc57552fc625fe115175906b4999fb3afbab4f3",
"review_execution_release": "c22b0fc25aa734487b075da1d665b75c9b645dbfbaca7b673863d942fbb58fe5",
"review_execution_submit": "80e9035b5dd37421bbdb6535042b7c2501bdcfd17e42070beb7a83ff1af3235f",
"review_execution_status": "1b27dee7128f1cec0c9c3bab65ea2368b58427a60728a156a0260e84f0c5edc4",
"review_execution_evidence_register": "59caa97b76723e1755e8684647513e014719d39f03ec44b8ec2e04b1f5f6f309",
"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,
"evidenceItemsPerCall": 200,
"evidenceItemsPerEpoch": 10000
}
},
"canonicalBundleSha256": "fe4c3e639e846e481ebd4512b4c0a04d4ad1b3c80a6a132212ea632f0a1656e8",
"envelope": {
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"heartbeatRecommendedSeconds": 30,
"harnessDescriptor": {
"harness": "codex",
"harnessVersion": "1",
"agent": "codex",
"model": "gpt-5"
}
},
"activeSkill": {
"role": "engineering",
"cursor": "sync_fixture_next"
},
"controlBlock": {
"state": {
"sessionState": "claimed",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Bindings: executionId from structuredContent.envelope.executionId; canonicalBundleSha256 from structuredContent.canonicalBundleSha256.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"bundle\":{\"protocolVersion\":\"1.1\",\"instructions\":\"Semel external-execution protocol v1: after review_execution_claim pins this bundle, the active skill is exactly one at a time (see the frozen skill order). Fetch the active reviewer lens and its matching shared framing with review_execution_skill_get. Use review_execution_checkpoint_append for bounded semantic milestones, review_question_open/review_question_answer for durable questions, review_execution_sync to discover recorded answers/cancellation/handoff without a persistent session, review_execution_heartbeat to renew the current fenced epoch, and review_execution_submit to finalize against this exact pinned brief base. review_execution_status is always callable and is the documented fail-safe whenever local context is lost. Raw chain-of-thought, source dumps, and hidden reasoning are never accepted fields.\",\"schemaHashes\":{\"review_execution_grant_request\":\"e52e7b64d1f1249e1e92c230fe31d7ac8aa504b9e00b154669269ee819d0ce08\",\"review_execution_claim\":\"a124f54e50215258b0b669806e5278f5fcf4a9a1dd9c5501f2cff7ac99345ed7\",\"review_execution_skill_get\":\"fbc91868b45920f159c6e65eccc70fe8d2a5bd107dbece3cceb4f8bf7edaf12c\",\"review_execution_checkpoint_append\":\"023d0a5c99799ffd1734b9ff5c37da0391ab3a80beba895522ee824a171058ad\",\"review_question_open\":\"2304a9fc9feed0e54f96202864f313485028d63f11d9c5bea41bbd8af6ceac2b\",\"review_question_answer\":\"cd82c71b9090d96c9b972b89d22baac83167073503cf06d0efd0eada62e2ba8b\",\"review_question_answer_supersede\":\"8ca9bcface0a212deb4c6595d162fffb06089c278177234ea995228e85277904\",\"review_execution_sync\":\"e3228cdf437c31d501474f2d688e25968a40bce0f1a620000cb8bb0840003907\",\"review_execution_wait\":\"e20acce29a5f9a5a03a0b351866e4df2129e888cabb08777c04ebce1474415a4\",\"review_execution_heartbeat\":\"b9ed5d743c1a9f668eb4ba3a4cc57552fc625fe115175906b4999fb3afbab4f3\",\"review_execution_release\":\"c22b0fc25aa734487b075da1d665b75c9b645dbfbaca7b673863d942fbb58fe5\",\"review_execution_submit\":\"80e9035b5dd37421bbdb6535042b7c2501bdcfd17e42070beb7a83ff1af3235f\",\"review_execution_status\":\"1b27dee7128f1cec0c9c3bab65ea2368b58427a60728a156a0260e84f0c5edc4\",\"review_execution_evidence_register\":\"59caa97b76723e1755e8684647513e014719d39f03ec44b8ec2e04b1f5f6f309\",\"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,\"evidenceItemsPerCall\":200,\"evidenceItemsPerEpoch\":10000}},\"canonicalBundleSha256\":\"fe4c3e639e846e481ebd4512b4c0a04d4ad1b3c80a6a132212ea632f0a1656e8\",\"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_wait": "e20acce29a5f9a5a03a0b351866e4df2129e888cabb08777c04ebce1474415a4",
"review_execution_heartbeat": "b9ed5d743c1a9f668eb4ba3a4cc57552fc625fe115175906b4999fb3afbab4f3",
"review_execution_release": "c22b0fc25aa734487b075da1d665b75c9b645dbfbaca7b673863d942fbb58fe5",
"review_execution_submit": "80e9035b5dd37421bbdb6535042b7c2501bdcfd17e42070beb7a83ff1af3235f",
"review_execution_status": "1b27dee7128f1cec0c9c3bab65ea2368b58427a60728a156a0260e84f0c5edc4",
"review_execution_evidence_register": "59caa97b76723e1755e8684647513e014719d39f03ec44b8ec2e04b1f5f6f309",
"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,
"evidenceItemsPerCall": 200,
"evidenceItemsPerEpoch": 10000
}
},
"canonicalBundleSha256": "fe4c3e639e846e481ebd4512b4c0a04d4ad1b3c80a6a132212ea632f0a1656e8",
"envelope": {
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"heartbeatRecommendedSeconds": 30,
"harnessDescriptor": {
"harness": "codex",
"harnessVersion": "1",
"agent": "codex",
"model": "gpt-5"
}
},
"activeSkill": {
"role": "engineering",
"cursor": "sync_fixture_next"
},
"controlBlock": {
"state": {
"sessionState": "claimed",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"Awaiting the first checkpoint, which advances the epoch into running."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Next permitted action: Persist executionId, fenceGeneration, bundle hash, lease guidance, and activeSkill from structuredContent.
**Example requests**
- “/semel continue the session I paused”
Errors: `GRANT_EXPIRED`, `PROTOCOL_VERSION_UNSUPPORTED`, `CAPABILITY_UNSUPPORTED`, `STALE_FENCE`, `CANCELLED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_grant_request`, `review_execution_status`.
---
### review_execution_evidence_register
Register bounded worktree excerpts from a currently-bound local repository as durable, citable lev_ evidence handles. Call this after an evidence_readiness_change binding checkpoint and before citing repository-code facts in a local submission.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `items` — array; required; minimum items 1; maximum items 200. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `items[]` — object; required.
- `items[].repositoryId` — string; required; minimum length 1. Repository identifier from the connected-codebase inventory. Minimum accepted length or value is 1.
- `items[].headSha` — string; required. Git commit SHA of the local worktree HEAD at binding or citation time.
- `items[].fileSha` — JSON value; optional. Git blob SHA of the local working file computed with git hash-object; null when unavailable. 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.
- `items[].fileSha (anyOf branch 1)` — string; optional.
- `items[].fileSha (anyOf branch 2)` — null; optional.
- `items[].path` — string; required; minimum length 1; maximum length 4096. Repository-relative source path; it never denotes an arbitrary local filesystem path. Accepted length or value is 1 through 4096, inclusive.
- `items[].startLine` — integer; required. One-based inclusive start line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `items[].endLine` — integer; required. One-based inclusive end line of the cited repository excerpt. Minimum accepted length or value is 0. The value must be an integer.
- `items[].verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"items": {
"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."
},
"headSha": {
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$",
"description": "Git commit SHA of the local worktree HEAD at binding or citation time."
},
"fileSha": {
"anyOf": [
{
"type": "string",
"pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$"
},
{
"type": "null"
}
],
"description": "Git blob SHA of the local working file computed with git hash-object; null when unavailable. 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."
},
"path": {
"type": "string",
"minLength": 1,
"maxLength": 4096,
"description": "Repository-relative source path; it never denotes an arbitrary local filesystem path. Accepted length or value is 1 through 4096, inclusive."
},
"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."
},
"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": [
"repositoryId",
"headSha",
"path",
"startLine",
"endLine",
"verbatim"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 200,
"description": "Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"items",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"items": [
{
"repositoryId": "repo_fixture_throughline",
"headSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"path": "services/api/src/checkout.ts",
"startLine": 42,
"endLine": 58,
"verbatim": "The checkout handler reuses the payment intent for a repeated idempotency key."
}
],
"idempotencyKey": "recipe-execution-evidence-register-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"items": [
{
"repositoryId": "repo_fixture_throughline",
"headSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"path": "services/api/src/checkout.ts",
"startLine": 42,
"endLine": 58,
"verbatim": "The checkout handler reuses the payment intent for a repeated idempotency key."
}
],
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `items` — array; required. Records in this page or grouped result; an empty array means there are none. An empty array explicitly means no matching items.
- `items[]` — object; required.
- `items[].citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `items[].verification` — constant "unverified"; required. Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. This branch always uses "unverified".
- `items[].provenance` — constant "local-worktree"; required. Immutable repository revision and evidence-source provenance. This branch always uses "local-worktree".
- `items[].verbatim` — string; required; maximum length 1200. Exact bounded evidence text supporting the citation. Maximum accepted length or value is 1200.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"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."
},
"verification": {
"type": "string",
"const": "unverified",
"description": "Citation verification result: exact and canonical are publishable evidence matches, while unverified cannot support a durable code claim. This branch always uses \"unverified\"."
},
"provenance": {
"type": "string",
"const": "local-worktree",
"description": "Immutable repository revision and evidence-source provenance. This branch always uses \"local-worktree\"."
},
"verbatim": {
"type": "string",
"maxLength": 1200,
"description": "Exact bounded evidence text supporting the citation. Maximum accepted length or value is 1200."
}
},
"required": [
"citationKey",
"verification",
"provenance",
"verbatim"
],
"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."
},
"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": [
"items",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (evidence-registered)**
```json
{
"items": [
{
"citationKey": "lev_fixture_checkout_excerpt",
"verification": "unverified",
"provenance": "local-worktree",
"verbatim": "The checkout handler reuses the payment intent for a repeated idempotency key."
}
],
"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."
]
},
{
"operation": "review_execution_evidence_register",
"preconditions": [
"A local-worktree binding receipt was recorded for this repository this epoch."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 2,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Bindings: evidenceCitationKey from structuredContent.items[0].citationKey.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"items\":[{\"citationKey\":\"lev_fixture_checkout_excerpt\",\"verification\":\"unverified\",\"provenance\":\"local-worktree\",\"verbatim\":\"The checkout handler reuses the payment intent for a repeated idempotency key.\"}],\"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.\"]},{\"operation\":\"review_execution_evidence_register\",\"preconditions\":[\"A local-worktree binding receipt was recorded for this repository this epoch.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":2,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}}}"
}
],
"structuredContent": {
"items": [
{
"citationKey": "lev_fixture_checkout_excerpt",
"verification": "unverified",
"provenance": "local-worktree",
"verbatim": "The checkout handler reuses the payment intent for a repeated idempotency key."
}
],
"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."
]
},
{
"operation": "review_execution_evidence_register",
"preconditions": [
"A local-worktree binding receipt was recorded for this repository this epoch."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 2,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Next permitted action: Cite the returned lev_ keys as repository-code anchors in submit.
**Example requests**
- “/semel register this worktree excerpt as evidence for my finding”
Errors: `STALE_FENCE`, `VALIDATION_FAILED`, `EVIDENCE_BINDING_MISSING`, `EVIDENCE_BINDING_STALE`, `EVIDENCE_BUDGET_EXCEEDED`, `PAYLOAD_REJECTED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_checkpoint_append`, `review_execution_submit`, `review_execution_status`.
---
### review_execution_grant_request
Discover or request the operator-issued execution grant that authorizes this harness to claim a review session.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: operator_grant
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `reviewSessionId` — string; required; minimum length 1. Review-session identifier returned by review_start, review_new_pass, or execution status. Minimum accepted length or value is 1.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"reviewSessionId": {
"type": "string",
"minLength": 1,
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. Minimum accepted length or value is 1."
}
},
"required": [
"reviewSessionId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"reviewSessionId": "rs_fixture_engineering"
}
```
**Binding template**
```json
{
"reviewSessionId": "{{reviewSessionId}}"
}
```
**Returns**
- `value (anyOf branch 1)` — object; optional.
- `value (anyOf branch 1).status` — constant "ready"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "ready".
- `value (anyOf branch 1).grant` — object; required. Current human-approved execution grant summary.
- `value (anyOf branch 1).grant.grantId` — string; required. Execution-grant identifier returned when the human approval boundary is satisfied.
- `value (anyOf branch 1).grant.state` — string; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 1).grant.intent` — string; required. Human-approved execution intent bound to the grant.
- `value (anyOf branch 1).grant.expiresAt` — string; required. RFC 3339 expiration timestamp.
- `value (anyOf branch 1).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 1).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 1).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 1).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 1).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 1).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 1).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 1).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 1).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 1).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 1).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 1).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 1).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 1).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 1).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 1).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 1).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 1).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 1).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 1).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 1).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 1).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
- `value (anyOf branch 2)` — object; optional.
- `value (anyOf branch 2).status` — constant "approval_required"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "approval_required".
- `value (anyOf branch 2).approvalUri` — string; required. Semel URI where a human can inspect and approve the execution grant.
- `value (anyOf branch 2).pollHandle` — string; required. Opaque handle used to poll while human grant approval is pending.
- `value (anyOf branch 2).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 2).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 2).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 2).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 2).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 2).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 2).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 2).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 2).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 2).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 2).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 2).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 2).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 2).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 2).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 2).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 2).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 2).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 2).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 2).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 2).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 2).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 2).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 2).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "ready",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"ready\"."
},
"grant": {
"type": "object",
"properties": {
"grantId": {
"type": "string",
"description": "Execution-grant identifier returned when the human approval boundary is satisfied."
},
"state": {
"type": "string",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"intent": {
"type": "string",
"description": "Human-approved execution intent bound to the grant."
},
"expiresAt": {
"type": "string",
"description": "RFC 3339 expiration timestamp."
}
},
"required": [
"grantId",
"state",
"intent",
"expiresAt"
],
"additionalProperties": false,
"description": "Current human-approved execution grant summary."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"grant",
"controlBlock"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "approval_required",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"approval_required\"."
},
"approvalUri": {
"type": "string",
"description": "Semel URI where a human can inspect and approve the execution grant."
},
"pollHandle": {
"type": "string",
"description": "Opaque handle used to poll while human grant approval is pending."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"approvalUri",
"pollHandle",
"controlBlock"
],
"additionalProperties": false
}
]
}
```
**Example structured result (approval-required)**
```json
{
"status": "approval_required",
"approvalUri": "https://mcp.semel.ai/review-execution/approve/xgr_fixture_engineering",
"pollHandle": "poll_fixture_engineering",
"controlBlock": {
"state": {
"sessionState": "awaiting_executor",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_claim",
"preconditions": [
"An operator-issued grant already exists; any authorized claimant may claim it."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": true,
"uri": "https://mcp.semel.ai/review-execution/approve/xgr_fixture_engineering"
}
}
}
```
Bindings: approvalUri from structuredContent.approvalUri.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"status\":\"approval_required\",\"approvalUri\":\"https://mcp.semel.ai/review-execution/approve/xgr_fixture_engineering\",\"pollHandle\":\"poll_fixture_engineering\",\"controlBlock\":{\"state\":{\"sessionState\":\"awaiting_executor\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_claim\",\"preconditions\":[\"An operator-issued grant already exists; any authorized claimant may claim it.\"]},{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":0,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":true,\"uri\":\"https://mcp.semel.ai/review-execution/approve/xgr_fixture_engineering\"}}}"
}
],
"structuredContent": {
"status": "approval_required",
"approvalUri": "https://mcp.semel.ai/review-execution/approve/xgr_fixture_engineering",
"pollHandle": "poll_fixture_engineering",
"controlBlock": {
"state": {
"sessionState": "awaiting_executor",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_claim",
"preconditions": [
"An operator-issued grant already exists; any authorized claimant may claim it."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": true,
"uri": "https://mcp.semel.ai/review-execution/approve/xgr_fixture_engineering"
}
}
}
}
```
Next permitted action: Show approvalUri to the human and poll only as instructed.
**Example requests**
- “/semel run the checkout brief review locally”
Errors: `GRANT_REQUIRED`, `GRANT_EXPIRED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_claim`, `review_execution_status`.
---
### review_execution_heartbeat
Renew the current fenced epoch lease.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"idempotencyKey": "recipe-execution-heartbeat-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `leaseExpiresAt` — string; required. RFC 3339 lease expiration timestamp; null means no active lease exists.
- `heartbeatRecommendedSeconds` — integer; required. Recommended maximum interval between heartbeats, in seconds. The value must be an integer.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"leaseExpiresAt": {
"type": "string",
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists."
},
"heartbeatRecommendedSeconds": {
"type": "integer",
"description": "Recommended maximum interval between heartbeats, in seconds. The value must be an integer."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"leaseExpiresAt",
"heartbeatRecommendedSeconds",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (lease-renewed)**
```json
{
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"heartbeatRecommendedSeconds": 30,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Bindings: leaseExpiresAt from structuredContent.leaseExpiresAt.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"heartbeatRecommendedSeconds\":30,\"controlBlock\":{\"state\":{\"sessionState\":\"running\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_skill_get\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_checkpoint_append\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_heartbeat\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_question_open\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_submit\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_release\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_sync\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":5,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}}}"
}
],
"structuredContent": {
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"heartbeatRecommendedSeconds": 30,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Next permitted action: Schedule the next heartbeat from heartbeatRecommendedSeconds.
**Example requests**
- “keep my claim alive while the reviewer skill works”
Errors: `STALE_FENCE`, `LEASE_EXPIRED`, `CANCELLED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_sync`, `review_execution_release`.
---
### review_execution_release
Yield the current fenced epoch for handoff or operator stop.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `reason` — "handoff" | "stop"; required. Typed or human-readable reason for the current outcome; omission means no reason is required. Allowed values: "handoff", "stop".
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"reason": {
"type": "string",
"enum": [
"handoff",
"stop"
],
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Allowed values: \"handoff\", \"stop\"."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"reason",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"reason": "handoff",
"idempotencyKey": "recipe-execution-release-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"reason": "handoff",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `released` — constant true; required. Confirms that the execution lease was released. This branch always uses true.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"released": {
"type": "boolean",
"const": true,
"description": "Confirms that the execution lease was released. This branch always uses true."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"released",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (released)**
```json
{
"released": true,
"controlBlock": {
"state": {
"sessionState": "handed_off",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_claim",
"preconditions": [
"Explicitly released for handoff — claimable by the next authorized harness."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Bindings: released from structuredContent.released.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"released\":true,\"controlBlock\":{\"state\":{\"sessionState\":\"handed_off\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_claim\",\"preconditions\":[\"Explicitly released for handoff — claimable by the next authorized harness.\"]},{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":5,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}}}"
}
],
"structuredContent": {
"released": true,
"controlBlock": {
"state": {
"sessionState": "handed_off",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_claim",
"preconditions": [
"Explicitly released for handoff — claimable by the next authorized harness."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Next permitted action: Stop; the next harness must claim a fresh epoch and repeat local evidence confirmation.
**Example requests**
- “hand this session off to Codex”
Errors: `STALE_FENCE`, `CANCELLED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_claim`, `review_execution_status`.
---
### review_execution_skill_get
Load the byte-exact active reviewer rubric (its shared framing, and the shared local-execution QA addendum when pinned) from an execution's frozen content-addressed pins without exposing upcoming reviewer skills.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `role` — string; required; minimum length 1; maximum length 200. Pinned reviewer or artifact role used by the execution bundle. Accepted length or value is 1 through 200, inclusive.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"role": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Pinned reviewer or artifact role used by the execution bundle. Accepted length or value is 1 through 200, inclusive."
}
},
"required": [
"executionId",
"role"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"role": "engineering"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"role": "engineering"
}
```
**Returns**
- `artifact` — object; required. Exact content-addressed skill artifact selected from the frozen execution bundle.
- `artifact.role` — string; required; minimum length 1. Pinned reviewer or artifact role used by the execution bundle. Minimum accepted length or value is 1.
- `artifact.version` — string; required; minimum length 1. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 1.
- `artifact.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `artifact.framingHash` — JSON value; required. SHA-256 identity of the shared framing artifact; null or omission means none is pinned. A null value explicitly means no current value is available.
- `artifact.framingHash (anyOf branch 1)` — string; required.
- `artifact.framingHash (anyOf branch 2)` — null; required.
- `artifact.contentType` — string; required; minimum length 1. Internet media type of the exact skill artifact bytes, such as text/markdown; use it when loading the artifact. Minimum accepted length or value is 1.
- `artifact.bytes` — string; required. Exact UTF-8 skill artifact body; verify its SHA-256 before activation.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"artifact": {
"type": "object",
"properties": {
"role": {
"type": "string",
"minLength": 1,
"description": "Pinned reviewer or artifact role used by the execution bundle. Minimum accepted length or value is 1."
},
"version": {
"type": "string",
"minLength": 1,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Minimum accepted length or value is 1."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
},
"framingHash": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
{
"type": "null"
}
],
"description": "SHA-256 identity of the shared framing artifact; null or omission means none is pinned. A null value explicitly means no current value is available."
},
"contentType": {
"type": "string",
"minLength": 1,
"description": "Internet media type of the exact skill artifact bytes, such as text/markdown; use it when loading the artifact. Minimum accepted length or value is 1."
},
"bytes": {
"type": "string",
"description": "Exact UTF-8 skill artifact body; verify its SHA-256 before activation."
}
},
"required": [
"role",
"version",
"sha256",
"framingHash",
"contentType",
"bytes"
],
"additionalProperties": false,
"description": "Exact content-addressed skill artifact selected from the frozen execution bundle."
}
},
"required": [
"artifact"
],
"additionalProperties": false
}
```
**Example structured result (active-skill)**
```json
{
"artifact": {
"role": "engineering",
"version": "1",
"sha256": "182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7",
"framingHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"contentType": "text/markdown",
"bytes": "# Engineering review\n\nValidate the brief against the repository evidence."
}
}
```
Bindings: skillSha256 from structuredContent.artifact.sha256.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"artifact\":{\"role\":\"engineering\",\"version\":\"1\",\"sha256\":\"182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7\",\"framingHash\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"contentType\":\"text/markdown\",\"bytes\":\"# Engineering review\\n\\nValidate the brief against the repository evidence.\"}}"
}
],
"structuredContent": {
"artifact": {
"role": "engineering",
"version": "1",
"sha256": "182b9a93e2b09a21a9cd632254e97f9dcb7582f34a50c2619588f75edde15dc7",
"framingHash": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
"contentType": "text/markdown",
"bytes": "# Engineering review\n\nValidate the brief against the repository evidence."
}
}
}
```
Next permitted action: Verify exact pinned hash/framing and execute only the active skill bytes.
**Example requests**
- “/semel load the exact pinned rubric for this local review”
- “/semel fetch the shared framing for the active reviewer lens”
- “/semel fetch the local-execution addendum pinned in this bundle”
Errors: `PROTOCOL_VERSION_UNSUPPORTED`, `LEASE_EXPIRED`, `STALE_FENCE`, `CANCELLED`, `PAYLOAD_REJECTED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_claim`, `review_execution_checkpoint_append`, `review_execution_status`.
---
### review_execution_status
Return the authoritative execution state — always callable, the documented fail-safe.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `reviewSessionId` — string; optional; minimum length 1. Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
- `executionId` — string; optional; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"reviewSessionId": {
"type": "string",
"minLength": 1,
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1."
},
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1."
}
},
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}"
}
```
**Returns**
- `execution` — JSON value; required. Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available.
- `execution (anyOf branch 1)` — object; required.
- `execution (anyOf branch 1).executionId` — string; required. External-execution identifier returned by a successful execution claim or status lookup.
- `execution (anyOf branch 1).reviewSessionId` — string; required. Review-session identifier returned by review_start, review_new_pass, or execution status.
- `execution (anyOf branch 1).state` — string; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `execution (anyOf branch 1).currentFenceGeneration` — integer; required. Active execution fence generation; refresh local state to this integer before attempting another fenced write. The value must be an integer.
- `execution (anyOf branch 1).activeSkillCursor` — string | null; required. Opaque cursor naming the active pinned skill; null means no skill is currently active. A null value explicitly means no current value is available.
- `execution (anyOf branch 2)` — null; required.
- `epoch` — JSON value; required. Execution fence generation associated with the current control-block state; omit before an epoch exists. A null value explicitly means no current value is available.
- `epoch (anyOf branch 1)` — object; required.
- `epoch (anyOf branch 1).fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. The value must be an integer.
- `epoch (anyOf branch 1).leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `epoch (anyOf branch 1).heartbeatAt` — string | null; required. RFC 3339 timestamp of the most recent accepted heartbeat; null means none was recorded. A null value explicitly means no current value is available.
- `epoch (anyOf branch 1).claimedByPrincipal` — string; required. Agent principal identifier that claimed this execution epoch.
- `epoch (anyOf branch 1).startedAt` — string; required. RFC 3339 timestamp when the execution epoch started.
- `epoch (anyOf branch 1).endedAt` — string | null; required. RFC 3339 timestamp when the execution epoch ended; null means it remains active. A null value explicitly means no current value is available.
- `epoch (anyOf branch 2)` — null; required.
- `checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `certificateReference` — JSON value; required. Reference to the terminal execution certificate when finalization has produced one; null means no certificate exists yet. A null value explicitly means no current value is available.
- `certificateReference (anyOf branch 1)` — object; required.
- `certificateReference (anyOf branch 1).certificateId` — string; required. Execution-certificate identifier assigned after successful finalization.
- `certificateReference (anyOf branch 1).state` — string; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `certificateReference (anyOf branch 2)` — null; required.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"execution": {
"anyOf": [
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup."
},
"reviewSessionId": {
"type": "string",
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status."
},
"state": {
"type": "string",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"currentFenceGeneration": {
"type": "integer",
"description": "Active execution fence generation; refresh local state to this integer before attempting another fenced write. The value must be an integer."
},
"activeSkillCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor naming the active pinned skill; null means no skill is currently active. A null value explicitly means no current value is available."
}
},
"required": [
"executionId",
"reviewSessionId",
"state",
"currentFenceGeneration",
"activeSkillCursor"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available."
},
"epoch": {
"anyOf": [
{
"type": "object",
"properties": {
"fenceGeneration": {
"type": "integer",
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"heartbeatAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp of the most recent accepted heartbeat; null means none was recorded. A null value explicitly means no current value is available."
},
"claimedByPrincipal": {
"type": "string",
"description": "Agent principal identifier that claimed this execution epoch."
},
"startedAt": {
"type": "string",
"description": "RFC 3339 timestamp when the execution epoch started."
},
"endedAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 timestamp when the execution epoch ended; null means it remains active. A null value explicitly means no current value is available."
}
},
"required": [
"fenceGeneration",
"leaseExpiresAt",
"heartbeatAt",
"claimedByPrincipal",
"startedAt",
"endedAt"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. A null value explicitly means no current value is available."
},
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"certificateReference": {
"anyOf": [
{
"type": "object",
"properties": {
"certificateId": {
"type": "string",
"description": "Execution-certificate identifier assigned after successful finalization."
},
"state": {
"type": "string",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
}
},
"required": [
"certificateId",
"state"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Reference to the terminal execution certificate when finalization has produced one; null means no certificate exists yet. A null value explicitly means no current value is available."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"execution",
"epoch",
"checkpointHighWaterMark",
"openQuestionCount",
"certificateReference",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (execution-status)**
```json
{
"execution": {
"executionId": "xex_fixture_engineering",
"reviewSessionId": "rs_fixture_engineering",
"state": "running",
"currentFenceGeneration": 1,
"activeSkillCursor": null
},
"epoch": {
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"heartbeatAt": "2026-09-07T16:00:30.000Z",
"claimedByPrincipal": "example",
"startedAt": "2026-09-07T16:00:00.000Z",
"endedAt": null
},
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"certificateReference": null,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Bindings: controlBlock from structuredContent.controlBlock.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"execution\":{\"executionId\":\"xex_fixture_engineering\",\"reviewSessionId\":\"rs_fixture_engineering\",\"state\":\"running\",\"currentFenceGeneration\":1,\"activeSkillCursor\":null},\"epoch\":{\"fenceGeneration\":1,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"heartbeatAt\":\"2026-09-07T16:00:30.000Z\",\"claimedByPrincipal\":\"example\",\"startedAt\":\"2026-09-07T16:00:00.000Z\",\"endedAt\":null},\"checkpointHighWaterMark\":5,\"openQuestionCount\":0,\"certificateReference\":null,\"controlBlock\":{\"state\":{\"sessionState\":\"running\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_skill_get\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_checkpoint_append\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_heartbeat\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_question_open\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_submit\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_release\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_sync\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":5,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}}}"
}
],
"structuredContent": {
"execution": {
"executionId": "xex_fixture_engineering",
"reviewSessionId": "rs_fixture_engineering",
"state": "running",
"currentFenceGeneration": 1,
"activeSkillCursor": null
},
"epoch": {
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"heartbeatAt": "2026-09-07T16:00:30.000Z",
"claimedByPrincipal": "example",
"startedAt": "2026-09-07T16:00:00.000Z",
"endedAt": null
},
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"certificateReference": null,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Next permitted action: Follow allowedNextOperations and the authoritative fence/lease/question counts.
**Example requests**
- “what is the current state of my claimed session”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_sync`.
---
### review_execution_submit
Submit a revision of the final typed reviewer result for validation and idempotent finalization; the completed response returns the next cascade step handoff.
- Mode: write
- Risk: high
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `submissionRevision` — integer; required. Monotonic final-submission attempt number for this execution, starting at 1. Minimum accepted length or value is 0. The value must be an integer.
- `canonicalBundleSha256` — string; required; minimum length 1. Lowercase hexadecimal SHA-256 digest of the frozen canonical execution bundle. Minimum accepted length or value is 1.
- `protocolVersion` — constant "1.2"; optional. Semel external-execution protocol version used for this bundle or state. Omit the field when it does not apply; omission is distinct from an empty value. This branch always uses "1.2".
- `resultIdentitySchemaVersion` — constant 2; optional. Version of the reviewer identity schema required for this execution result. Omit the field when it does not apply; omission is distinct from an empty value. This branch always uses 2.
- `result` — JSON value; required. Complete typed reviewer submission produced against the frozen execution bundle.
- `result (anyOf branch 1)` — object; required.
- `result (anyOf branch 1).reviewer` — "product" | "engineering" | "design" | "security" | "test"; required. Reviewer role responsible for this submitted result. Allowed values: "product", "engineering", "design", "security", "test".
- `result (anyOf branch 1).findings` — array; optional; default []; maximum items 50. Reviewer findings associated with the selected brief version. Omission uses the schema default []. An empty array explicitly means no matching items.
- `result (anyOf branch 1).findings[]` — object; required.
- `result (anyOf branch 1).findings[].section` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief section key associated with the question, finding, proposal, or decision entry. Allowed values: "goal", "userPersonaContext", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 1).findings[].note` — string; required; maximum length 4000. Reviewer-facing finding detail that explains the observed issue and the evidence-based change requested. Maximum accepted length or value is 4000.
- `result (anyOf branch 1).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 (anyOf branch 1).findings[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).findings[].citations[]` — JSON value; required.
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 1)` — object; required.
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 2)` — object; required.
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 3)` — object; required.
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).findings[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).questions` — array; optional; default []; maximum items 50. Durable decision questions raised by the reviewer; omission defaults to no questions and each supplied question must be actionable. Omission uses the schema default []. An empty array explicitly means no matching items.
- `result (anyOf branch 1).questions[]` — object; required.
- `result (anyOf branch 1).questions[].section` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief section key associated with the question, finding, proposal, or decision entry. Allowed values: "goal", "userPersonaContext", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 1).questions[].decisionKey` — string; required; minimum length 1; maximum length 200. Caller-stable semantic key for one decision question; keep it unchanged across idempotent retries and review passes. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).questions[].text` — string; required; maximum length 4000. Human-authored or model-produced text for this typed record. Maximum accepted length or value is 4000.
- `result (anyOf branch 1).questions[].context_excerpt` — string; optional; maximum length 2000. Optional bounded context stored with the reviewer decision question. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 2000.
- `result (anyOf branch 1).questions[].recommendation` — string; required; minimum length 1; maximum length 1200. Reviewer-recommended answer to the decision question, supplied so the respondent can accept or override it. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).questions[].recommendationRationale` — string; required; minimum length 1; maximum length 1200. Evidence-based explanation of why the reviewer recommends the proposed answer. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).questions[].consequenceOfDeferring` — string; required; minimum length 1; maximum length 1200. Concrete product or engineering consequence of postponing the requested decision. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).questions[].options` — array; optional; minimum items 2; maximum items 5. Explicit answer choices for a decision question; omission means the respondent may provide free-form text. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).questions[].options[]` — string; required; maximum length 1000.
- `result (anyOf branch 1).questions[].suggestedRespondentId` — string; required; minimum length 1; maximum length 160. Optional Semel user identifier suggested to answer the question. Accepted length or value is 1 through 160, inclusive.
- `result (anyOf branch 1).questions[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).questions[].citations[]` — JSON value; required.
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 1)` — object; required.
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 2)` — object; required.
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 3)` — object; required.
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).questions[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).codeClaims` — array; optional; maximum items 50. Repository-behavior claims proposed by the reviewer; each claim requires bounded citations and is verified before durable publication. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).codeClaims[]` — object; required.
- `result (anyOf branch 1).codeClaims[].claim` — string; required; minimum length 1; maximum length 4000. Concise factual assertion about repository behavior that the evidence checker must verify before publication. Accepted length or value is 1 through 4000, inclusive.
- `result (anyOf branch 1).codeClaims[].citations` — array; required; minimum items 1; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. An empty array explicitly means no matching items.
- `result (anyOf branch 1).codeClaims[].citations[]` — JSON value; required.
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 1)` — object; required.
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 2)` — object; required.
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 3)` — object; required.
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).codeClaims[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).codeClaims[].consequence` — string; optional; minimum length 1; maximum length 4000. Concrete impact if the finding is left unresolved, used to explain its severity and required follow-up. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive.
- `result (anyOf branch 1).codeClaims[].uncertainty` — string; optional; minimum length 1; maximum length 4000. Bounded explanation of any residual uncertainty in a repository claim after examining the cited evidence. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive.
- `result (anyOf branch 1).codeClaims[].recommendation` — string; optional; minimum length 1; maximum length 4000. Reviewer-recommended answer to the decision question, supplied so the respondent can accept or override it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive.
- `result (anyOf branch 1).sectionEdits` — object; optional. Complete replacements for supplied brief sections; omitted sections remain unchanged and supplied empty values intentionally clear them, except customerFacingLaunchMessage, which is never cleared and is authored only by Product Review. Omit the field when it does not apply; omission is distinct from an empty value.
- `result (anyOf branch 1).sectionEdits.goal` — string; optional; maximum length 4000. Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 1).sectionEdits.userPersonaContext` — string; optional; maximum length 4000. User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 1).sectionEdits.customerFacingLaunchMessage` — string; optional; maximum length 4000. Copy-ready end-user launch message stating the capability, value, and one concrete example, authored only by Product Review. Must be 1 to 120 whitespace-separated words; never send an empty value to clear it — omit the key and record a product-definition gap instead.
- `result (anyOf branch 1).sectionEdits.scope` — string; optional; maximum length 4000. Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 1).sectionEdits.outOfScope` — string; optional; maximum length 4000. Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 1).sectionEdits.requirements` — array; optional; maximum items 50. Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.requirements[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 1).sectionEdits.edgeCases` — array; optional; maximum items 50. Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.edgeCases[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria` — array; optional; maximum items 50. Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[]` — object; required.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].id` — string; optional; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[]` — JSON value; required.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1)` — object; required.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2)` — object; required.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3)` — object; required.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).sectionEdits.rolesPermissions` — array; optional; maximum items 50. Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.rolesPermissions[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 1).sectionEdits.states` — array; optional; maximum items 50. User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.states[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 1).sectionEdits.productSolution` — string; optional; maximum length 4000. Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 1).sectionEdits.technicalSolution` — string; optional; maximum length 4000. Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 1).sectionEdits.dataModelImplications` — string; optional; maximum length 4000. Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 1).sectionEdits.architectureAssumptions` — string; optional; maximum length 4000. Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 1).sectionEdits.design` — string; optional; maximum length 4000. Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 1).sectionEdits.testingQaChecklist` — array; optional; maximum items 50. Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.testingQaChecklist[]` — object; required.
- `result (anyOf branch 1).sectionEdits.testingQaChecklist[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 1).sectionEdits.testPlanUnit` — array; optional; maximum items 50. Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.testPlanUnit[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 1).sectionEdits.testPlanIntegration` — array; optional; maximum items 50. Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.testPlanIntegration[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 1).sectionEdits.testPlanUiUx` — array; optional; maximum items 50. Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.testPlanUiUx[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 1).sectionEdits.openQuestions` — array; optional; maximum items 50. Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.openQuestions[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 1).sectionEdits.generatedTickets` — array; optional; maximum items 50. Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.generatedTickets[]` — object; required.
- `result (anyOf branch 1).sectionEdits.generatedTickets[].id` — string; optional; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).sectionEdits.generatedTickets[].title` — string; required; minimum length 1; maximum length 500. Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
- `result (anyOf branch 1).sectionEdits.generatedTickets[].description` — JSON value; optional. Human-readable explanatory text; null or omission means no description was supplied. Omit the field when it does not apply; omission is distinct from an empty value. A null value explicitly means no current value is available. Maximum accepted length or value is 10000.
- `result (anyOf branch 1).sectionEdits.generatedTickets[].description (anyOf branch 1)` — string; optional; maximum length 10000.
- `result (anyOf branch 1).sectionEdits.generatedTickets[].description (anyOf branch 2)` — null; optional.
- `result (anyOf branch 1).sectionEdits.generatedTickets[].boundCriteria` — array; optional; maximum items 50. Stable acceptance-criterion IDs implemented by this work order. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.generatedTickets[].boundCriteria[]` — string; required; minimum length 1; maximum length 200.
- `result (anyOf branch 1).sectionEdits.generatedTickets[].boundRequirements` — array; optional; maximum items 50. Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.generatedTickets[].boundRequirements[]` — string; required; minimum length 1; maximum length 200.
- `result (anyOf branch 1).sectionEdits.requiredEvidence` — array; optional; maximum items 50. Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[]` — object; required.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].id` — string; optional; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[]` — JSON value; required.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 1)` — object; required.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 2)` — object; required.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 3)` — object; required.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 1).sectionEdits.requiredEvidence[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 1).sectionEdits.decisions` — array; optional; maximum items 50. Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.decisions[]` — object; required.
- `result (anyOf branch 1).sectionEdits.decisions[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 1).sectionEdits.decisions[].source` — string; optional; maximum length 1000. Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000.
- `result (anyOf branch 1).sectionEdits.sourceArtifactLinks` — array; optional; maximum items 50. Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 1).sectionEdits.sourceArtifactLinks[]` — object; required.
- `result (anyOf branch 1).sectionEdits.sourceArtifactLinks[].label` — string; required; minimum length 1; maximum length 1000. Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 1).sectionEdits.sourceArtifactLinks[].kind` — string; optional; maximum length 200. Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `result (anyOf branch 1).summaryOfChanges` — string; optional; maximum length 4000. Bounded reviewer summary of the submitted section changes for user review and durable history. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 2)` — object; required.
- `result (anyOf branch 2).findings` — array; optional; default []; maximum items 50. Reviewer findings associated with the selected brief version. Omission uses the schema default []. An empty array explicitly means no matching items.
- `result (anyOf branch 2).findings[]` — object; required.
- `result (anyOf branch 2).findings[].section` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief section key associated with the question, finding, proposal, or decision entry. Allowed values: "goal", "userPersonaContext", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 2).findings[].note` — string; required; maximum length 4000. Reviewer-facing finding detail that explains the observed issue and the evidence-based change requested. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).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 (anyOf branch 2).findings[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).findings[].citations[]` — JSON value; required.
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 1)` — object; required.
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 2)` — object; required.
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 3)` — object; required.
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).findings[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).questions` — array; optional; default []; maximum items 50. Durable decision questions raised by the reviewer; omission defaults to no questions and each supplied question must be actionable. Omission uses the schema default []. An empty array explicitly means no matching items.
- `result (anyOf branch 2).questions[]` — object; required.
- `result (anyOf branch 2).questions[].section` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "scope" | "outOfScope" | "requirements" | "edgeCases" | "acceptanceCriteria" | "rolesPermissions" | "states" | "productSolution" | "technicalSolution" | "dataModelImplications" | "architectureAssumptions" | "design" | "testingQaChecklist" | "testPlanUnit" | "testPlanIntegration" | "testPlanUiUx" | "openQuestions" | "generatedTickets" | "requiredEvidence" | "decisions" | "sourceArtifactLinks"; required. Canonical brief section key associated with the question, finding, proposal, or decision entry. Allowed values: "goal", "userPersonaContext", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 2).questions[].decisionKey` — string; required; minimum length 1; maximum length 200. Caller-stable semantic key for one decision question; keep it unchanged across idempotent retries and review passes. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).questions[].text` — string; required; maximum length 4000. Human-authored or model-produced text for this typed record. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).questions[].context_excerpt` — string; optional; maximum length 2000. Optional bounded context stored with the reviewer decision question. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 2000.
- `result (anyOf branch 2).questions[].recommendation` — string; required; minimum length 1; maximum length 1200. Reviewer-recommended answer to the decision question, supplied so the respondent can accept or override it. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).questions[].recommendationRationale` — string; required; minimum length 1; maximum length 1200. Evidence-based explanation of why the reviewer recommends the proposed answer. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).questions[].consequenceOfDeferring` — string; required; minimum length 1; maximum length 1200. Concrete product or engineering consequence of postponing the requested decision. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).questions[].options` — array; optional; minimum items 2; maximum items 5. Explicit answer choices for a decision question; omission means the respondent may provide free-form text. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).questions[].options[]` — string; required; maximum length 1000.
- `result (anyOf branch 2).questions[].suggestedRespondentId` — string; required; minimum length 1; maximum length 160. Optional Semel user identifier suggested to answer the question. Accepted length or value is 1 through 160, inclusive.
- `result (anyOf branch 2).questions[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).questions[].citations[]` — JSON value; required.
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 1)` — object; required.
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 2)` — object; required.
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 3)` — object; required.
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).questions[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).codeClaims` — array; optional; maximum items 50. Repository-behavior claims proposed by the reviewer; each claim requires bounded citations and is verified before durable publication. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).codeClaims[]` — object; required.
- `result (anyOf branch 2).codeClaims[].claim` — string; required; minimum length 1; maximum length 4000. Concise factual assertion about repository behavior that the evidence checker must verify before publication. Accepted length or value is 1 through 4000, inclusive.
- `result (anyOf branch 2).codeClaims[].citations` — array; required; minimum items 1; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. An empty array explicitly means no matching items.
- `result (anyOf branch 2).codeClaims[].citations[]` — JSON value; required.
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 1)` — object; required.
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 2)` — object; required.
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 3)` — object; required.
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).codeClaims[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).codeClaims[].consequence` — string; optional; minimum length 1; maximum length 4000. Concrete impact if the finding is left unresolved, used to explain its severity and required follow-up. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive.
- `result (anyOf branch 2).codeClaims[].uncertainty` — string; optional; minimum length 1; maximum length 4000. Bounded explanation of any residual uncertainty in a repository claim after examining the cited evidence. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive.
- `result (anyOf branch 2).codeClaims[].recommendation` — string; optional; minimum length 1; maximum length 4000. Reviewer-recommended answer to the decision question, supplied so the respondent can accept or override it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 4000, inclusive.
- `result (anyOf branch 2).sectionEdits` — object; optional. Complete replacements for supplied brief sections; omitted sections remain unchanged and supplied empty values intentionally clear them, except customerFacingLaunchMessage, which is never cleared and is authored only by Product Review. Omit the field when it does not apply; omission is distinct from an empty value.
- `result (anyOf branch 2).sectionEdits.goal` — string; optional; maximum length 4000. Concise statement of the outcome this brief must achieve. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).sectionEdits.userPersonaContext` — string; optional; maximum length 4000. User and situational context that explains who needs the outcome and why. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).sectionEdits.customerFacingLaunchMessage` — string; optional; maximum length 4000. Copy-ready end-user launch message stating the capability, value, and one concrete example, authored only by Product Review. Must be 1 to 120 whitespace-separated words; never send an empty value to clear it — omit the key and record a product-definition gap instead.
- `result (anyOf branch 2).sectionEdits.scope` — string; optional; maximum length 4000. Work explicitly included in this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).sectionEdits.outOfScope` — string; optional; maximum length 4000. Work explicitly excluded from this brief. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).sectionEdits.requirements` — array; optional; maximum items 50. Ordered product requirements; an empty array explicitly records none. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.requirements[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 2).sectionEdits.edgeCases` — array; optional; maximum items 50. Known edge cases the implementation must handle. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.edgeCases[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria` — array; optional; maximum items 50. Stable-ID acceptance criteria that define completion of the brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[]` — object; required.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].id` — string; optional; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[]` — JSON value; required.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1)` — object; required.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2)` — object; required.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3)` — object; required.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).sectionEdits.acceptanceCriteria[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).sectionEdits.rolesPermissions` — array; optional; maximum items 50. Roles and permission boundaries relevant to the feature. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.rolesPermissions[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 2).sectionEdits.states` — array; optional; maximum items 50. User-visible and system lifecycle states the feature must represent. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.states[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 2).sectionEdits.productSolution` — string; optional; maximum length 4000. Product behavior chosen to satisfy the goal and requirements. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).sectionEdits.technicalSolution` — string; optional; maximum length 4000. Implementation approach and major technical constraints. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).sectionEdits.dataModelImplications` — string; optional; maximum length 4000. Required data model changes, invariants, and migration implications. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).sectionEdits.architectureAssumptions` — string; optional; maximum length 4000. Architecture assumptions the implementation relies on. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).sectionEdits.design` — string; optional; maximum length 4000. Interaction and visual design requirements for the feature. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).sectionEdits.testingQaChecklist` — array; optional; maximum items 50. Mutable QA checklist; checked state and attribution are preserved by server reconciliation. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.testingQaChecklist[]` — object; required.
- `result (anyOf branch 2).sectionEdits.testingQaChecklist[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 2).sectionEdits.testPlanUnit` — array; optional; maximum items 50. Unit-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.testPlanUnit[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 2).sectionEdits.testPlanIntegration` — array; optional; maximum items 50. Integration-level verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.testPlanIntegration[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 2).sectionEdits.testPlanUiUx` — array; optional; maximum items 50. Browser, accessibility, and visual verification plan. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.testPlanUiUx[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 2).sectionEdits.openQuestions` — array; optional; maximum items 50. Unresolved questions that still require an explicit answer. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.openQuestions[]` — string; required; minimum length 1; maximum length 1000.
- `result (anyOf branch 2).sectionEdits.generatedTickets` — array; optional; maximum items 50. Ordered implementation work orders derived from this brief. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.generatedTickets[]` — object; required.
- `result (anyOf branch 2).sectionEdits.generatedTickets[].id` — string; optional; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).sectionEdits.generatedTickets[].title` — string; required; minimum length 1; maximum length 500. Human-readable title displayed in Semel. Accepted length or value is 1 through 500, inclusive.
- `result (anyOf branch 2).sectionEdits.generatedTickets[].description` — JSON value; optional. Human-readable explanatory text; null or omission means no description was supplied. Omit the field when it does not apply; omission is distinct from an empty value. A null value explicitly means no current value is available. Maximum accepted length or value is 10000.
- `result (anyOf branch 2).sectionEdits.generatedTickets[].description (anyOf branch 1)` — string; optional; maximum length 10000.
- `result (anyOf branch 2).sectionEdits.generatedTickets[].description (anyOf branch 2)` — null; optional.
- `result (anyOf branch 2).sectionEdits.generatedTickets[].boundCriteria` — array; optional; maximum items 50. Stable acceptance-criterion IDs implemented by this work order. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.generatedTickets[].boundCriteria[]` — string; required; minimum length 1; maximum length 200.
- `result (anyOf branch 2).sectionEdits.generatedTickets[].boundRequirements` — array; optional; maximum items 50. Stable requirement IDs implemented by this work order; omission is tolerated only for legacy reads. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.generatedTickets[].boundRequirements[]` — string; required; minimum length 1; maximum length 200.
- `result (anyOf branch 2).sectionEdits.requiredEvidence` — array; optional; maximum items 50. Stable-ID evidence requirements needed to prove completion. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[]` — object; required.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].implementation` — boolean; optional. Whether this criterion requires implementation; omission defaults to implementation work. Omit the field when it does not apply; omission is distinct from an empty value.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].manualEvidence` — object; optional. Structured exemption required when implementation is explicitly false. Omit the field when it does not apply; omission is distinct from an empty value.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].manualEvidence.rationale` — string; required; minimum length 1; maximum length 1000. Durable explanation for why this item is exempted from implementation work. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].manualEvidence.evidencePath` — string; required; minimum length 1; maximum length 1000. Durable location or procedure for collecting the manual evidence. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].id` — string; optional; minimum length 1; maximum length 200. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations` — array; optional; maximum items 5. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[]` — JSON value; required.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 1)` — object; required.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 2)` — object; required.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 3)` — object; required.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `result (anyOf branch 2).sectionEdits.requiredEvidence[].citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `result (anyOf branch 2).sectionEdits.decisions` — array; optional; maximum items 50. Recorded product or engineering decisions with optional source provenance. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.decisions[]` — object; required.
- `result (anyOf branch 2).sectionEdits.decisions[].text` — string; required; minimum length 1; maximum length 1000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 2).sectionEdits.decisions[].source` — string; optional; maximum length 1000. Optional human-readable provenance for the decision. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 1000.
- `result (anyOf branch 2).sectionEdits.sourceArtifactLinks` — array; optional; maximum items 50. Artifact labels referenced by the brief; an empty array means none are linked. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `result (anyOf branch 2).sectionEdits.sourceArtifactLinks[]` — object; required.
- `result (anyOf branch 2).sectionEdits.sourceArtifactLinks[].label` — string; required; minimum length 1; maximum length 1000. Human-readable label displayed for this record. Accepted length or value is 1 through 1000, inclusive.
- `result (anyOf branch 2).sectionEdits.sourceArtifactLinks[].kind` — string; optional; maximum length 200. Discriminator identifying the typed variant represented by this object. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `result (anyOf branch 2).summaryOfChanges` — string; optional; maximum length 4000. Bounded reviewer summary of the submitted section changes for user review and durable history. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 4000.
- `result (anyOf branch 2).reviewerIdentity` — object; required. Server-stamped reviewer occurrence identity, or the bounded occurrence echo accepted from a schema-2 result.
- `result (anyOf branch 2).reviewerIdentity.schemaVersion` — constant 2; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2.
- `result (anyOf branch 2).reviewerIdentity.occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"submissionRevision": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Monotonic final-submission attempt number for this execution, starting at 1. Minimum accepted length or value is 0. The value must be an integer."
},
"canonicalBundleSha256": {
"type": "string",
"minLength": 1,
"description": "Lowercase hexadecimal SHA-256 digest of the frozen canonical execution bundle. Minimum accepted length or value is 1."
},
"protocolVersion": {
"type": "string",
"const": "1.2",
"description": "Semel external-execution protocol version used for this bundle or state. Omit the field when it does not apply; omission is distinct from an empty value. This branch always uses \"1.2\"."
},
"resultIdentitySchemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the reviewer identity schema required for this execution result. Omit the field when it does not apply; omission is distinct from an empty value. This branch always uses 2."
},
"result": {
"anyOf": [
{
"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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."
},
"customerFacingLaunchMessage": {
"type": "string",
"maxLength": 4000,
"description": "Copy-ready end-user launch message stating the capability, value, and one concrete example, authored only by Product Review. Must be 1 to 120 whitespace-separated words; never send an empty value to clear it — omit the key and record a product-definition gap instead."
},
"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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, except customerFacingLaunchMessage, which is never cleared and is authored only by Product Review. 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
},
{
"type": "object",
"properties": {
"findings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"section": {
"type": "string",
"enum": [
"goal",
"userPersonaContext",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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."
},
"customerFacingLaunchMessage": {
"type": "string",
"maxLength": 4000,
"description": "Copy-ready end-user launch message stating the capability, value, and one concrete example, authored only by Product Review. Must be 1 to 120 whitespace-separated words; never send an empty value to clear it — omit the key and record a product-definition gap instead."
},
"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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, except customerFacingLaunchMessage, which is never cleared and is authored only by Product Review. 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."
},
"reviewerIdentity": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 2,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 2."
},
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
}
},
"required": [
"schemaVersion",
"occurrenceId"
],
"additionalProperties": false,
"description": "Server-stamped reviewer occurrence identity, or the bounded occurrence echo accepted from a schema-2 result."
}
},
"required": [
"reviewerIdentity"
],
"additionalProperties": false
}
],
"description": "Complete typed reviewer submission produced against the frozen execution bundle."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"submissionRevision",
"canonicalBundleSha256",
"result",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"submissionRevision": 1,
"canonicalBundleSha256": "fe4c3e639e846e481ebd4512b4c0a04d4ad1b3c80a6a132212ea632f0a1656e8",
"result": {
"reviewer": "engineering",
"findings": [],
"questions": [],
"summaryOfChanges": "Validated retry-safe payment intent reuse."
},
"idempotencyKey": "recipe-execution-submit-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"submissionRevision": 1,
"canonicalBundleSha256": "{{canonicalBundleSha256}}",
"result": {
"reviewer": "engineering",
"findings": [],
"questions": [],
"summaryOfChanges": "Validated retry-safe payment intent reuse."
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `value (anyOf branch 1)` — object; optional.
- `value (anyOf branch 1).status` — constant "completed"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "completed".
- `value (anyOf branch 1).outcome` — "version_created" | "no_change"; required. Typed result of this operation; union branches define the follow-up action for each value. Allowed values: "version_created", "no_change".
- `value (anyOf branch 1).briefVersionId` — string | null; required. Immutable brief-version identifier created or selected by finalization; null means no version was produced. A null value explicitly means no current value is available.
- `value (anyOf branch 1).briefVersionNum` — JSON value; required. Monotonic brief-version number created or selected by finalization; null means no version was produced. A null value explicitly means no current value is available. The value must be an integer.
- `value (anyOf branch 1).briefVersionNum (anyOf branch 1)` — integer; required.
- `value (anyOf branch 1).briefVersionNum (anyOf branch 2)` — null; required.
- `value (anyOf branch 1).certificateReference` — JSON value; required. Reference to the terminal execution certificate when finalization has produced one; null means no certificate exists yet. A null value explicitly means no current value is available.
- `value (anyOf branch 1).certificateReference (anyOf branch 1)` — object; required.
- `value (anyOf branch 1).certificateReference (anyOf branch 1).certificateId` — string; required. Execution-certificate identifier assigned after successful finalization.
- `value (anyOf branch 1).certificateReference (anyOf branch 1).state` — string; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 1).certificateReference (anyOf branch 2)` — null; required.
- `value (anyOf branch 1).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 1).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 1).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 1).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 1).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 1).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 1).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 1).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 1).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 1).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 1).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 1).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 1).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 1).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 1).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 1).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 1).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 1).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 1).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 1).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 1).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 1).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 1).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
- `value (anyOf branch 1).cascade` — JSON value; optional. Observed next-step cascade handoff after submission or review admission. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 1).status` — constant "awaiting_local_claim"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "awaiting_local_claim".
- `value (anyOf branch 1).cascade (anyOf branch 1).runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `value (anyOf branch 1).cascade (anyOf branch 1).reviewSessionId` — string | null; required. Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available.
- `value (anyOf branch 1).cascade (anyOf branch 1).cascadeStepId` — string; required. Identifier of the configured reviewer-cascade step associated with this run.
- `value (anyOf branch 1).cascade (anyOf branch 1).grantApprovalUri` — string; optional. Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 1).cascade (anyOf branch 1).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
- `value (anyOf branch 1).cascade (anyOf branch 2)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 2).status` — constant "in_progress"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "in_progress".
- `value (anyOf branch 1).cascade (anyOf branch 2).runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `value (anyOf branch 1).cascade (anyOf branch 2).reviewSessionId` — string | null; required. Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available.
- `value (anyOf branch 1).cascade (anyOf branch 2).cascadeStepId` — string; required. Identifier of the configured reviewer-cascade step associated with this run.
- `value (anyOf branch 1).cascade (anyOf branch 2).execution` — JSON value; required. Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available. Allowed values: "hosted", "local".
- `value (anyOf branch 1).cascade (anyOf branch 2).execution (anyOf branch 1)` — "hosted" | "local"; required.
- `value (anyOf branch 1).cascade (anyOf branch 2).execution (anyOf branch 2)` — null; required.
- `value (anyOf branch 1).cascade (anyOf branch 3)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 3).status` — constant "settled"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "settled".
- `value (anyOf branch 1).cascade (anyOf branch 3).runId` — string; required. Review-run identifier returned by a review start, status, or cascade handoff result.
- `value (anyOf branch 1).cascade (anyOf branch 3).cascadeStepId` — string; required. Identifier of the configured reviewer-cascade step associated with this run.
- `value (anyOf branch 1).cascade (anyOf branch 3).runStatus` — string; required. Terminal or current review-run status returned by finalization when no additional cascade dispatch is required.
- `value (anyOf branch 1).cascade (anyOf branch 4)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 4).status` — constant "gate_wait"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "gate_wait".
- `value (anyOf branch 1).cascade (anyOf branch 4).cascadeStepId` — string; required. Identifier of the configured reviewer-cascade step associated with this run.
- `value (anyOf branch 1).cascade (anyOf branch 5)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 5).status` — constant "blocked"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "blocked".
- `value (anyOf branch 1).cascade (anyOf branch 5).cascadeStepId` — string; required. Identifier of the configured reviewer-cascade step associated with this run.
- `value (anyOf branch 1).cascade (anyOf branch 5).reason` — constant "cap_exceeded"; required. Typed or human-readable reason for the current outcome; omission means no reason is required. This branch always uses "cap_exceeded".
- `value (anyOf branch 1).cascade (anyOf branch 5).hardCapCents` — integer; required. Workspace hard spending cap in integer US-dollar cents. The value must be an integer.
- `value (anyOf branch 1).cascade (anyOf branch 5).spentThisMonthCents` — integer; required. Workspace spend in integer US-dollar cents for the current billing month. The value must be an integer.
- `value (anyOf branch 1).cascade (anyOf branch 6)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 6).status` — constant "cascade_complete"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "cascade_complete".
- `value (anyOf branch 1).cascade (anyOf branch 7)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 7).status` — constant "none"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "none".
- `value (anyOf branch 1).cascade (anyOf branch 8)` — object; optional.
- `value (anyOf branch 1).cascade (anyOf branch 8).status` — constant "pending"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "pending".
- `value (anyOf branch 1).cascade (anyOf branch 8).reason` — string; required. Typed or human-readable reason for the current outcome; omission means no reason is required.
- `value (anyOf branch 2)` — object; optional.
- `value (anyOf branch 2).status` — constant "repair_required"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "repair_required".
- `value (anyOf branch 2).submissionRevision` — integer; required. Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer.
- `value (anyOf branch 2).payloadSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the canonical submitted payload.
- `value (anyOf branch 2).violations` — array; required; minimum items 1. Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items.
- `value (anyOf branch 2).violations[]` — object; required.
- `value (anyOf branch 2).violations[].pointer` — string; required. RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root.
- `value (anyOf branch 2).violations[].ruleId` — string; required. Stable validation-rule identifier for this violation.
- `value (anyOf branch 2).violations[].remediationCategory` — string; required. Machine-readable category describing the required correction.
- `value (anyOf branch 2).violations[].message` — string; required. User-facing validation or remediation message that contains no secret material.
- `value (anyOf branch 2).remainingRepairAttempts` — integer; required; minimum 0. Distinct corrected submissions still allowed before operator attention is required. Minimum accepted length or value is 0. The value must be an integer.
- `value (anyOf branch 2).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 2).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 2).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 2).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 2).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 2).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 2).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 2).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 2).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 2).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 2).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 2).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 2).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 2).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 2).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 2).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 2).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 2).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 2).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 2).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 2).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 2).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 2).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 2).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 2).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 2).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
- `value (anyOf branch 3)` — object; optional.
- `value (anyOf branch 3).status` — constant "needs_attention"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "needs_attention".
- `value (anyOf branch 3).reason` — "repair_budget_exhausted" | "non_repairable"; required. Typed or human-readable reason for the current outcome; omission means no reason is required. Allowed values: "repair_budget_exhausted", "non_repairable".
- `value (anyOf branch 3).submissionRevision` — integer; required. Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer.
- `value (anyOf branch 3).violations` — array; required. Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items.
- `value (anyOf branch 3).violations[]` — object; required.
- `value (anyOf branch 3).violations[].pointer` — string; required. RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root.
- `value (anyOf branch 3).violations[].ruleId` — string; required. Stable validation-rule identifier for this violation.
- `value (anyOf branch 3).violations[].remediationCategory` — string; required. Machine-readable category describing the required correction.
- `value (anyOf branch 3).violations[].message` — string; required. User-facing validation or remediation message that contains no secret material.
- `value (anyOf branch 3).history` — array; required. Complete safe submission-validation history, oldest attempt first. An empty array explicitly means no matching items.
- `value (anyOf branch 3).history[]` — object; required.
- `value (anyOf branch 3).history[].submissionRevision` — integer; required. Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer.
- `value (anyOf branch 3).history[].payloadSha256` — string; required. Lowercase hexadecimal SHA-256 digest of the canonical submitted payload.
- `value (anyOf branch 3).history[].outcome` — "repair_required" | "needs_attention" | "version_conflict" | "completed"; required. Typed result of this operation; union branches define the follow-up action for each value. Allowed values: "repair_required", "needs_attention", "version_conflict", "completed".
- `value (anyOf branch 3).history[].violations` — array; required. Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items.
- `value (anyOf branch 3).history[].violations[]` — object; required.
- `value (anyOf branch 3).history[].violations[].pointer` — string; required. RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root.
- `value (anyOf branch 3).history[].violations[].ruleId` — string; required. Stable validation-rule identifier for this violation.
- `value (anyOf branch 3).history[].violations[].remediationCategory` — string; required. Machine-readable category describing the required correction.
- `value (anyOf branch 3).history[].violations[].message` — string; required. User-facing validation or remediation message that contains no secret material.
- `value (anyOf branch 3).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 3).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 3).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 3).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 3).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 3).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 3).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 3).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 3).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 3).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 3).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 3).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 3).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 3).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 3).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 3).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 3).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 3).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 3).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 3).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 3).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 3).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 3).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 3).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 3).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 3).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 3).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 3).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 3).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 3).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 3).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
- `value (anyOf branch 4)` — object; optional.
- `value (anyOf branch 4).status` — constant "version_conflict"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "version_conflict".
- `value (anyOf branch 4).pinnedBriefBaseVersionId` — string; required. Immutable brief-version identifier frozen when the execution began and used for stale-base detection.
- `value (anyOf branch 4).pinnedBriefBaseVersionNum` — integer; required. Monotonic brief-version number frozen when the execution began and used for stale-base detection. The value must be an integer.
- `value (anyOf branch 4).currentBriefVersionId` — string; required. Immutable identifier of the current canonical brief version reported after a stale-base rejection.
- `value (anyOf branch 4).currentBriefVersionNum` — integer; required. Monotonic number of the current canonical brief version reported after a stale-base rejection. The value must be an integer.
- `value (anyOf branch 4).controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `value (anyOf branch 4).controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `value (anyOf branch 4).controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `value (anyOf branch 4).controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `value (anyOf branch 4).controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `value (anyOf branch 4).controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `value (anyOf branch 4).controlBlock.allowedNextOperations[]` — object; required.
- `value (anyOf branch 4).controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `value (anyOf branch 4).controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `value (anyOf branch 4).controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `value (anyOf branch 4).controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `value (anyOf branch 4).controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `value (anyOf branch 4).controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `value (anyOf branch 4).controlBlock.completion.unmetRequirements[]` — string; required.
- `value (anyOf branch 4).controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `value (anyOf branch 4).controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `value (anyOf branch 4).controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `value (anyOf branch 4).controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `value (anyOf branch 4).controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `value (anyOf branch 4).controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `value (anyOf branch 4).controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `value (anyOf branch 4).controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `value (anyOf branch 4).controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 4).controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `value (anyOf branch 4).controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `value (anyOf branch 4).controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `value (anyOf branch 4).controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `value (anyOf branch 4).controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `value (anyOf branch 4).controlBlock.error.permittedNextOperations[]` — string; required.
- `value (anyOf branch 4).controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `value (anyOf branch 4).controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "completed",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"completed\"."
},
"outcome": {
"type": "string",
"enum": [
"version_created",
"no_change"
],
"description": "Typed result of this operation; union branches define the follow-up action for each value. Allowed values: \"version_created\", \"no_change\"."
},
"briefVersionId": {
"type": [
"string",
"null"
],
"description": "Immutable brief-version identifier created or selected by finalization; null means no version was produced. A null value explicitly means no current value is available."
},
"briefVersionNum": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Monotonic brief-version number created or selected by finalization; null means no version was produced. A null value explicitly means no current value is available. The value must be an integer."
},
"certificateReference": {
"anyOf": [
{
"type": "object",
"properties": {
"certificateId": {
"type": "string",
"description": "Execution-certificate identifier assigned after successful finalization."
},
"state": {
"type": "string",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
}
},
"required": [
"certificateId",
"state"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Reference to the terminal execution certificate when finalization has produced one; null means no certificate exists yet. A null value explicitly means no current value is available."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
},
"cascade": {
"anyOf": [
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "awaiting_local_claim",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"awaiting_local_claim\"."
},
"runId": {
"type": "string",
"description": "Review-run identifier returned by a review start, status, or cascade handoff result."
},
"reviewSessionId": {
"type": [
"string",
"null"
],
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available."
},
"cascadeStepId": {
"type": "string",
"description": "Identifier of the configured reviewer-cascade step associated with this run."
},
"grantApprovalUri": {
"type": "string",
"description": "Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"runId",
"reviewSessionId",
"cascadeStepId",
"controlBlock"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "in_progress",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"in_progress\"."
},
"runId": {
"type": "string",
"description": "Review-run identifier returned by a review start, status, or cascade handoff result."
},
"reviewSessionId": {
"type": [
"string",
"null"
],
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available."
},
"cascadeStepId": {
"type": "string",
"description": "Identifier of the configured reviewer-cascade step associated with this run."
},
"execution": {
"anyOf": [
{
"type": "string",
"enum": [
"hosted",
"local"
]
},
{
"type": "null"
}
],
"description": "Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available. Allowed values: \"hosted\", \"local\"."
}
},
"required": [
"status",
"runId",
"reviewSessionId",
"cascadeStepId",
"execution"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "settled",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"settled\"."
},
"runId": {
"type": "string",
"description": "Review-run identifier returned by a review start, status, or cascade handoff result."
},
"cascadeStepId": {
"type": "string",
"description": "Identifier of the configured reviewer-cascade step associated with this run."
},
"runStatus": {
"type": "string",
"description": "Terminal or current review-run status returned by finalization when no additional cascade dispatch is required."
}
},
"required": [
"status",
"runId",
"cascadeStepId",
"runStatus"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "gate_wait",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"gate_wait\"."
},
"cascadeStepId": {
"type": "string",
"description": "Identifier of the configured reviewer-cascade step associated with this run."
}
},
"required": [
"status",
"cascadeStepId"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "blocked",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"blocked\"."
},
"cascadeStepId": {
"type": "string",
"description": "Identifier of the configured reviewer-cascade step associated with this run."
},
"reason": {
"type": "string",
"const": "cap_exceeded",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. This branch always uses \"cap_exceeded\"."
},
"hardCapCents": {
"type": "integer",
"description": "Workspace hard spending cap in integer US-dollar cents. The value must be an integer."
},
"spentThisMonthCents": {
"type": "integer",
"description": "Workspace spend in integer US-dollar cents for the current billing month. The value must be an integer."
}
},
"required": [
"status",
"cascadeStepId",
"reason",
"hardCapCents",
"spentThisMonthCents"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "cascade_complete",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"cascade_complete\"."
}
},
"required": [
"status"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "none",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"none\"."
}
},
"required": [
"status"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "pending",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"pending\"."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required."
}
},
"required": [
"status",
"reason"
],
"additionalProperties": false
}
],
"description": "Observed next-step cascade handoff after submission or review admission. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"status",
"outcome",
"briefVersionId",
"briefVersionNum",
"certificateReference",
"controlBlock"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "repair_required",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"repair_required\"."
},
"submissionRevision": {
"type": "integer",
"description": "Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer."
},
"payloadSha256": {
"type": "string",
"description": "Lowercase hexadecimal SHA-256 digest of the canonical submitted payload."
},
"violations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pointer": {
"type": "string",
"description": "RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root."
},
"ruleId": {
"type": "string",
"description": "Stable validation-rule identifier for this violation."
},
"remediationCategory": {
"type": "string",
"description": "Machine-readable category describing the required correction."
},
"message": {
"type": "string",
"description": "User-facing validation or remediation message that contains no secret material."
}
},
"required": [
"pointer",
"ruleId",
"remediationCategory",
"message"
],
"additionalProperties": false
},
"minItems": 1,
"description": "Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items."
},
"remainingRepairAttempts": {
"type": "integer",
"minimum": 0,
"description": "Distinct corrected submissions still allowed before operator attention is required. Minimum accepted length or value is 0. The value must be an integer."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"submissionRevision",
"payloadSha256",
"violations",
"remainingRepairAttempts",
"controlBlock"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "needs_attention",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"needs_attention\"."
},
"reason": {
"type": "string",
"enum": [
"repair_budget_exhausted",
"non_repairable"
],
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Allowed values: \"repair_budget_exhausted\", \"non_repairable\"."
},
"submissionRevision": {
"type": "integer",
"description": "Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer."
},
"violations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pointer": {
"type": "string",
"description": "RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root."
},
"ruleId": {
"type": "string",
"description": "Stable validation-rule identifier for this violation."
},
"remediationCategory": {
"type": "string",
"description": "Machine-readable category describing the required correction."
},
"message": {
"type": "string",
"description": "User-facing validation or remediation message that contains no secret material."
}
},
"required": [
"pointer",
"ruleId",
"remediationCategory",
"message"
],
"additionalProperties": false
},
"description": "Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items."
},
"history": {
"type": "array",
"items": {
"type": "object",
"properties": {
"submissionRevision": {
"type": "integer",
"description": "Monotonic final-submission attempt number for this execution, starting at 1. The value must be an integer."
},
"payloadSha256": {
"type": "string",
"description": "Lowercase hexadecimal SHA-256 digest of the canonical submitted payload."
},
"outcome": {
"type": "string",
"enum": [
"repair_required",
"needs_attention",
"version_conflict",
"completed"
],
"description": "Typed result of this operation; union branches define the follow-up action for each value. Allowed values: \"repair_required\", \"needs_attention\", \"version_conflict\", \"completed\"."
},
"violations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"pointer": {
"type": "string",
"description": "RFC 6901 JSON Pointer locating the invalid result property; an empty pointer refers to the result root."
},
"ruleId": {
"type": "string",
"description": "Stable validation-rule identifier for this violation."
},
"remediationCategory": {
"type": "string",
"description": "Machine-readable category describing the required correction."
},
"message": {
"type": "string",
"description": "User-facing validation or remediation message that contains no secret material."
}
},
"required": [
"pointer",
"ruleId",
"remediationCategory",
"message"
],
"additionalProperties": false
},
"description": "Safe structured validation failures that must be repaired before resubmission. An empty array explicitly means no matching items."
}
},
"required": [
"submissionRevision",
"payloadSha256",
"outcome",
"violations"
],
"additionalProperties": false
},
"description": "Complete safe submission-validation history, oldest attempt first. An empty array explicitly means no matching items."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"reason",
"submissionRevision",
"violations",
"history",
"controlBlock"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "version_conflict",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"version_conflict\"."
},
"pinnedBriefBaseVersionId": {
"type": "string",
"description": "Immutable brief-version identifier frozen when the execution began and used for stale-base detection."
},
"pinnedBriefBaseVersionNum": {
"type": "integer",
"description": "Monotonic brief-version number frozen when the execution began and used for stale-base detection. The value must be an integer."
},
"currentBriefVersionId": {
"type": "string",
"description": "Immutable identifier of the current canonical brief version reported after a stale-base rejection."
},
"currentBriefVersionNum": {
"type": "integer",
"description": "Monotonic number of the current canonical brief version reported after a stale-base rejection. The value must be an integer."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"status",
"pinnedBriefBaseVersionId",
"pinnedBriefBaseVersionNum",
"currentBriefVersionId",
"currentBriefVersionNum",
"controlBlock"
],
"additionalProperties": false
}
]
}
```
**Example structured result (completed)**
```json
{
"status": "completed",
"outcome": "no_change",
"briefVersionId": null,
"briefVersionNum": null,
"certificateReference": {
"certificateId": "example",
"state": "pending"
},
"controlBlock": {
"state": {
"sessionState": "completed",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": true,
"unmetRequirements": [],
"certificateState": "pending"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
},
"cascade": {
"status": "awaiting_local_claim",
"runId": "run_fixture_review",
"reviewSessionId": "rs_fixture_engineering",
"cascadeStepId": "example",
"controlBlock": {
"state": {
"sessionState": "awaiting_local_claim",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_grant_request",
"preconditions": [
"A human must approve the execution grant before a harness can claim this run."
]
},
{
"operation": "review_execution_wait",
"preconditions": [
"A human must approve the execution grant before a harness can claim this run."
]
},
{
"operation": "review_execution_claim",
"preconditions": [
"A human must approve the execution grant before a harness can claim this run."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Bindings: cascade from structuredContent.cascade.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"status\":\"completed\",\"outcome\":\"no_change\",\"briefVersionId\":null,\"briefVersionNum\":null,\"certificateReference\":{\"certificateId\":\"example\",\"state\":\"pending\"},\"controlBlock\":{\"state\":{\"sessionState\":\"completed\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":true,\"unmetRequirements\":[],\"certificateState\":\"pending\"},\"progress\":{\"checkpointHighWaterMark\":5,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}},\"cascade\":{\"status\":\"awaiting_local_claim\",\"runId\":\"run_fixture_review\",\"reviewSessionId\":\"rs_fixture_engineering\",\"cascadeStepId\":\"example\",\"controlBlock\":{\"state\":{\"sessionState\":\"awaiting_local_claim\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_grant_request\",\"preconditions\":[\"A human must approve the execution grant before a harness can claim this run.\"]},{\"operation\":\"review_execution_wait\",\"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_wait",
"preconditions": [
"A human must approve the execution grant before a harness can claim this run."
]
},
{
"operation": "review_execution_claim",
"preconditions": [
"A human must approve the execution grant before a harness can claim this run."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 0,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
}
```
Next permitted action: Follow cascade.status; request the next grant only for awaiting_local_claim and never wait for certificate signing.
**Example requests**
- “submit my completed review for this session”
Errors: `CAPABILITY_UNSUPPORTED`, `VALIDATION_FAILED`, `BRIEF_VERSION_CONFLICT`, `QUESTION_OPEN`, `STALE_FENCE`, `CANCELLED`, `PAYLOAD_REJECTED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_status`, `review_execution_checkpoint_append`, `review_execution_grant_request`, `review_status`.
---
### review_execution_sync
Cursor-poll for recorded answers, cancellation, handoff, and lease state.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `cursor` — string; optional; minimum length 1. Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; optional. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 0. The value must be an integer.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"cursor": {
"type": "string",
"minLength": 1,
"description": "Opaque pagination or synchronization cursor from the preceding response; omit to start from the beginning. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"executionId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"cursor": "sync_fixture_next",
"fenceGeneration": 1
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"cursor": "{{syncCursor}}",
"fenceGeneration": 1
}
```
**Returns**
- `answers` — array; required. Accepted durable answers emitted since the requested synchronization cursor, in causal order. An empty array explicitly means no matching items.
- `answers[]` — object; required.
- `answers[].questionId` — string; required. Durable question identifier returned by review_question_open or execution sync.
- `answers[].answerId` — string; required. Immutable answer identifier assigned by Semel when an answer attempt is recorded.
- `answers[].channel` — string; required. Typed delivery or answer channel recorded as provenance.
- `answers[].answerText` — string; required. Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit.
- `answers[].answeredAt` — string; required. RFC 3339 timestamp when the active answer was recorded.
- `cancellationRequested` — boolean; required. Whether a cancellation request is pending for this execution.
- `serverCommands` — array; required. Ordered server commands issued since the supplied synchronization cursor. An empty array explicitly means no matching items.
- `serverCommands[]` — object; required.
- `serverCommands[].command` — string; required. Server-issued synchronization command the harness must process in order.
- `serverCommands[].issuedAt` — string; required. RFC 3339 timestamp when the server command was issued.
- `handoff` — object; required. Execution handoff state relative to the caller’s remembered epoch.
- `handoff.occurred` — boolean; required. Whether an execution handoff occurred since the supplied cursor or epoch.
- `handoff.currentFenceGeneration` — integer; required. Active execution fence generation; refresh local state to this integer before attempting another fenced write. The value must be an integer.
- `lease` — object; required. Current lease identity and expiry as observed during synchronization.
- `lease.fenceGeneration` — JSON value; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. A null value explicitly means no current value is available. The value must be an integer.
- `lease.fenceGeneration (anyOf branch 1)` — integer; required.
- `lease.fenceGeneration (anyOf branch 2)` — null; required.
- `lease.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `lease.current` — boolean; required. Whether the caller-provided fence generation is still the active execution epoch.
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `suggestedNextPollAt` — string; required. RFC 3339 timestamp for the next recommended sync or status poll.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"answers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"questionId": {
"type": "string",
"description": "Durable question identifier returned by review_question_open or execution sync."
},
"answerId": {
"type": "string",
"description": "Immutable answer identifier assigned by Semel when an answer attempt is recorded."
},
"channel": {
"type": "string",
"description": "Typed delivery or answer channel recorded as provenance."
},
"answerText": {
"type": "string",
"description": "Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit."
},
"answeredAt": {
"type": "string",
"description": "RFC 3339 timestamp when the active answer was recorded."
}
},
"required": [
"questionId",
"answerId",
"channel",
"answerText",
"answeredAt"
],
"additionalProperties": false
},
"description": "Accepted durable answers emitted since the requested synchronization cursor, in causal order. An empty array explicitly means no matching items."
},
"cancellationRequested": {
"type": "boolean",
"description": "Whether a cancellation request is pending for this execution."
},
"serverCommands": {
"type": "array",
"items": {
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "Server-issued synchronization command the harness must process in order."
},
"issuedAt": {
"type": "string",
"description": "RFC 3339 timestamp when the server command was issued."
}
},
"required": [
"command",
"issuedAt"
],
"additionalProperties": false
},
"description": "Ordered server commands issued since the supplied synchronization cursor. An empty array explicitly means no matching items."
},
"handoff": {
"type": "object",
"properties": {
"occurred": {
"type": "boolean",
"description": "Whether an execution handoff occurred since the supplied cursor or epoch."
},
"currentFenceGeneration": {
"type": "integer",
"description": "Active execution fence generation; refresh local state to this integer before attempting another fenced write. The value must be an integer."
}
},
"required": [
"occurred",
"currentFenceGeneration"
],
"additionalProperties": false,
"description": "Execution handoff state relative to the caller’s remembered epoch."
},
"lease": {
"type": "object",
"properties": {
"fenceGeneration": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. A null value explicitly means no current value is available. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"current": {
"type": "boolean",
"description": "Whether the caller-provided fence generation is still the active execution epoch."
}
},
"required": [
"fenceGeneration",
"leaseExpiresAt",
"current"
],
"additionalProperties": false,
"description": "Current lease identity and expiry as observed during synchronization."
},
"nextCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available."
},
"suggestedNextPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended sync or status poll."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"answers",
"cancellationRequested",
"serverCommands",
"handoff",
"lease",
"nextCursor",
"suggestedNextPollAt",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (sync)**
```json
{
"answers": [],
"cancellationRequested": false,
"serverCommands": [],
"handoff": {
"occurred": false,
"currentFenceGeneration": 1
},
"lease": {
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"current": true
},
"nextCursor": "sync_fixture_after_checkpoint",
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Bindings: nextCursor from structuredContent.nextCursor.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"answers\":[],\"cancellationRequested\":false,\"serverCommands\":[],\"handoff\":{\"occurred\":false,\"currentFenceGeneration\":1},\"lease\":{\"fenceGeneration\":1,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"current\":true},\"nextCursor\":\"sync_fixture_after_checkpoint\",\"suggestedNextPollAt\":\"2026-09-07T16:05:00.000Z\",\"controlBlock\":{\"state\":{\"sessionState\":\"running\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_skill_get\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_checkpoint_append\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_heartbeat\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_question_open\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_submit\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_release\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_sync\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":5,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}}}"
}
],
"structuredContent": {
"answers": [],
"cancellationRequested": false,
"serverCommands": [],
"handoff": {
"occurred": false,
"currentFenceGeneration": 1
},
"lease": {
"fenceGeneration": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"current": true
},
"nextCursor": "sync_fixture_after_checkpoint",
"suggestedNextPollAt": "2026-09-07T16:05:00.000Z",
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 5,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Next permitted action: Apply answers, cancellation, handoff, lease, and server commands before more work.
**Example requests**
- “check whether the operator answered my open question yet”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `review_question_answer`, `review_execution_status`.
---
### review_execution_wait
One cheap, immediate status check a local harness polls while it waits on a human: reports an accepted answer, an approved grant, a cancellation, an expired question, a 24-hour approval timeout, a handoff, or a lost lease, and never holds the call. Claimed mode { executionId, fenceGeneration } renews the caller-held lease; pre-claim mode { reviewSessionId } reports a claimable grant and never returns answer text. On event "none", print nothing and sleep retryAfterSeconds (15 s, then 30 s) before calling again with nextCursor.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; optional; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; optional. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 0. The value must be an integer.
- `reviewSessionId` — string; optional; minimum length 1. Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value. Minimum accepted length or value is 1.
- `cursor` — string; optional; minimum length 1; maximum length 512. 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. Accepted length or value is 1 through 512, inclusive.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. 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."
},
"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."
},
"cursor": {
"type": "string",
"minLength": 1,
"maxLength": 512,
"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. Accepted length or value is 1 through 512, inclusive."
}
},
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"cursor": "sync_fixture_next"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"cursor": "{{syncCursor}}"
}
```
**Returns**
- `event` — "none" | "cancelled" | "answer" | "question_expired" | "grant_ready" | "approval_timeout" | "handoff" | "lease_lost"; required. What this check found: none (nothing yet; sleep retryAfterSeconds and check again), answer, grant_ready, lease_lost (reclaim), or a stop event (cancelled, question_expired, approval_timeout, handoff).
- `leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `nextCursor` — string; required. Opaque cursor for the next page or sync; null means the current result is complete.
- `retryAfterSeconds` — integer; required; minimum 0. Seconds to sleep before the next check after an empty result (15, then 30), computed server-side.
- `answers` — array; optional. Accepted durable answers emitted since the requested synchronization cursor, in causal order. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `answers[]` — object; required.
- `answers[].questionId` — string; required. Durable question identifier returned by review_question_open or execution sync.
- `answers[].answerId` — string; required. Immutable answer identifier assigned by Semel when an answer attempt is recorded.
- `answers[].channel` — string; required. Typed delivery or answer channel recorded as provenance.
- `answers[].answerText` — string; required. Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit.
- `answers[].answeredAt` — string; required. RFC 3339 timestamp when the active answer was recorded.
- `grant` — object; optional. Current human-approved execution grant summary. Omit the field when it does not apply; omission is distinct from an empty value.
- `grant.grantId` — string; required. Execution-grant identifier returned when the human approval boundary is satisfied.
- `grant.state` — string; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `grant.intent` — string; required. Human-approved execution intent bound to the grant.
- `grant.expiresAt` — string; required. RFC 3339 expiration timestamp.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"event": {
"type": "string",
"enum": [
"none",
"cancelled",
"answer",
"question_expired",
"grant_ready",
"approval_timeout",
"handoff",
"lease_lost"
],
"description": "What this check found: none (nothing yet; sleep retryAfterSeconds and check again), answer, grant_ready, lease_lost (reclaim), or a stop event (cancelled, question_expired, approval_timeout, handoff)."
},
"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."
},
"nextCursor": {
"type": "string",
"description": "Opaque cursor for the next page or sync; null means the current result is complete."
},
"retryAfterSeconds": {
"type": "integer",
"minimum": 0,
"description": "Seconds to sleep before the next check after an empty result (15, then 30), computed server-side."
},
"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. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"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. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"event",
"leaseExpiresAt",
"nextCursor",
"retryAfterSeconds"
],
"additionalProperties": false
}
```
**Example structured result (answered)**
```json
{
"event": "answer",
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"nextCursor": "example",
"retryAfterSeconds": 0,
"answers": []
}
```
Bindings: answers from structuredContent.answers.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"event\":\"answer\",\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"nextCursor\":\"example\",\"retryAfterSeconds\":0,\"answers\":[]}"
}
],
"structuredContent": {
"event": "answer",
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"nextCursor": "example",
"retryAfterSeconds": 0,
"answers": []
}
}
```
Next permitted action: On event none print nothing, sleep retryAfterSeconds without model turns, and wait again with nextCursor; on answer, resume the dependent work.
**Example requests**
- “wait for the operator to answer my open question”
- “wait until my local execution grant is approved”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `review_execution_sync`, `review_execution_heartbeat`, `review_execution_grant_request`, `review_execution_claim`.
---
### review_new_pass
Start a repeat AI review pass for a brief, anchored on a prior run from review_status. Defaults to local when the caller has review:execute; a review:run-only caller defaults to hosted with a warning. Pass execution:'hosted' to opt into hosted execution.
- Mode: write
- Risk: high
- Scopes: `brief:read`, `review:run`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1.
- `anchorRunId` — string; required; minimum length 1. Completed review-run identifier used as the starting point for a new pass; obtain it from review_status or review_start. Minimum accepted length or value is 1.
- `execution` — "hosted" | "local"; optional. Requested or observed execution lane: hosted Semel execution or local external execution. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: "hosted", "local".
- `explicitOverride` — object; optional. Explicit bounded reviewer selection for this new pass; omission uses the saved project configuration. Omit the field when it does not apply; omission is distinct from an empty value.
- `explicitOverride.schemaVersion` — constant 1; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1.
- `explicitOverride.occurrences` — array; required; minimum items 1; maximum items 20. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `explicitOverride.occurrences[]` — object; required.
- `explicitOverride.occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `explicitOverride.occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `explicitOverride.occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `explicitOverride.occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `explicitOverride.occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `explicitOverride.occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `explicitOverride.occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `explicitOverride.occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `explicitOverride.occurrences[].model` — object; required. Optional model name declared by the harness.
- `explicitOverride.occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `explicitOverride.occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `explicitOverride.occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `explicitOverride.occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `explicitOverride.occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1."
},
"anchorRunId": {
"type": "string",
"minLength": 1,
"description": "Completed review-run identifier used as the starting point for a new pass; obtain it from review_status or review_start. Minimum accepted length or value is 1."
},
"execution": {
"type": "string",
"enum": [
"hosted",
"local"
],
"description": "Requested or observed execution lane: hosted Semel execution or local external execution. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: \"hosted\", \"local\"."
},
"explicitOverride": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 1,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"schemaVersion",
"occurrences"
],
"additionalProperties": false,
"description": "Explicit bounded reviewer selection for this new pass; omission uses the saved project configuration. 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": [
"briefId",
"anchorRunId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"anchorRunId": "run_fixture_review",
"execution": "local",
"idempotencyKey": "recipe-review-new-pass-v1"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"anchorRunId": "{{anchorRunId}}",
"execution": "local",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `warnings` — array; optional. Non-fatal origination notices; present only when an omitted execution mode was resolved to hosted because the caller lacks review:execute.
- `warnings[]` — object; required.
- `warnings[].code` — constant "LOCAL_DEFAULT_DOWNGRADED_TO_HOSTED"; required. Stable machine-readable protocol error code used to choose a documented recovery action. This branch always uses "LOCAL_DEFAULT_DOWNGRADED_TO_HOSTED".
- `warnings[].message` — string; required. User-facing validation or remediation message that contains no secret material.
- `run` — object; required. Newly created review run and its queue position.
- `run.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `run.status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `run.position` — integer; required; minimum 0. Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer.
- `cascade` — object; required. Observed next-step cascade handoff after submission or review admission.
- `cascade.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `cascade.phase` — string; required. Current cascade phase reported by Semel.
- `dispatch` — object; optional. Post-commit admission and dispatch result for the newly created review run. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.status` — "invoking" | "queued" | "evidence_wait" | "settled" | "awaiting_local_claim"; required. Current typed status; the schema enum or union branch lists every allowed value. Allowed values: "invoking", "queued", "evidence_wait", "settled", "awaiting_local_claim".
- `dispatch.admitted` — boolean; required. Whether the review run was admitted for execution.
- `dispatch.softCapWarning` — boolean; required. Optional nonblocking workspace spending warning attached to admission.
- `dispatch.evidenceWait` — object; optional. Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.evidenceWait.manifestId` — string; required. Evidence manifest identifier whose readiness is being reported.
- `dispatch.evidenceWait.state` — constant "pending"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "pending".
- `dispatch.evidenceWait.deadlineAt` — string; required. RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision.
- `dispatch.evidenceWait.requiredRepositoryCount` — integer; required; minimum 0. Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer.
- `dispatch.evidenceWait.unavailableRepositoryCount` — integer; required; minimum 0. Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer.
- `dispatch.evidenceWait.statusPath` — string; required. Relative Semel API path for polling evidence readiness.
- `dispatch.evidenceWait.decisionPath` — string; required. Relative Semel API path for the human evidence-wait decision.
- `dispatch.evidenceWait.actions` — array; required. User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items.
- `dispatch.evidenceWait.actions[]` — string; required.
- `dispatch.reviewSessionId` — string; optional. Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.grantApprovalUri` — string; optional. Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock` — object; optional. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `dispatch.controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `dispatch.controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `dispatch.controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `dispatch.controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `dispatch.controlBlock.allowedNextOperations[]` — object; required.
- `dispatch.controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `dispatch.controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `dispatch.controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `dispatch.controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `dispatch.controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `dispatch.controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `dispatch.controlBlock.completion.unmetRequirements[]` — string; required.
- `dispatch.controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `dispatch.controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `dispatch.controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `dispatch.controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `dispatch.controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `dispatch.controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `dispatch.controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `dispatch.controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `dispatch.controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `dispatch.controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `dispatch.controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `dispatch.controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `dispatch.controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `dispatch.controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `dispatch.controlBlock.error.permittedNextOperations[]` — string; required.
- `dispatch.controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"const": "LOCAL_DEFAULT_DOWNGRADED_TO_HOSTED",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action. This branch always uses \"LOCAL_DEFAULT_DOWNGRADED_TO_HOSTED\"."
},
"message": {
"type": "string",
"description": "User-facing validation or remediation message that contains no secret material."
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
"description": "Non-fatal origination notices; present only when an omitted execution mode was resolved to hosted because the caller lacks review:execute."
},
"run": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"status": {
"type": "string",
"description": "Current typed status; the schema enum or union branch lists every allowed value."
},
"position": {
"type": "integer",
"minimum": 0,
"description": "Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"id",
"status",
"position"
],
"additionalProperties": false,
"description": "Newly created review run and its queue position."
},
"cascade": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"phase": {
"type": "string",
"description": "Current cascade phase reported by Semel."
}
},
"required": [
"projectId",
"phase"
],
"additionalProperties": false,
"description": "Observed next-step cascade handoff after submission or review admission."
},
"dispatch": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"invoking",
"queued",
"evidence_wait",
"settled",
"awaiting_local_claim"
],
"description": "Current typed status; the schema enum or union branch lists every allowed value. Allowed values: \"invoking\", \"queued\", \"evidence_wait\", \"settled\", \"awaiting_local_claim\"."
},
"admitted": {
"type": "boolean",
"description": "Whether the review run was admitted for execution."
},
"softCapWarning": {
"type": "boolean",
"description": "Optional nonblocking workspace spending warning attached to admission."
},
"evidenceWait": {
"type": "object",
"properties": {
"manifestId": {
"type": "string",
"description": "Evidence manifest identifier whose readiness is being reported."
},
"state": {
"type": "string",
"const": "pending",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"pending\"."
},
"deadlineAt": {
"type": "string",
"description": "RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision."
},
"requiredRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer."
},
"unavailableRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer."
},
"statusPath": {
"type": "string",
"description": "Relative Semel API path for polling evidence readiness."
},
"decisionPath": {
"type": "string",
"description": "Relative Semel API path for the human evidence-wait decision."
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items."
}
},
"required": [
"manifestId",
"state",
"deadlineAt",
"requiredRepositoryCount",
"unavailableRepositoryCount",
"statusPath",
"decisionPath",
"actions"
],
"additionalProperties": false,
"description": "Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reviewSessionId": {
"type": "string",
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value."
},
"grantApprovalUri": {
"type": "string",
"description": "Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"status",
"admitted",
"softCapWarning"
],
"additionalProperties": false,
"description": "Post-commit admission and dispatch result for the newly created review run. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"run",
"cascade"
],
"additionalProperties": false
}
```
**Example structured result (local-start)**
```json
{
"run": {
"id": "run_fixture_followup",
"status": "queued",
"position": 0
},
"cascade": {
"projectId": "prj_fixture_checkout",
"phase": "reviewing"
},
"dispatch": {
"status": "awaiting_local_claim",
"admitted": true,
"softCapWarning": false
}
}
```
Bindings: newRunId from structuredContent.run.id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"run\":{\"id\":\"run_fixture_followup\",\"status\":\"queued\",\"position\":0},\"cascade\":{\"projectId\":\"prj_fixture_checkout\",\"phase\":\"reviewing\"},\"dispatch\":{\"status\":\"awaiting_local_claim\",\"admitted\":true,\"softCapWarning\":false}}"
}
],
"structuredContent": {
"run": {
"id": "run_fixture_followup",
"status": "queued",
"position": 0
},
"cascade": {
"projectId": "prj_fixture_checkout",
"phase": "reviewing"
},
"dispatch": {
"status": "awaiting_local_claim",
"admitted": true,
"softCapWarning": false
}
}
}
```
Next permitted action: Request the returned local session grant; do not claim without approval.
**Example requests**
- “/semel re-run the review now that I updated the brief”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `review_start`, `review_status`, `review_execution_status`.
---
### review_question_answer
Record a local_harness answer; first valid terminal answer wins.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `questionId` — string; required; minimum length 1. Durable question identifier returned by review_question_open or execution sync. Minimum accepted length or value is 1.
- `answerText` — string; required; minimum length 1; maximum length 20000. Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit. Accepted length or value is 1 through 20000, inclusive.
- `transmittingAgent` — string; optional; maximum length 200. Optional harness-declared agent identity that transmitted the answer. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `humanAttribution` — object; optional. Optional harness-attested human identity; it is not verified identity. Omit the field when it does not apply; omission is distinct from an empty value.
- `humanAttribution.claimedName` — string; optional; maximum length 200. Optional human name claimed by the harness; it is not verified by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `humanAttribution.claimedEmail` — string; optional; format email. Optional human email claimed by the harness; it is not verified by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Use a syntactically valid email address.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"questionId": {
"type": "string",
"minLength": 1,
"description": "Durable question identifier returned by review_question_open or execution sync. Minimum accepted length or value is 1."
},
"answerText": {
"type": "string",
"minLength": 1,
"maxLength": 20000,
"description": "Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit. Accepted length or value is 1 through 20000, inclusive."
},
"transmittingAgent": {
"type": "string",
"maxLength": 200,
"description": "Optional harness-declared agent identity that transmitted the answer. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"humanAttribution": {
"type": "object",
"properties": {
"claimedName": {
"type": "string",
"maxLength": 200,
"description": "Optional human name claimed by the harness; it is not verified by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"claimedEmail": {
"type": "string",
"format": "email",
"description": "Optional human email claimed by the harness; it is not verified by Semel. Omit the field when it does not apply; omission is distinct from an empty value. Use a syntactically valid email address."
}
},
"additionalProperties": false,
"description": "Optional harness-attested human identity; it is not verified identity. Omit the field when it does not apply; omission is distinct from an empty value."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"questionId",
"answerText",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"questionId": "q_fixture_database",
"answerText": "Use online expand/contract.",
"transmittingAgent": "codex",
"humanAttribution": {
"claimedName": "Repository owner"
},
"idempotencyKey": "recipe-question-answer-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"questionId": "{{questionId}}",
"answerText": "Use online expand/contract.",
"transmittingAgent": "codex",
"humanAttribution": {
"claimedName": "Repository owner"
},
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `outcome` — "accepted" | "conflict"; required. Typed result of this operation; union branches define the follow-up action for each value. Allowed values: "accepted", "conflict".
- `answerId` — string; required. Immutable answer identifier assigned by Semel when an answer attempt is recorded.
- `questionId` — string; required. Durable question identifier returned by review_question_open or execution sync.
- `activeAnswer` — object; required. Question’s current winning immutable answer, including conflict responses.
- `activeAnswer.answerId` — string; required. Immutable answer identifier assigned by Semel when an answer attempt is recorded.
- `activeAnswer.channel` — string; required. Typed delivery or answer channel recorded as provenance.
- `activeAnswer.answerText` — string; required. Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit.
- `activeAnswer.answeredAt` — string; required. RFC 3339 timestamp when the active answer was recorded.
- `roundResumed` — boolean; required. Whether this accepted answer closed the question round and resumed the run.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"outcome": {
"type": "string",
"enum": [
"accepted",
"conflict"
],
"description": "Typed result of this operation; union branches define the follow-up action for each value. Allowed values: \"accepted\", \"conflict\"."
},
"answerId": {
"type": "string",
"description": "Immutable answer identifier assigned by Semel when an answer attempt is recorded."
},
"questionId": {
"type": "string",
"description": "Durable question identifier returned by review_question_open or execution sync."
},
"activeAnswer": {
"type": "object",
"properties": {
"answerId": {
"type": "string",
"description": "Immutable answer identifier assigned by Semel when an answer attempt is recorded."
},
"channel": {
"type": "string",
"description": "Typed delivery or answer channel recorded as provenance."
},
"answerText": {
"type": "string",
"description": "Answer text supplied for the durable question; the API also enforces the documented UTF-8 byte limit."
},
"answeredAt": {
"type": "string",
"description": "RFC 3339 timestamp when the active answer was recorded."
}
},
"required": [
"answerId",
"channel",
"answerText",
"answeredAt"
],
"additionalProperties": false,
"description": "Question’s current winning immutable answer, including conflict responses."
},
"roundResumed": {
"type": "boolean",
"description": "Whether this accepted answer closed the question round and resumed the run."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"outcome",
"answerId",
"questionId",
"activeAnswer",
"roundResumed",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (accepted-answer)**
```json
{
"outcome": "accepted",
"answerId": "example",
"questionId": "q_fixture_database",
"activeAnswer": {
"answerId": "example",
"channel": "local_harness",
"answerText": "Use online expand/contract.",
"answeredAt": "2026-09-07T16:03:00.000Z"
},
"roundResumed": true,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 6,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Bindings: activeAnswer from structuredContent.activeAnswer.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"outcome\":\"accepted\",\"answerId\":\"example\",\"questionId\":\"q_fixture_database\",\"activeAnswer\":{\"answerId\":\"example\",\"channel\":\"local_harness\",\"answerText\":\"Use online expand/contract.\",\"answeredAt\":\"2026-09-07T16:03:00.000Z\"},\"roundResumed\":true,\"controlBlock\":{\"state\":{\"sessionState\":\"running\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_skill_get\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_checkpoint_append\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_heartbeat\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_question_open\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_submit\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_release\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_sync\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":6,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}}}"
}
],
"structuredContent": {
"outcome": "accepted",
"answerId": "example",
"questionId": "q_fixture_database",
"activeAnswer": {
"answerId": "example",
"channel": "local_harness",
"answerText": "Use online expand/contract.",
"answeredAt": "2026-09-07T16:03:00.000Z"
},
"roundResumed": true,
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 6,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Next permitted action: Resume dependent work only when this answer is accepted or matches the existing winner.
**Example requests**
- “the operator just told me the answer locally”
Errors: `STALE_FENCE`, `CANCELLED`, `VALIDATION_FAILED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_question_open`, `review_execution_sync`.
---
### review_question_answer_supersede
Verified-operator correction of an already-accepted answer.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `review:execute`
- Confirmation: operator_grant
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `questionId` — string; required; minimum length 1. Durable question identifier returned by review_question_open or execution sync. Minimum accepted length or value is 1.
- `correctedAnswerText` — string; required; minimum length 1; maximum length 20000. Replacement answer text supplied by a verified operator while preserving answer history. Accepted length or value is 1 through 20000, inclusive.
- `reason` — string; optional; maximum length 2000. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 2000.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"questionId": {
"type": "string",
"minLength": 1,
"description": "Durable question identifier returned by review_question_open or execution sync. Minimum accepted length or value is 1."
},
"correctedAnswerText": {
"type": "string",
"minLength": 1,
"maxLength": 20000,
"description": "Replacement answer text supplied by a verified operator while preserving answer history. Accepted length or value is 1 through 20000, inclusive."
},
"reason": {
"type": "string",
"maxLength": 2000,
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 2000."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"questionId",
"correctedAnswerText",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"questionId": "q_fixture_database",
"correctedAnswerText": "Use an online expand/contract migration with a compatibility window.",
"reason": "Owner clarified rollback requirements.",
"idempotencyKey": "recipe-question-supersede-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"questionId": "{{questionId}}",
"correctedAnswerText": "Use an online expand/contract migration with a compatibility window.",
"reason": "Owner clarified rollback requirements.",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `outcome` — constant "accepted"; required. Typed result of this operation; union branches define the follow-up action for each value. This branch always uses "accepted".
- `newAnswerId` — string; required. Immutable identifier of the corrected answer created by a successful supersede operation.
- `supersededAnswerId` — string; required. Immutable identifier of the prior answer replaced by a successful supersede operation.
- `recoveryCursor` — object; required. Causal boundary the harness must use after an operator corrects an answer.
- `recoveryCursor.invalidatedFromSeq` — integer; required; minimum 0. First checkpoint sequence considered downstream of the corrected answer. Minimum accepted length or value is 0. The value must be an integer.
- `recoveryCursor.activeSkillCursor` — string | null; required. Opaque cursor naming the active pinned skill; null means no skill is currently active. A null value explicitly means no current value is available.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"outcome": {
"type": "string",
"const": "accepted",
"description": "Typed result of this operation; union branches define the follow-up action for each value. This branch always uses \"accepted\"."
},
"newAnswerId": {
"type": "string",
"description": "Immutable identifier of the corrected answer created by a successful supersede operation."
},
"supersededAnswerId": {
"type": "string",
"description": "Immutable identifier of the prior answer replaced by a successful supersede operation."
},
"recoveryCursor": {
"type": "object",
"properties": {
"invalidatedFromSeq": {
"type": "integer",
"minimum": 0,
"description": "First checkpoint sequence considered downstream of the corrected answer. Minimum accepted length or value is 0. The value must be an integer."
},
"activeSkillCursor": {
"type": [
"string",
"null"
],
"description": "Opaque cursor naming the active pinned skill; null means no skill is currently active. A null value explicitly means no current value is available."
}
},
"required": [
"invalidatedFromSeq",
"activeSkillCursor"
],
"additionalProperties": false,
"description": "Causal boundary the harness must use after an operator corrects an answer."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"outcome",
"newAnswerId",
"supersededAnswerId",
"recoveryCursor",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (superseded)**
```json
{
"outcome": "accepted",
"newAnswerId": "ans_fixture_corrected",
"supersededAnswerId": "ans_fixture_original",
"recoveryCursor": {
"invalidatedFromSeq": 1,
"activeSkillCursor": null
},
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 7,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Bindings: recoveryCursor from structuredContent.recoveryCursor.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"outcome\":\"accepted\",\"newAnswerId\":\"ans_fixture_corrected\",\"supersededAnswerId\":\"ans_fixture_original\",\"recoveryCursor\":{\"invalidatedFromSeq\":1,\"activeSkillCursor\":null},\"controlBlock\":{\"state\":{\"sessionState\":\"running\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_skill_get\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_checkpoint_append\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_heartbeat\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_question_open\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_submit\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_release\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_sync\",\"preconditions\":[\"The active epoch may progress, ask a question, submit, or release.\"]},{\"operation\":\"review_execution_status\",\"preconditions\":[\"Always callable as the documented fail-safe.\"]}],\"completion\":{\"complete\":false,\"unmetRequirements\":[],\"certificateState\":\"not_applicable\"},\"progress\":{\"checkpointHighWaterMark\":7,\"openQuestionCount\":0,\"leaseExpiresAt\":\"2026-09-07T16:15:00.000Z\",\"suggestedPollAt\":\"2026-09-07T16:05:00.000Z\"},\"operatorAction\":{\"required\":false}}}"
}
],
"structuredContent": {
"outcome": "accepted",
"newAnswerId": "ans_fixture_corrected",
"supersededAnswerId": "ans_fixture_original",
"recoveryCursor": {
"invalidatedFromSeq": 1,
"activeSkillCursor": null
},
"controlBlock": {
"state": {
"sessionState": "running",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_checkpoint_append",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_question_open",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_submit",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"The active epoch may progress, ask a question, submit, or release."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 7,
"openQuestionCount": 0,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Next permitted action: Rework from recoveryCursor before final submission.
**Example requests**
- “the operator corrected an earlier answer”
Errors: `VALIDATION_FAILED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_question_answer`, `review_execution_status`.
---
### review_question_open
Durably create a question before displaying or delivering it anywhere.
- Mode: write
- Risk: low
- Scopes: `brief:read`, `review:execute`
- Confirmation: none
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `executionId` — string; required; minimum length 1. External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1.
- `fenceGeneration` — integer; required. Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer.
- `clientQuestionId` — string; required; minimum length 1; maximum length 200. Caller-stable logical question identifier; it must equal the MCP idempotency key for this call. Accepted length or value is 1 through 200, inclusive.
- `text` — string; required; minimum length 1; maximum length 20000. Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 20000, inclusive.
- `contextExcerpt` — string; optional; maximum length 20000. Optional bounded context shown with the question; omit when the question is self-contained. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 20000.
- `section` — string; optional; maximum length 200. Canonical brief section key associated with the question, finding, proposal, or decision entry. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `options` — array; optional; minimum items 2; maximum items 5. Explicit answer choices for a decision question; omission means the respondent may provide free-form text. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `options[]` — string; required; minimum length 1; maximum length 500.
- `citations` — array; optional. Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items.
- `citations[]` — JSON value; required.
- `citations[] (anyOf branch 1)` — object; required.
- `citations[] (anyOf branch 1).sourceType` — constant "brief-section"; required. Discriminator identifying the evidence source variant. This branch always uses "brief-section".
- `citations[] (anyOf branch 1).sectionKey` — "goal" | "userPersonaContext" | "customerFacingLaunchMessage" | "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", "customerFacingLaunchMessage", "scope", "outOfScope", "requirements", "edgeCases", "acceptanceCriteria", "rolesPermissions", "states", "productSolution", "technicalSolution", "dataModelImplications", "architectureAssumptions", "design", "testingQaChecklist", "testPlanUnit", "testPlanIntegration", "testPlanUiUx", "openQuestions", "generatedTickets", "requiredEvidence", "decisions", "sourceArtifactLinks".
- `citations[] (anyOf branch 1).statementId` — string; optional; minimum length 1; maximum length 200. Stable identifier of the exact statement within a brief section; omit when the citation addresses the entire section. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `citations[] (anyOf branch 1).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `citations[] (anyOf branch 2)` — object; required.
- `citations[] (anyOf branch 2).sourceType` — constant "artifact"; required. Discriminator identifying the evidence source variant. This branch always uses "artifact".
- `citations[] (anyOf branch 2).artifactId` — string; required; minimum length 1; maximum length 200. Artifact identifier assigned by Semel when source material is uploaded. Accepted length or value is 1 through 200, inclusive.
- `citations[] (anyOf branch 2).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `citations[] (anyOf branch 3)` — object; required.
- `citations[] (anyOf branch 3).sourceType` — constant "repository-code"; required. Discriminator identifying the evidence source variant. This branch always uses "repository-code".
- `citations[] (anyOf branch 3).citationKey` — string; required; minimum length 1; maximum length 200. Stable citation key assigned by Semel to repository evidence. Accepted length or value is 1 through 200, inclusive.
- `citations[] (anyOf branch 3).verbatim` — string; required; minimum length 1; maximum length 1200. Exact bounded evidence text supporting the citation. Accepted length or value is 1 through 1200, inclusive.
- `responseDeadlineHint` — string; optional; format date-time. Optional RFC 3339 requested deadline; Semel clamps it to the documented server bounds. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"executionId": {
"type": "string",
"minLength": 1,
"description": "External-execution identifier returned by a successful execution claim or status lookup. Minimum accepted length or value is 1."
},
"fenceGeneration": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Current positive execution epoch used to reject writes from stale or handed-off harnesses. Minimum accepted length or value is 0. The value must be an integer."
},
"clientQuestionId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Caller-stable logical question identifier; it must equal the MCP idempotency key for this call. Accepted length or value is 1 through 200, inclusive."
},
"text": {
"type": "string",
"minLength": 1,
"maxLength": 20000,
"description": "Human-authored or model-produced text for this typed record. Accepted length or value is 1 through 20000, inclusive."
},
"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",
"customerFacingLaunchMessage",
"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\", \"customerFacingLaunchMessage\", \"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
}
]
},
"description": "Bounded evidence anchors supporting this statement; omit when no citation is claimed and use an empty array only to clear a replaceable list. Omit the field when it does not apply; omission is distinct from an empty value. An empty array explicitly means no matching items."
},
"responseDeadlineHint": {
"type": "string",
"format": "date-time",
"description": "Optional RFC 3339 requested deadline; Semel clamps it to the documented server bounds. Omit the field when it does not apply; omission is distinct from an empty value. Use an RFC 3339 date-time string."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"executionId",
"fenceGeneration",
"clientQuestionId",
"text",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"executionId": "xex_fixture_engineering",
"fenceGeneration": 1,
"clientQuestionId": "recipe-question-open-v1",
"text": "Which migration strategy should implementation use?",
"section": "technicalSolution",
"options": [
"Online expand/contract",
"Scheduled maintenance"
],
"responseDeadlineHint": "2026-09-08T16:00:00.000Z",
"idempotencyKey": "recipe-question-open-v1"
}
```
**Binding template**
```json
{
"executionId": "{{executionId}}",
"fenceGeneration": 1,
"clientQuestionId": "{{clientQuestionId}}",
"text": "Which migration strategy should implementation use?",
"section": "technicalSolution",
"options": [
"Online expand/contract",
"Scheduled maintenance"
],
"responseDeadlineHint": "2026-09-08T16:00:00.000Z",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `questionId` — string; required. Durable question identifier returned by review_question_open or execution sync.
- `deduped` — boolean; required. Whether the existing durable question was returned for an idempotent replay.
- `responseDeadline` — string; required. RFC 3339 timestamp after which the unanswered question requires recovery.
- `deliveryState` — array; required. Per-channel best-effort question notification outcomes. An empty array explicitly means no matching items.
- `deliveryState[]` — object; required.
- `deliveryState[].channel` — "in_app" | "slack"; required. Typed delivery or answer channel recorded as provenance. Allowed values: "in_app", "slack".
- `deliveryState[].state` — "delivered" | "degraded" | "not_configured"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "delivered", "degraded", "not_configured".
- `deliveryState[].providerRef` — string; optional. Optional opaque delivery-provider receipt for the question notification; it is provenance, not a question identifier. Omit the field when it does not apply; omission is distinct from an empty value.
- `deliveryState[].safeError` — string; optional. Sanitized provider error category; omission means no safe delivery error was recorded. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock` — object; required. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance.
- `controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[]` — object; required.
- `controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `controlBlock.completion.unmetRequirements[]` — string; required.
- `controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `controlBlock.error.permittedNextOperations[]` — string; required.
- `controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"questionId": {
"type": "string",
"description": "Durable question identifier returned by review_question_open or execution sync."
},
"deduped": {
"type": "boolean",
"description": "Whether the existing durable question was returned for an idempotent replay."
},
"responseDeadline": {
"type": "string",
"description": "RFC 3339 timestamp after which the unanswered question requires recovery."
},
"deliveryState": {
"type": "array",
"items": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"enum": [
"in_app",
"slack"
],
"description": "Typed delivery or answer channel recorded as provenance. Allowed values: \"in_app\", \"slack\"."
},
"state": {
"type": "string",
"enum": [
"delivered",
"degraded",
"not_configured"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"delivered\", \"degraded\", \"not_configured\"."
},
"providerRef": {
"type": "string",
"description": "Optional opaque delivery-provider receipt for the question notification; it is provenance, not a question identifier. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeError": {
"type": "string",
"description": "Sanitized provider error category; omission means no safe delivery error was recorded. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"channel",
"state"
],
"additionalProperties": false
},
"description": "Per-channel best-effort question notification outcomes. An empty array explicitly means no matching items."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance."
}
},
"required": [
"questionId",
"deduped",
"responseDeadline",
"deliveryState",
"controlBlock"
],
"additionalProperties": false
}
```
**Example structured result (question-opened)**
```json
{
"questionId": "q_fixture_database",
"deduped": false,
"responseDeadline": "2026-09-08T16:00:00.000Z",
"deliveryState": [],
"controlBlock": {
"state": {
"sessionState": "waiting_input",
"protocolVersion": "1.1"
},
"allowedNextOperations": [
{
"operation": "review_execution_skill_get",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_question_answer",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_wait",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 6,
"openQuestionCount": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
```
Bindings: questionId from structuredContent.questionId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"questionId\":\"q_fixture_database\",\"deduped\":false,\"responseDeadline\":\"2026-09-08T16:00:00.000Z\",\"deliveryState\":[],\"controlBlock\":{\"state\":{\"sessionState\":\"waiting_input\",\"protocolVersion\":\"1.1\"},\"allowedNextOperations\":[{\"operation\":\"review_execution_skill_get\",\"preconditions\":[\"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease.\"]},{\"operation\":\"review_question_answer\",\"preconditions\":[\"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease.\"]},{\"operation\":\"review_execution_wait\",\"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_wait",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_sync",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_heartbeat",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_release",
"preconditions": [
"Consumes no hosted resource; a local answer resumes the epoch, or the polling harness may retain its bounded lease."
]
},
{
"operation": "review_execution_status",
"preconditions": [
"Always callable as the documented fail-safe."
]
}
],
"completion": {
"complete": false,
"unmetRequirements": [],
"certificateState": "not_applicable"
},
"progress": {
"checkpointHighWaterMark": 6,
"openQuestionCount": 1,
"leaseExpiresAt": "2026-09-07T16:15:00.000Z",
"suggestedPollAt": "2026-09-07T16:05:00.000Z"
},
"operatorAction": {
"required": false
}
}
}
}
```
Next permitted action: Display the durable question and its options only after this call succeeds.
**Example requests**
- “ask the operator whether this endpoint should require auth”
Errors: `STALE_FENCE`, `CANCELLED`, `VALIDATION_FAILED`, `PROJECT_ACCESS_DENIED`.
Related operations: `review_question_answer`, `review_execution_sync`.
---
### review_start
Start the first AI review cascade for a brief's project. Defaults to local when the caller has review:execute; a review:run-only caller defaults to hosted with a warning. Pass execution:'hosted' to opt into hosted execution.
- Mode: write
- Risk: high
- Scopes: `brief:read`, `review:run`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1.
- `execution` — "hosted" | "local"; optional. Requested or observed execution lane: hosted Semel execution or local external execution. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: "hosted", "local".
- `explicitOverride` — object; optional. Explicit bounded reviewer selection for this new pass; omission uses the saved project configuration. Omit the field when it does not apply; omission is distinct from an empty value.
- `explicitOverride.schemaVersion` — constant 1; required. Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1.
- `explicitOverride.occurrences` — array; required; minimum items 1; maximum items 20. Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items.
- `explicitOverride.occurrences[]` — object; required.
- `explicitOverride.occurrences[].occurrenceId` — string; required; minimum length 1; maximum length 200. Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values.
- `explicitOverride.occurrences[].reviewerRef` — JSON value; required. Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version.
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 1)` — object; required.
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 2)` — object; required.
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 2).skillId` — string; required; minimum length 1. Immutable tenant skill identifier used by a custom reviewer reference.
- `explicitOverride.occurrences[].reviewerRef (anyOf branch 2).versionId` — string; required; minimum length 1. Immutable version identifier returned by the owning brief, reviewer skill, or claim contract.
- `explicitOverride.occurrences[].label` — string; required; minimum length 1. Human-readable label displayed for this record. Minimum accepted length or value is 1.
- `explicitOverride.occurrences[].enabled` — boolean; required. Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable.
- `explicitOverride.occurrences[].skill` — object; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `explicitOverride.occurrences[].skill.version` — string; required; minimum length 1; maximum length 200. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive.
- `explicitOverride.occurrences[].skill.displayVersion` — string; optional; minimum length 1; maximum length 200. Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive.
- `explicitOverride.occurrences[].skill.sha256` — string; required. Lowercase hexadecimal SHA-256 digest used to verify exact bytes.
- `explicitOverride.occurrences[].model` — object; required. Optional model name declared by the harness.
- `explicitOverride.occurrences[].model.provider` — string; required; minimum length 1; maximum length 100. Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive.
- `explicitOverride.occurrences[].model.model` — string; required; minimum length 1; maximum length 200. Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive.
- `explicitOverride.occurrences[].model.reasoning` — JSON value; required. Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive.
- `explicitOverride.occurrences[].model.reasoning (anyOf branch 1)` — string; required; minimum length 1; maximum length 100.
- `explicitOverride.occurrences[].model.reasoning (anyOf branch 2)` — null; required.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1."
},
"execution": {
"type": "string",
"enum": [
"hosted",
"local"
],
"description": "Requested or observed execution lane: hosted Semel execution or local external execution. Omit the field when it does not apply; omission is distinct from an empty value. Allowed values: \"hosted\", \"local\"."
},
"explicitOverride": {
"type": "object",
"properties": {
"schemaVersion": {
"type": "number",
"const": 1,
"description": "Version of the strict schema used to encode this stored or transmitted record. This branch always uses 1."
},
"occurrences": {
"type": "array",
"items": {
"type": "object",
"properties": {
"occurrenceId": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-issued identifier for one ordered reviewer occurrence; repeated reviewer skills have distinct values."
},
"reviewerRef": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
}
},
"required": [
"kind",
"role"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"skillId": {
"type": "string",
"minLength": 1,
"description": "Immutable tenant skill identifier used by a custom reviewer reference."
},
"versionId": {
"type": "string",
"minLength": 1,
"description": "Immutable version identifier returned by the owning brief, reviewer skill, or claim contract."
}
},
"required": [
"kind",
"skillId",
"versionId"
],
"additionalProperties": false
}
],
"description": "Tagged immutable reviewer reference identifying either a built-in role or an exact custom skill version."
},
"label": {
"type": "string",
"minLength": 1,
"description": "Human-readable label displayed for this record. Minimum accepted length or value is 1."
},
"enabled": {
"type": "boolean",
"description": "Whether this frozen reviewer occurrence participates in execution; disabled occurrences remain inspectable."
},
"skill": {
"type": "object",
"properties": {
"version": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 200, inclusive."
},
"displayVersion": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Server-derived human-readable publication number for the exact reviewer skill version. Omit the field when it does not apply; omission is distinct from an empty value. Accepted length or value is 1 through 200, inclusive."
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase hexadecimal SHA-256 digest used to verify exact bytes."
}
},
"required": [
"version",
"sha256"
],
"additionalProperties": false,
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"model": {
"type": "object",
"properties": {
"provider": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Resolved inference provider preserved in the immutable reviewer execution pin. Accepted length or value is 1 through 100, inclusive."
},
"model": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "Optional model name declared by the harness. Accepted length or value is 1 through 200, inclusive."
},
"reasoning": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 100
},
{
"type": "null"
}
],
"description": "Resolved reasoning setting preserved in the immutable model pin; null means the model accepts none. A null value explicitly means no current value is available. Accepted length or value is 1 through 100, inclusive."
}
},
"required": [
"provider",
"model",
"reasoning"
],
"additionalProperties": false,
"description": "Optional model name declared by the harness."
}
},
"required": [
"occurrenceId",
"reviewerRef",
"label",
"enabled",
"skill",
"model"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "Ordered reviewer occurrences preserved by this preset, project configuration, or explicit review override. An empty array explicitly means no matching items."
}
},
"required": [
"schemaVersion",
"occurrences"
],
"additionalProperties": false,
"description": "Explicit bounded reviewer selection for this new pass; omission uses the saved project configuration. 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": [
"briefId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout",
"execution": "hosted",
"idempotencyKey": "recipe-review-start-v1"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}",
"execution": "hosted",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `warnings` — array; optional. Non-fatal origination notices; present only when an omitted execution mode was resolved to hosted because the caller lacks review:execute.
- `warnings[]` — object; required.
- `warnings[].code` — constant "LOCAL_DEFAULT_DOWNGRADED_TO_HOSTED"; required. Stable machine-readable protocol error code used to choose a documented recovery action. This branch always uses "LOCAL_DEFAULT_DOWNGRADED_TO_HOSTED".
- `warnings[].message` — string; required. User-facing validation or remediation message that contains no secret material.
- `run` — object; required. Newly created review run and its queue position.
- `run.id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `run.status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `run.position` — integer; required; minimum 0. Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer.
- `cascade` — object; required. Observed next-step cascade handoff after submission or review admission.
- `cascade.projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `cascade.phase` — string; required. Current cascade phase reported by Semel.
- `dispatch` — object; optional. Post-commit admission and dispatch result for the newly created review run. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.status` — "invoking" | "queued" | "evidence_wait" | "settled" | "awaiting_local_claim"; required. Current typed status; the schema enum or union branch lists every allowed value. Allowed values: "invoking", "queued", "evidence_wait", "settled", "awaiting_local_claim".
- `dispatch.admitted` — boolean; required. Whether the review run was admitted for execution.
- `dispatch.softCapWarning` — boolean; required. Optional nonblocking workspace spending warning attached to admission.
- `dispatch.evidenceWait` — object; optional. Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.evidenceWait.manifestId` — string; required. Evidence manifest identifier whose readiness is being reported.
- `dispatch.evidenceWait.state` — constant "pending"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "pending".
- `dispatch.evidenceWait.deadlineAt` — string; required. RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision.
- `dispatch.evidenceWait.requiredRepositoryCount` — integer; required; minimum 0. Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer.
- `dispatch.evidenceWait.unavailableRepositoryCount` — integer; required; minimum 0. Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer.
- `dispatch.evidenceWait.statusPath` — string; required. Relative Semel API path for polling evidence readiness.
- `dispatch.evidenceWait.decisionPath` — string; required. Relative Semel API path for the human evidence-wait decision.
- `dispatch.evidenceWait.actions` — array; required. User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items.
- `dispatch.evidenceWait.actions[]` — string; required.
- `dispatch.reviewSessionId` — string; optional. Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.grantApprovalUri` — string; optional. Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock` — object; optional. Authoritative runbook state, allowed operations, completion, progress, and recovery guidance. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.state` — object; required. Current typed lifecycle state; the schema enum or union branch defines allowed values.
- `dispatch.controlBlock.state.sessionState` — string; required. Authoritative lifecycle state of the parent review session reported by the execution runbook.
- `dispatch.controlBlock.state.executionId` — string; optional. External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.state.epoch` — integer; optional. Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer.
- `dispatch.controlBlock.state.protocolVersion` — string; required. Semel external-execution protocol version used for this bundle or state.
- `dispatch.controlBlock.state.bundleVersion` — string; optional. Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.allowedNextOperations` — array; required. Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items.
- `dispatch.controlBlock.allowedNextOperations[]` — object; required.
- `dispatch.controlBlock.allowedNextOperations[].operation` — string; required. MCP operation name currently permitted by the runbook control block.
- `dispatch.controlBlock.allowedNextOperations[].preconditions` — array; required. Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items.
- `dispatch.controlBlock.allowedNextOperations[].preconditions[]` — string; required.
- `dispatch.controlBlock.completion` — object; required. Authoritative completion assessment for the current execution state.
- `dispatch.controlBlock.completion.complete` — boolean; required. Whether all protocol completion requirements are currently satisfied.
- `dispatch.controlBlock.completion.unmetRequirements` — array; required. Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items.
- `dispatch.controlBlock.completion.unmetRequirements[]` — string; required.
- `dispatch.controlBlock.completion.certificateState` — "not_applicable" | "pending" | "signed" | "failed"; required. Current execution-certificate state. Allowed values: "not_applicable", "pending", "signed", "failed".
- `dispatch.controlBlock.progress` — object; required. Current durable checkpoint, question, lease, and polling progress.
- `dispatch.controlBlock.progress.checkpointHighWaterMark` — integer; required. Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer.
- `dispatch.controlBlock.progress.openQuestionCount` — integer; required. Number of durable questions still awaiting an accepted answer. The value must be an integer.
- `dispatch.controlBlock.progress.leaseExpiresAt` — string | null; required. RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available.
- `dispatch.controlBlock.progress.suggestedPollAt` — string; required. RFC 3339 timestamp for the next recommended status poll.
- `dispatch.controlBlock.operatorAction` — object; required. Human action required before the protocol may continue.
- `dispatch.controlBlock.operatorAction.required` — boolean; required. Whether the operator action must occur before execution can continue.
- `dispatch.controlBlock.operatorAction.uri` — string; optional. Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.operatorAction.reason` — string; optional. Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.recovery` — object; optional. Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.recovery.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `dispatch.controlBlock.recovery.idempotent` — boolean; required. Whether retrying the named recovery operation with identical arguments is safe.
- `dispatch.controlBlock.recovery.recoveryOperation` — string; optional. Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error` — object; optional. Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error.code` — string; required. Stable machine-readable protocol error code used to choose a documented recovery action.
- `dispatch.controlBlock.error.retryable` — boolean; required. Whether repeating the documented recovery operation can succeed without changing permanent state.
- `dispatch.controlBlock.error.currentState` — string; required. Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery.
- `dispatch.controlBlock.error.permittedNextOperations` — array; required. Operation names permitted after this protocol error. An empty array explicitly means no matching items.
- `dispatch.controlBlock.error.permittedNextOperations[]` — string; required.
- `dispatch.controlBlock.error.operatorApprovalUri` — string; optional. Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value.
- `dispatch.controlBlock.error.safeText` — string; required. Sanitized user-facing error text that excludes secrets and internal exception details.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"warnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"const": "LOCAL_DEFAULT_DOWNGRADED_TO_HOSTED",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action. This branch always uses \"LOCAL_DEFAULT_DOWNGRADED_TO_HOSTED\"."
},
"message": {
"type": "string",
"description": "User-facing validation or remediation message that contains no secret material."
}
},
"required": [
"code",
"message"
],
"additionalProperties": false
},
"description": "Non-fatal origination notices; present only when an omitted execution mode was resolved to hosted because the caller lacks review:execute."
},
"run": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"status": {
"type": "string",
"description": "Current typed status; the schema enum or union branch lists every allowed value."
},
"position": {
"type": "integer",
"minimum": 0,
"description": "Stable zero-based or configured ordering position returned by Semel. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"id",
"status",
"position"
],
"additionalProperties": false,
"description": "Newly created review run and its queue position."
},
"cascade": {
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"phase": {
"type": "string",
"description": "Current cascade phase reported by Semel."
}
},
"required": [
"projectId",
"phase"
],
"additionalProperties": false,
"description": "Observed next-step cascade handoff after submission or review admission."
},
"dispatch": {
"type": "object",
"properties": {
"status": {
"type": "string",
"enum": [
"invoking",
"queued",
"evidence_wait",
"settled",
"awaiting_local_claim"
],
"description": "Current typed status; the schema enum or union branch lists every allowed value. Allowed values: \"invoking\", \"queued\", \"evidence_wait\", \"settled\", \"awaiting_local_claim\"."
},
"admitted": {
"type": "boolean",
"description": "Whether the review run was admitted for execution."
},
"softCapWarning": {
"type": "boolean",
"description": "Optional nonblocking workspace spending warning attached to admission."
},
"evidenceWait": {
"type": "object",
"properties": {
"manifestId": {
"type": "string",
"description": "Evidence manifest identifier whose readiness is being reported."
},
"state": {
"type": "string",
"const": "pending",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"pending\"."
},
"deadlineAt": {
"type": "string",
"description": "RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision."
},
"requiredRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer."
},
"unavailableRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer."
},
"statusPath": {
"type": "string",
"description": "Relative Semel API path for polling evidence readiness."
},
"decisionPath": {
"type": "string",
"description": "Relative Semel API path for the human evidence-wait decision."
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items."
}
},
"required": [
"manifestId",
"state",
"deadlineAt",
"requiredRepositoryCount",
"unavailableRepositoryCount",
"statusPath",
"decisionPath",
"actions"
],
"additionalProperties": false,
"description": "Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reviewSessionId": {
"type": "string",
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. Omit the field when it does not apply; omission is distinct from an empty value."
},
"grantApprovalUri": {
"type": "string",
"description": "Semel URI for approving the next external execution grant; omit until available. Omit the field when it does not apply; omission is distinct from an empty value."
},
"controlBlock": {
"type": "object",
"properties": {
"state": {
"type": "object",
"properties": {
"sessionState": {
"type": "string",
"description": "Authoritative lifecycle state of the parent review session reported by the execution runbook."
},
"executionId": {
"type": "string",
"description": "External-execution identifier returned by a successful execution claim or status lookup. Omit the field when it does not apply; omission is distinct from an empty value."
},
"epoch": {
"type": "integer",
"description": "Execution fence generation associated with the current control-block state; omit before an epoch exists. Omit the field when it does not apply; omission is distinct from an empty value. The value must be an integer."
},
"protocolVersion": {
"type": "string",
"description": "Semel external-execution protocol version used for this bundle or state."
},
"bundleVersion": {
"type": "string",
"description": "Pinned executable bundle version; omit before a bundle is assigned. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"sessionState",
"protocolVersion"
],
"additionalProperties": false,
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values."
},
"allowedNextOperations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string",
"description": "MCP operation name currently permitted by the runbook control block."
},
"preconditions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable conditions that must hold before invoking the operation. An empty array explicitly means no matching items."
}
},
"required": [
"operation",
"preconditions"
],
"additionalProperties": false
},
"description": "Operations currently allowed by the authoritative runbook state. An empty array explicitly means no matching items."
},
"completion": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Whether all protocol completion requirements are currently satisfied."
},
"unmetRequirements": {
"type": "array",
"items": {
"type": "string"
},
"description": "Human-readable completion requirements that are not yet satisfied. An empty array explicitly means no matching items."
},
"certificateState": {
"type": "string",
"enum": [
"not_applicable",
"pending",
"signed",
"failed"
],
"description": "Current execution-certificate state. Allowed values: \"not_applicable\", \"pending\", \"signed\", \"failed\"."
}
},
"required": [
"complete",
"unmetRequirements",
"certificateState"
],
"additionalProperties": false,
"description": "Authoritative completion assessment for the current execution state."
},
"progress": {
"type": "object",
"properties": {
"checkpointHighWaterMark": {
"type": "integer",
"description": "Highest checkpoint sequence durably accepted for the current execution epoch. The value must be an integer."
},
"openQuestionCount": {
"type": "integer",
"description": "Number of durable questions still awaiting an accepted answer. The value must be an integer."
},
"leaseExpiresAt": {
"type": [
"string",
"null"
],
"description": "RFC 3339 lease expiration timestamp; null means no active lease exists. A null value explicitly means no current value is available."
},
"suggestedPollAt": {
"type": "string",
"description": "RFC 3339 timestamp for the next recommended status poll."
}
},
"required": [
"checkpointHighWaterMark",
"openQuestionCount",
"leaseExpiresAt",
"suggestedPollAt"
],
"additionalProperties": false,
"description": "Current durable checkpoint, question, lease, and polling progress."
},
"operatorAction": {
"type": "object",
"properties": {
"required": {
"type": "boolean",
"description": "Whether the operator action must occur before execution can continue."
},
"uri": {
"type": "string",
"description": "Absolute or same-origin URI for the referenced resource or required operator action. Omit the field when it does not apply; omission is distinct from an empty value."
},
"reason": {
"type": "string",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"required"
],
"additionalProperties": false,
"description": "Human action required before the protocol may continue."
},
"recovery": {
"type": "object",
"properties": {
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"idempotent": {
"type": "boolean",
"description": "Whether retrying the named recovery operation with identical arguments is safe."
},
"recoveryOperation": {
"type": "string",
"description": "Operation to call for safe recovery; omit when recovery requires no protocol call. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"retryable",
"idempotent"
],
"additionalProperties": false,
"description": "Safe retry and recovery guidance; omission means no recovery operation is required. Omit the field when it does not apply; omission is distinct from an empty value."
},
"error": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Stable machine-readable protocol error code used to choose a documented recovery action."
},
"retryable": {
"type": "boolean",
"description": "Whether repeating the documented recovery operation can succeed without changing permanent state."
},
"currentState": {
"type": "string",
"description": "Authoritative protocol state at the time of an error; use it with allowedNextOperations to select recovery."
},
"permittedNextOperations": {
"type": "array",
"items": {
"type": "string"
},
"description": "Operation names permitted after this protocol error. An empty array explicitly means no matching items."
},
"operatorApprovalUri": {
"type": "string",
"description": "Semel URI for the required human recovery action; omit when no operator approval applies. Omit the field when it does not apply; omission is distinct from an empty value."
},
"safeText": {
"type": "string",
"description": "Sanitized user-facing error text that excludes secrets and internal exception details."
}
},
"required": [
"code",
"retryable",
"currentState",
"permittedNextOperations",
"safeText"
],
"additionalProperties": false,
"description": "Safe structured protocol error; omission means the operation succeeded without a protocol error. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"state",
"allowedNextOperations",
"completion",
"progress",
"operatorAction"
],
"additionalProperties": false,
"description": "Authoritative runbook state, allowed operations, completion, progress, and recovery guidance. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"status",
"admitted",
"softCapWarning"
],
"additionalProperties": false,
"description": "Post-commit admission and dispatch result for the newly created review run. Omit the field when it does not apply; omission is distinct from an empty value."
}
},
"required": [
"run",
"cascade"
],
"additionalProperties": false
}
```
**Example structured result (hosted-start)**
```json
{
"run": {
"id": "run_fixture_review",
"status": "queued",
"position": 0
},
"cascade": {
"projectId": "prj_fixture_checkout",
"phase": "reviewing"
},
"dispatch": {
"status": "invoking",
"admitted": true,
"softCapWarning": false
}
}
```
Bindings: runId from structuredContent.run.id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"run\":{\"id\":\"run_fixture_review\",\"status\":\"queued\",\"position\":0},\"cascade\":{\"projectId\":\"prj_fixture_checkout\",\"phase\":\"reviewing\"},\"dispatch\":{\"status\":\"invoking\",\"admitted\":true,\"softCapWarning\":false}}"
}
],
"structuredContent": {
"run": {
"id": "run_fixture_review",
"status": "queued",
"position": 0
},
"cascade": {
"projectId": "prj_fixture_checkout",
"phase": "reviewing"
},
"dispatch": {
"status": "invoking",
"admitted": true,
"softCapWarning": false
}
}
}
```
Next permitted action: Poll review_status and respect configless, cap, evidence-wait, or in-flight outcomes.
**Example requests**
- “/semel run the review for the checkout brief”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `review_new_pass`, `review_status`, `review_execution_status`.
---
### review_status
Report the current review cascade state for a brief — steps, in-flight status, and the run id to anchor a new pass on.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `review:run`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `briefId` — string; required; minimum length 1. Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"minLength": 1,
"description": "Brief identifier returned by brief_create or brief_list; it determines the project authorization boundary. Minimum accepted length or value is 1."
}
},
"required": [
"briefId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"briefId": "brf_fixture_checkout"
}
```
**Binding template**
```json
{
"briefId": "{{briefId}}"
}
```
**Returns**
- `projectId` — string; required. Project identifier returned by project_create or project_list; the caller must have access to that project.
- `phase` — string; required. Current cascade phase reported by Semel.
- `inFlight` — boolean; required. Whether the cascade currently has an unsettled run.
- `execution` — JSON value; required. Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available. Allowed values: "hosted", "local".
- `execution (anyOf branch 1)` — "hosted" | "local"; required.
- `execution (anyOf branch 2)` — null; required.
- `awaitingLocalClaim` — boolean; required. Whether the next external run is waiting for a harness claim.
- `steps` — array; required. Configured cascade steps in execution order with their latest run state. An empty array explicitly means no matching items.
- `steps[]` — object; required.
- `steps[].id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `steps[].position` — integer; required. Stable zero-based or configured ordering position returned by Semel. The value must be an integer.
- `steps[].kind` — string; required. Discriminator identifying the typed variant represented by this object.
- `steps[].status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `steps[].latestRun` — JSON value; required. Latest run for this cascade step; null means the step has not run. A null value explicitly means no current value is available.
- `steps[].latestRun (anyOf branch 1)` — object; required.
- `steps[].latestRun (anyOf branch 1).id` — string; required. Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it.
- `steps[].latestRun (anyOf branch 1).status` — string; required. Current typed status; the schema enum or union branch lists every allowed value.
- `steps[].latestRun (anyOf branch 1).createdAt` — string; required. RFC 3339 timestamp assigned by Semel when this record was created.
- `steps[].latestRun (anyOf branch 1).reviewSessionId` — string | null; required. Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available.
- `steps[].latestRun (anyOf branch 2)` — null; required.
- `latestRunId` — string | null; required. Most recent run identifier in the cascade; null means no run exists. A null value explicitly means no current value is available.
- `latestTerminalRunId` — string | null; required. Most recent terminal run identifier; null means none has settled. A null value explicitly means no current value is available.
- `evidenceWait` — object; optional. Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value.
- `evidenceWait.manifestId` — string; required. Evidence manifest identifier whose readiness is being reported.
- `evidenceWait.state` — constant "pending"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "pending".
- `evidenceWait.deadlineAt` — string; required. RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision.
- `evidenceWait.requiredRepositoryCount` — integer; required; minimum 0. Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer.
- `evidenceWait.unavailableRepositoryCount` — integer; required; minimum 0. Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer.
- `evidenceWait.statusPath` — string; required. Relative Semel API path for polling evidence readiness.
- `evidenceWait.decisionPath` — string; required. Relative Semel API path for the human evidence-wait decision.
- `evidenceWait.actions` — array; required. User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items.
- `evidenceWait.actions[]` — string; required.
- `blocked` — JSON value; required. Non-null spending or configuration condition currently blocking review progress. A null value explicitly means no current value is available.
- `blocked (anyOf branch 1)` — object; required.
- `blocked (anyOf branch 1).reason` — constant "cap_exceeded"; required. Typed or human-readable reason for the current outcome; omission means no reason is required. This branch always uses "cap_exceeded".
- `blocked (anyOf branch 1).hardCapCents` — integer; required. Workspace hard spending cap in integer US-dollar cents. The value must be an integer.
- `blocked (anyOf branch 1).spentThisMonthCents` — integer; required. Workspace spend in integer US-dollar cents for the current billing month. The value must be an integer.
- `blocked (anyOf branch 2)` — null; required.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"description": "Project identifier returned by project_create or project_list; the caller must have access to that project."
},
"phase": {
"type": "string",
"description": "Current cascade phase reported by Semel."
},
"inFlight": {
"type": "boolean",
"description": "Whether the cascade currently has an unsettled run."
},
"execution": {
"anyOf": [
{
"type": "string",
"enum": [
"hosted",
"local"
]
},
{
"type": "null"
}
],
"description": "Requested or observed execution lane: hosted Semel execution or local external execution. A null value explicitly means no current value is available. Allowed values: \"hosted\", \"local\"."
},
"awaitingLocalClaim": {
"type": "boolean",
"description": "Whether the next external run is waiting for a harness claim."
},
"steps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"position": {
"type": "integer",
"description": "Stable zero-based or configured ordering position returned by Semel. The value must be an integer."
},
"kind": {
"type": "string",
"description": "Discriminator identifying the typed variant represented by this object."
},
"status": {
"type": "string",
"description": "Current typed status; the schema enum or union branch lists every allowed value."
},
"latestRun": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Stable identifier for this record; copy it from the corresponding create, list, or read result rather than inventing it."
},
"status": {
"type": "string",
"description": "Current typed status; the schema enum or union branch lists every allowed value."
},
"createdAt": {
"type": "string",
"description": "RFC 3339 timestamp assigned by Semel when this record was created."
},
"reviewSessionId": {
"type": [
"string",
"null"
],
"description": "Review-session identifier returned by review_start, review_new_pass, or execution status. A null value explicitly means no current value is available."
}
},
"required": [
"id",
"status",
"createdAt",
"reviewSessionId"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Latest run for this cascade step; null means the step has not run. A null value explicitly means no current value is available."
}
},
"required": [
"id",
"position",
"kind",
"status",
"latestRun"
],
"additionalProperties": false
},
"description": "Configured cascade steps in execution order with their latest run state. An empty array explicitly means no matching items."
},
"latestRunId": {
"type": [
"string",
"null"
],
"description": "Most recent run identifier in the cascade; null means no run exists. A null value explicitly means no current value is available."
},
"latestTerminalRunId": {
"type": [
"string",
"null"
],
"description": "Most recent terminal run identifier; null means none has settled. A null value explicitly means no current value is available."
},
"evidenceWait": {
"type": "object",
"properties": {
"manifestId": {
"type": "string",
"description": "Evidence manifest identifier whose readiness is being reported."
},
"state": {
"type": "string",
"const": "pending",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"pending\"."
},
"deadlineAt": {
"type": "string",
"description": "RFC 3339 deadline for resolving the current evidence wait before the review requires a new status decision."
},
"requiredRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of repositories required before this evidence manifest can become ready. Minimum accepted length or value is 0. The value must be an integer."
},
"unavailableRepositoryCount": {
"type": "integer",
"minimum": 0,
"description": "Number of required repositories currently unavailable. Minimum accepted length or value is 0. The value must be an integer."
},
"statusPath": {
"type": "string",
"description": "Relative Semel API path for polling evidence readiness."
},
"decisionPath": {
"type": "string",
"description": "Relative Semel API path for the human evidence-wait decision."
},
"actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "User-facing actions available while evidence preparation is unresolved. An empty array explicitly means no matching items."
}
},
"required": [
"manifestId",
"state",
"deadlineAt",
"requiredRepositoryCount",
"unavailableRepositoryCount",
"statusPath",
"decisionPath",
"actions"
],
"additionalProperties": false,
"description": "Evidence-preparation state and the documented status/decision recovery paths. Omit the field when it does not apply; omission is distinct from an empty value."
},
"blocked": {
"anyOf": [
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"const": "cap_exceeded",
"description": "Typed or human-readable reason for the current outcome; omission means no reason is required. This branch always uses \"cap_exceeded\"."
},
"hardCapCents": {
"type": "integer",
"description": "Workspace hard spending cap in integer US-dollar cents. The value must be an integer."
},
"spentThisMonthCents": {
"type": "integer",
"description": "Workspace spend in integer US-dollar cents for the current billing month. The value must be an integer."
}
},
"required": [
"reason",
"hardCapCents",
"spentThisMonthCents"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Non-null spending or configuration condition currently blocking review progress. A null value explicitly means no current value is available."
}
},
"required": [
"projectId",
"phase",
"inFlight",
"execution",
"awaitingLocalClaim",
"steps",
"latestRunId",
"latestTerminalRunId",
"blocked"
],
"additionalProperties": false
}
```
**Example structured result (review-status)**
```json
{
"projectId": "prj_fixture_checkout",
"phase": "complete",
"inFlight": false,
"execution": "hosted",
"awaitingLocalClaim": false,
"steps": [],
"latestRunId": "run_fixture_review",
"latestTerminalRunId": "run_fixture_review",
"blocked": null
}
```
Bindings: latestRunId from structuredContent.latestRunId; anchorRunId from structuredContent.latestTerminalRunId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"projectId\":\"prj_fixture_checkout\",\"phase\":\"complete\",\"inFlight\":false,\"execution\":\"hosted\",\"awaitingLocalClaim\":false,\"steps\":[],\"latestRunId\":\"run_fixture_review\",\"latestTerminalRunId\":\"run_fixture_review\",\"blocked\":null}"
}
],
"structuredContent": {
"projectId": "prj_fixture_checkout",
"phase": "complete",
"inFlight": false,
"execution": "hosted",
"awaitingLocalClaim": false,
"steps": [],
"latestRunId": "run_fixture_review",
"latestTerminalRunId": "run_fixture_review",
"blocked": null
}
}
```
Next permitted action: Use latestTerminalRunId as the anchor for a later pass only when the user asks.
**Example requests**
- “what is the status of the review for this brief”
Errors: `PROJECT_ACCESS_DENIED`.
Related operations: `review_start`, `review_new_pass`, `review_execution_status`.
---
### skill_archive
Archive a skill for new authoring/configuration while retaining immutable history and existing execution pins.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `skills:read`, `skills:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `expectedRevisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skillId` — string; required; minimum length 1; maximum length 240. Immutable tenant reviewer-skill identifier returned by skill_list or skill_create.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"expectedRevisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"description": "Immutable tenant reviewer-skill identifier returned by skill_list or skill_create."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"expectedRevisionId",
"skillId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"skillId": "skl_recipe_checkout_copy",
"expectedRevisionId": "skr_recipe_checkout_copy_2",
"idempotencyKey": "recipe-skill-archive-unused-copy-v1"
}
```
**Binding template**
```json
{
"skillId": "{{copiedSkillId}}",
"expectedRevisionId": "{{restoredRevisionId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `operationId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skillId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `state` — constant "archived"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "archived".
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"operationId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"state": {
"type": "string",
"const": "archived",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"archived\"."
}
},
"required": [
"operationId",
"skillId",
"state"
],
"additionalProperties": false
}
```
**Example structured result (skill-archived)**
```json
{
"operationId": "example",
"skillId": "skl_recipe_checkout_copy",
"state": "archived"
}
```
Bindings: archivedSkillId from structuredContent.skillId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"operationId\":\"example\",\"skillId\":\"skl_recipe_checkout_copy\",\"state\":\"archived\"}"
}
],
"structuredContent": {
"operationId": "example",
"skillId": "skl_recipe_checkout_copy",
"state": "archived"
}
}
```
Next permitted action: Continue with project configuration independently of the archived unused copy.
**Example requests**
- “/semel archive this reviewer skill after confirming its current revision”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`, `CONFLICTING_IDEMPOTENCY_REPLAY`, `VALIDATION_FAILED`.
Related operations: `skill_get`, `skill_revision_list`.
---
### skill_compare
Compare the verified Markdown bytes of two explicitly selected immutable revisions of one authorized customer skill.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `skills:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `skillId` — string; required; minimum length 1; maximum length 240. Immutable tenant reviewer-skill identifier returned by skill_list or skill_create.
- `before` — string; required; minimum length 1; maximum length 240. Exact earlier revision selected as the before comparison side.
- `after` — string; required; minimum length 1; maximum length 240. Exact later revision selected as the after comparison side.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"description": "Immutable tenant reviewer-skill identifier returned by skill_list or skill_create."
},
"before": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"description": "Exact earlier revision selected as the before comparison side."
},
"after": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"description": "Exact later revision selected as the after comparison side."
}
},
"required": [
"skillId",
"before",
"after"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"skillId": "skl_recipe_checkout",
"before": "skr_recipe_checkout_1",
"after": "skr_recipe_checkout_2"
}
```
**Binding template**
```json
{
"skillId": "{{skillId}}",
"before": "{{draftRevisionId}}",
"after": "{{updatedRevisionId}}"
}
```
**Returns**
- `before` — object; required. Exact earlier reviewer-skill revision selected as the before side of this comparison.
- `before.revisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `before.markdown` — string; required. Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters.
- `after` — object; required. Exact later reviewer-skill revision selected as the after side of this comparison.
- `after.revisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `after.markdown` — string; required. Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"before": {
"type": "object",
"properties": {
"revisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"markdown": {
"type": "string",
"description": "Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters."
}
},
"required": [
"revisionId",
"markdown"
],
"additionalProperties": false,
"description": "Exact earlier reviewer-skill revision selected as the before side of this comparison."
},
"after": {
"type": "object",
"properties": {
"revisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"markdown": {
"type": "string",
"description": "Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters."
}
},
"required": [
"revisionId",
"markdown"
],
"additionalProperties": false,
"description": "Exact later reviewer-skill revision selected as the after side of this comparison."
}
},
"required": [
"before",
"after"
],
"additionalProperties": false
}
```
**Example structured result (skill-comparison)**
```json
{
"before": {
"revisionId": "skr_recipe_checkout_1",
"markdown": "example"
},
"after": {
"revisionId": "skr_recipe_checkout_2",
"markdown": "example"
}
}
```
Bindings: comparedAfterRevisionId from structuredContent.after.revisionId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"before\":{\"revisionId\":\"skr_recipe_checkout_1\",\"markdown\":\"example\"},\"after\":{\"revisionId\":\"skr_recipe_checkout_2\",\"markdown\":\"example\"}}"
}
],
"structuredContent": {
"before": {
"revisionId": "skr_recipe_checkout_1",
"markdown": "example"
},
"after": {
"revisionId": "skr_recipe_checkout_2",
"markdown": "example"
}
}
}
```
Next permitted action: Publish only the revision that was inspected and compared.
**Example requests**
- “/semel compare these two reviewer-skill revisions”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `skill_revision_list`, `skill_restore`.
---
### skill_copy
Copy an explicitly selected immutable published version. Personal-to-team copies require a pre-existing exact human-owner consent receipt; an agent cannot create one.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `skills:read`, `skills:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `sourceVersionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `audience` — "personal" | "team"; required. Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: "personal", "team".
- `name` — string; required; minimum length 1. Human-readable name displayed in Semel. Minimum accepted length or value is 1.
- `description` — string; required; minimum length 1. Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1.
- `skillId` — string; required; minimum length 1; maximum length 240. Immutable tenant reviewer-skill identifier returned by skill_list or skill_create.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"sourceVersionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"audience": {
"type": "string",
"enum": [
"personal",
"team"
],
"description": "Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: \"personal\", \"team\"."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable name displayed in Semel. Minimum accepted length or value is 1."
},
"description": {
"type": "string",
"minLength": 1,
"description": "Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1."
},
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"description": "Immutable tenant reviewer-skill identifier returned by skill_list or skill_create."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"sourceVersionId",
"audience",
"name",
"description",
"skillId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"skillId": "skl_recipe_checkout",
"sourceVersionId": "skv_recipe_checkout_1",
"audience": "personal",
"name": "Checkout reliability reviewer copy",
"description": "Editable copy of the exact published reviewer.",
"idempotencyKey": "recipe-skill-copy-v1"
}
```
**Binding template**
```json
{
"skillId": "{{skillId}}",
"sourceVersionId": "{{publishedSkillVersionId}}",
"audience": "personal",
"name": "Checkout reliability reviewer copy",
"description": "Editable copy of the exact published reviewer.",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `operationId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skillId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `draftRevisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `contentSha256` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `state` — constant "draft"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "draft".
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"operationId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"draftRevisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
"state": {
"type": "string",
"const": "draft",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"draft\"."
}
},
"required": [
"operationId",
"skillId",
"draftRevisionId",
"contentSha256",
"state"
],
"additionalProperties": false
}
```
**Example structured result (skill-draft)**
```json
{
"operationId": "example",
"skillId": "skl_recipe_checkout_copy",
"draftRevisionId": "skr_recipe_checkout_copy_1",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "draft"
}
```
Bindings: copiedSkillId from structuredContent.skillId; copiedRevisionId from structuredContent.draftRevisionId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"operationId\":\"example\",\"skillId\":\"skl_recipe_checkout_copy\",\"draftRevisionId\":\"skr_recipe_checkout_copy_1\",\"contentSha256\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"state\":\"draft\"}"
}
],
"structuredContent": {
"operationId": "example",
"skillId": "skl_recipe_checkout_copy",
"draftRevisionId": "skr_recipe_checkout_copy_1",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "draft"
}
}
```
Next permitted action: Restore only through a new immutable draft revision.
**Example requests**
- “/semel make a team draft copy of this exact published skill version”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`, `CONFLICTING_IDEMPOTENCY_REPLAY`, `VALIDATION_FAILED`.
Related operations: `skill_get`, `skill_publish`.
---
### skill_create
Create one bounded customer-authored skill draft. This does not publish, select, or run it.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `skills:read`, `skills:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `name` — string; required; minimum length 1. Human-readable name displayed in Semel. Minimum accepted length or value is 1.
- `description` — string; required; minimum length 1. Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1.
- `markdown` — string; required; minimum length 1. Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters. Minimum accepted length or value is 1.
- `audience` — "personal" | "team"; required. Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: "personal", "team".
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable name displayed in Semel. Minimum accepted length or value is 1."
},
"description": {
"type": "string",
"minLength": 1,
"description": "Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1."
},
"markdown": {
"type": "string",
"minLength": 1,
"description": "Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters. Minimum accepted length or value is 1."
},
"audience": {
"type": "string",
"enum": [
"personal",
"team"
],
"description": "Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: \"personal\", \"team\"."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"name",
"description",
"markdown",
"audience",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"name": "Checkout reliability reviewer",
"description": "Checks retry-safe checkout behavior.",
"markdown": "# Checkout reliability\n\nVerify idempotent payment behavior.",
"audience": "personal",
"idempotencyKey": "recipe-skill-create-v1"
}
```
**Binding template**
```json
{
"name": "Checkout reliability reviewer",
"description": "Checks retry-safe checkout behavior.",
"markdown": "# Checkout reliability\n\nVerify idempotent payment behavior.",
"audience": "personal",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `operationId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skillId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `draftRevisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `contentSha256` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `state` — constant "draft"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "draft".
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"operationId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"draftRevisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
"state": {
"type": "string",
"const": "draft",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"draft\"."
}
},
"required": [
"operationId",
"skillId",
"draftRevisionId",
"contentSha256",
"state"
],
"additionalProperties": false
}
```
**Example structured result (skill-draft)**
```json
{
"operationId": "example",
"skillId": "skl_recipe_checkout",
"draftRevisionId": "skr_recipe_checkout_1",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "draft"
}
```
Bindings: skillId from structuredContent.skillId; draftRevisionId from structuredContent.draftRevisionId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"operationId\":\"example\",\"skillId\":\"skl_recipe_checkout\",\"draftRevisionId\":\"skr_recipe_checkout_1\",\"contentSha256\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"state\":\"draft\"}"
}
],
"structuredContent": {
"operationId": "example",
"skillId": "skl_recipe_checkout",
"draftRevisionId": "skr_recipe_checkout_1",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "draft"
}
}
```
Next permitted action: Inspect the exact returned draft before editing or publishing it.
**Example requests**
- “/semel create a personal reviewer skill draft from this Markdown”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`, `CONFLICTING_IDEMPOTENCY_REPLAY`, `VALIDATION_FAILED`.
Related operations: `skill_update`, `skill_publish`.
---
### skill_get
Inspect one authorized skill and exact immutable version, including its verified Markdown source and current platform-framing preview.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `skills:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `skillId` — string; required; minimum length 1; maximum length 240. Immutable tenant reviewer-skill identifier returned by skill_list or skill_create.
- `versionId` — string; optional; minimum length 1; maximum length 240. Exact immutable reviewer-skill version to inspect; omit to inspect the authorized current head.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"description": "Immutable tenant reviewer-skill identifier returned by skill_list or skill_create."
},
"versionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"description": "Exact immutable reviewer-skill version to inspect; omit to inspect the authorized current head."
}
},
"required": [
"skillId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"skillId": "skl_recipe_checkout"
}
```
**Binding template**
```json
{
"skillId": "{{skillId}}"
}
```
**Returns**
- `skill` — JSON value; required. Exact immutable reviewer skill artifact pin used for this occurrence.
- `skill (anyOf branch 1)` — object; required.
- `skill (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `skill (anyOf branch 1).id` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skill (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `skill (anyOf branch 1).name` — string; required; minimum length 1. Human-readable name displayed in Semel. Minimum accepted length or value is 1.
- `skill (anyOf branch 1).description` — string; required; minimum length 1. Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1.
- `skill (anyOf branch 1).status` — constant "published"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "published".
- `skill (anyOf branch 1).versionId` — JSON value; 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 240, inclusive.
- `skill (anyOf branch 1).versionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skill (anyOf branch 1).versionId (anyOf branch 2)` — null; required.
- `skill (anyOf branch 1).versionLabel` — string | null; required. Display label for the immutable built-in reviewer-skill publication; null means no publication is available. A null value explicitly means no current value is available.
- `skill (anyOf branch 1).contentSha256` — JSON value; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `skill (anyOf branch 1).contentSha256 (anyOf branch 1)` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `skill (anyOf branch 1).contentSha256 (anyOf branch 2)` — null; required.
- `skill (anyOf branch 1).updatedAt` — null; required. RFC 3339 timestamp when this record was last updated.
- `skill (anyOf branch 1).canEdit` — constant false; required. Whether the current authenticated principal may edit this reviewer skill. This branch always uses false.
- `skill (anyOf branch 1).canCopy` — boolean; required. Whether the current authenticated principal may create a customer-owned copy of this reviewer skill version.
- `skill (anyOf branch 2)` — object; required.
- `skill (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `skill (anyOf branch 2).id` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skill (anyOf branch 2).name` — string; required; minimum length 1. Human-readable name displayed in Semel. Minimum accepted length or value is 1.
- `skill (anyOf branch 2).description` — string; required; minimum length 1. Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1.
- `skill (anyOf branch 2).audience` — "personal" | "team"; required. Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: "personal", "team".
- `skill (anyOf branch 2).ownerUserId` — JSON value; 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 240, inclusive.
- `skill (anyOf branch 2).ownerUserId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skill (anyOf branch 2).ownerUserId (anyOf branch 2)` — null; required.
- `skill (anyOf branch 2).status` — "draft" | "published" | "archived"; required. Current typed status; the schema enum or union branch lists every allowed value. Allowed values: "draft", "published", "archived".
- `skill (anyOf branch 2).draftHeadRevisionId` — JSON value; 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 240, inclusive.
- `skill (anyOf branch 2).draftHeadRevisionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skill (anyOf branch 2).draftHeadRevisionId (anyOf branch 2)` — null; required.
- `skill (anyOf branch 2).publishedHeadVersionId` — JSON value; 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 240, inclusive.
- `skill (anyOf branch 2).publishedHeadVersionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skill (anyOf branch 2).publishedHeadVersionId (anyOf branch 2)` — null; required.
- `skill (anyOf branch 2).publishedVersionNumber` — JSON value; required. Positive monotonic number of the current published reviewer-skill version; null means it has never been published. A null value explicitly means no current value is available. Minimum accepted length or value is 0. The value must be an integer.
- `skill (anyOf branch 2).publishedVersionNumber (anyOf branch 1)` — integer; required.
- `skill (anyOf branch 2).publishedVersionNumber (anyOf branch 2)` — null; required.
- `skill (anyOf branch 2).updatedAt` — string; required; format date-time. RFC 3339 timestamp assigned by Semel when this record was created. Use an RFC 3339 date-time string.
- `skill (anyOf branch 2).canEdit` — boolean; required. Whether the current authenticated principal may edit this reviewer skill.
- `skill (anyOf branch 2).canCopy` — boolean; required. Whether the current authenticated principal may create a customer-owned copy of this reviewer skill version.
- `source` — object; required. Optional human-readable provenance for the decision.
- `source.markdown` — string; required. Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters.
- `source.byteLength` — integer; required. Exact UTF-8 byte length of the immutable reviewer-skill or framing source. Minimum accepted length or value is 0. The value must be an integer.
- `source.contentSha256` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `source.revisionId` — JSON value; 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 240, inclusive.
- `source.revisionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `source.revisionId (anyOf branch 2)` — null; required.
- `source.versionId` — JSON value; 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 240, inclusive.
- `source.versionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `source.versionId (anyOf branch 2)` — null; required.
- `source.versionNumber` — JSON value; required. Positive monotonic publication number assigned to this immutable reviewer-skill version. A null value explicitly means no current value is available. Minimum accepted length or value is 0. The value must be an integer.
- `source.versionNumber (anyOf branch 1)` — integer; required.
- `source.versionNumber (anyOf branch 2)` — null; required.
- `copyProvenance` — JSON value; optional; default null. Server-recorded immutable lineage for a copied reviewer skill; null means no copy lineage is recorded, and source identifiers do not grant access to the source skill. Omission uses the schema default null. A null value explicitly means no current value is available.
- `copyProvenance (anyOf branch 1)` — JSON value; optional.
- `copyProvenance (anyOf branch 1) (anyOf branch 1)` — object; optional.
- `copyProvenance (anyOf branch 1) (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `copyProvenance (anyOf branch 1) (anyOf branch 1).role` — string; required; minimum length 1; maximum length 120. Pinned reviewer or artifact role used by the execution bundle. Accepted length or value is 1 through 120, inclusive.
- `copyProvenance (anyOf branch 1) (anyOf branch 1).version` — string; required; minimum length 1; maximum length 120. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 120, inclusive.
- `copyProvenance (anyOf branch 1) (anyOf branch 1).contentSha256` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `copyProvenance (anyOf branch 1) (anyOf branch 2)` — object; optional.
- `copyProvenance (anyOf branch 1) (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `copyProvenance (anyOf branch 1) (anyOf branch 2).sourceSkillId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `copyProvenance (anyOf branch 1) (anyOf branch 2).sourceVersionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `copyProvenance (anyOf branch 1) (anyOf branch 2).contentSha256` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `copyProvenance (anyOf branch 2)` — null; optional.
- `platformFraming` — object; required. Authenticated shared platform framing composed with the selected reviewer skill at execution admission.
- `platformFraming.title` — constant "Platform framing"; required. Human-readable title displayed in Semel. This branch always uses "Platform framing".
- `platformFraming.description` — string; required; minimum length 1; maximum length 2000. Human-readable explanatory text; null or omission means no description was supplied. Accepted length or value is 1 through 2000, inclusive.
- `platformFraming.includedAtRuntime` — constant true; required. Whether this platform framing is included when the reviewer skill is composed for execution. This branch always uses true.
- `platformFraming.compositionStatus` — constant "current_preview"; required. Describes whether the returned framing is a current preview or an immutable admitted execution snapshot. This branch always uses "current_preview".
- `platformFraming.executionUsesAdmittedSnapshot` — constant true; required. Whether executions use a separately admitted immutable snapshot instead of trusting this current preview. This branch always uses true.
- `platformFraming.source` — JSON value; required. Optional human-readable provenance for the decision. A null value explicitly means no current value is available.
- `platformFraming.source (anyOf branch 1)` — object; required.
- `platformFraming.source (anyOf branch 1).role` — constant "reviewer-protocol-framing"; required. Pinned reviewer or artifact role used by the execution bundle. This branch always uses "reviewer-protocol-framing".
- `platformFraming.source (anyOf branch 1).version` — string; required; minimum length 1; maximum length 120. Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 120, inclusive.
- `platformFraming.source (anyOf branch 1).markdown` — string; required. Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters.
- `platformFraming.source (anyOf branch 1).byteLength` — integer; required. Exact UTF-8 byte length of the immutable reviewer-skill or framing source. Minimum accepted length or value is 0. The value must be an integer.
- `platformFraming.source (anyOf branch 1).contentSha256` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `platformFraming.source (anyOf branch 1).framingHash` — JSON value; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `platformFraming.source (anyOf branch 1).framingHash (anyOf branch 1)` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `platformFraming.source (anyOf branch 1).framingHash (anyOf branch 2)` — null; required.
- `platformFraming.source (anyOf branch 2)` — null; required.
- `newVersionAvailable` — boolean; required. Whether a newer immutable reviewer-skill version exists than the exact version currently being inspected.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"skill": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable name displayed in Semel. Minimum accepted length or value is 1."
},
"description": {
"type": "string",
"minLength": 1,
"description": "Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1."
},
"status": {
"type": "string",
"const": "published",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"published\"."
},
"versionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"versionLabel": {
"type": [
"string",
"null"
],
"description": "Display label for the immutable built-in reviewer-skill publication; null means no publication is available. A null value explicitly means no current value is available."
},
"contentSha256": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
{
"type": "null"
}
],
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
"updatedAt": {
"type": "null",
"description": "RFC 3339 timestamp when this record was last updated."
},
"canEdit": {
"type": "boolean",
"const": false,
"description": "Whether the current authenticated principal may edit this reviewer skill. This branch always uses false."
},
"canCopy": {
"type": "boolean",
"description": "Whether the current authenticated principal may create a customer-owned copy of this reviewer skill version."
}
},
"required": [
"kind",
"id",
"role",
"name",
"description",
"status",
"versionId",
"versionLabel",
"contentSha256",
"updatedAt",
"canEdit",
"canCopy"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable name displayed in Semel. Minimum accepted length or value is 1."
},
"description": {
"type": "string",
"minLength": 1,
"description": "Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1."
},
"audience": {
"type": "string",
"enum": [
"personal",
"team"
],
"description": "Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: \"personal\", \"team\"."
},
"ownerUserId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"status": {
"type": "string",
"enum": [
"draft",
"published",
"archived"
],
"description": "Current typed status; the schema enum or union branch lists every allowed value. Allowed values: \"draft\", \"published\", \"archived\"."
},
"draftHeadRevisionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"publishedHeadVersionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"publishedVersionNumber": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"description": "Positive monotonic number of the current published reviewer-skill version; null means it has never been published. A null value explicitly means no current value is available. Minimum accepted length or value is 0. The value must be an integer."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp assigned by Semel when this record was created. Use an RFC 3339 date-time string."
},
"canEdit": {
"type": "boolean",
"description": "Whether the current authenticated principal may edit this reviewer skill."
},
"canCopy": {
"type": "boolean",
"description": "Whether the current authenticated principal may create a customer-owned copy of this reviewer skill version."
}
},
"required": [
"kind",
"id",
"name",
"description",
"audience",
"ownerUserId",
"status",
"draftHeadRevisionId",
"publishedHeadVersionId",
"publishedVersionNumber",
"updatedAt",
"canEdit",
"canCopy"
],
"additionalProperties": false
}
],
"description": "Exact immutable reviewer skill artifact pin used for this occurrence."
},
"source": {
"type": "object",
"properties": {
"markdown": {
"type": "string",
"description": "Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters."
},
"byteLength": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Exact UTF-8 byte length of the immutable reviewer-skill or framing source. Minimum accepted length or value is 0. The value must be an integer."
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
"revisionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"versionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"versionNumber": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"description": "Positive monotonic publication number assigned to this immutable reviewer-skill version. A null value explicitly means no current value is available. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"markdown",
"byteLength",
"contentSha256",
"revisionId",
"versionId",
"versionNumber"
],
"additionalProperties": false,
"description": "Optional human-readable provenance for the decision."
},
"copyProvenance": {
"anyOf": [
{
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"role": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "Pinned reviewer or artifact role used by the execution bundle. Accepted length or value is 1 through 120, inclusive."
},
"version": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 120, inclusive."
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
}
},
"required": [
"kind",
"role",
"version",
"contentSha256"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"sourceSkillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"sourceVersionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
}
},
"required": [
"kind",
"sourceSkillId",
"sourceVersionId",
"contentSha256"
],
"additionalProperties": false
}
]
},
{
"type": "null"
}
],
"default": null,
"description": "Server-recorded immutable lineage for a copied reviewer skill; null means no copy lineage is recorded, and source identifiers do not grant access to the source skill. Omission uses the schema default null. A null value explicitly means no current value is available."
},
"platformFraming": {
"type": "object",
"properties": {
"title": {
"type": "string",
"const": "Platform framing",
"description": "Human-readable title displayed in Semel. This branch always uses \"Platform framing\"."
},
"description": {
"type": "string",
"minLength": 1,
"maxLength": 2000,
"description": "Human-readable explanatory text; null or omission means no description was supplied. Accepted length or value is 1 through 2000, inclusive."
},
"includedAtRuntime": {
"type": "boolean",
"const": true,
"description": "Whether this platform framing is included when the reviewer skill is composed for execution. This branch always uses true."
},
"compositionStatus": {
"type": "string",
"const": "current_preview",
"description": "Describes whether the returned framing is a current preview or an immutable admitted execution snapshot. This branch always uses \"current_preview\"."
},
"executionUsesAdmittedSnapshot": {
"type": "boolean",
"const": true,
"description": "Whether executions use a separately admitted immutable snapshot instead of trusting this current preview. This branch always uses true."
},
"source": {
"anyOf": [
{
"type": "object",
"properties": {
"role": {
"type": "string",
"const": "reviewer-protocol-framing",
"description": "Pinned reviewer or artifact role used by the execution bundle. This branch always uses \"reviewer-protocol-framing\"."
},
"version": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "Positive version number of a skill artifact or nonnegative snapshot version of a knowledge collection. Accepted length or value is 1 through 120, inclusive."
},
"markdown": {
"type": "string",
"description": "Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters."
},
"byteLength": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Exact UTF-8 byte length of the immutable reviewer-skill or framing source. Minimum accepted length or value is 0. The value must be an integer."
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
"framingHash": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
{
"type": "null"
}
],
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
}
},
"required": [
"role",
"version",
"markdown",
"byteLength",
"contentSha256",
"framingHash"
],
"additionalProperties": false
},
{
"type": "null"
}
],
"description": "Optional human-readable provenance for the decision. A null value explicitly means no current value is available."
}
},
"required": [
"title",
"description",
"includedAtRuntime",
"compositionStatus",
"executionUsesAdmittedSnapshot",
"source"
],
"additionalProperties": false,
"description": "Authenticated shared platform framing composed with the selected reviewer skill at execution admission."
},
"newVersionAvailable": {
"type": "boolean",
"description": "Whether a newer immutable reviewer-skill version exists than the exact version currently being inspected."
}
},
"required": [
"skill",
"source",
"platformFraming",
"newVersionAvailable"
],
"additionalProperties": false
}
```
**Example structured result (skill-detail)**
```json
{
"skill": {
"kind": "builtin",
"id": "record_fixture_01",
"role": "product",
"name": "Checkout reliability",
"description": "example",
"status": "published",
"versionId": "example",
"versionLabel": "example",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"updatedAt": null,
"canEdit": false,
"canCopy": false
},
"source": {
"markdown": "example",
"byteLength": 1,
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"revisionId": "skr_recipe_checkout_1",
"versionId": "example",
"versionNumber": 1
},
"platformFraming": {
"title": "Platform framing",
"description": "example",
"includedAtRuntime": true,
"compositionStatus": "current_preview",
"executionUsesAdmittedSnapshot": true,
"source": {
"role": "reviewer-protocol-framing",
"version": "example",
"markdown": "example",
"byteLength": 1,
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"framingHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
},
"newVersionAvailable": false
}
```
Bindings: inspectedRevisionId from structuredContent.source.revisionId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"skill\":{\"kind\":\"builtin\",\"id\":\"record_fixture_01\",\"role\":\"product\",\"name\":\"Checkout reliability\",\"description\":\"example\",\"status\":\"published\",\"versionId\":\"example\",\"versionLabel\":\"example\",\"contentSha256\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"updatedAt\":null,\"canEdit\":false,\"canCopy\":false},\"source\":{\"markdown\":\"example\",\"byteLength\":1,\"contentSha256\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"revisionId\":\"skr_recipe_checkout_1\",\"versionId\":\"example\",\"versionNumber\":1},\"platformFraming\":{\"title\":\"Platform framing\",\"description\":\"example\",\"includedAtRuntime\":true,\"compositionStatus\":\"current_preview\",\"executionUsesAdmittedSnapshot\":true,\"source\":{\"role\":\"reviewer-protocol-framing\",\"version\":\"example\",\"markdown\":\"example\",\"byteLength\":1,\"contentSha256\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"framingHash\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"}},\"newVersionAvailable\":false}"
}
],
"structuredContent": {
"skill": {
"kind": "builtin",
"id": "record_fixture_01",
"role": "product",
"name": "Checkout reliability",
"description": "example",
"status": "published",
"versionId": "example",
"versionLabel": "example",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"updatedAt": null,
"canEdit": false,
"canCopy": false
},
"source": {
"markdown": "example",
"byteLength": 1,
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"revisionId": "skr_recipe_checkout_1",
"versionId": "example",
"versionNumber": 1
},
"platformFraming": {
"title": "Platform framing",
"description": "example",
"includedAtRuntime": true,
"compositionStatus": "current_preview",
"executionUsesAdmittedSnapshot": true,
"source": {
"role": "reviewer-protocol-framing",
"version": "example",
"markdown": "example",
"byteLength": 1,
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"framingHash": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}
},
"newVersionAvailable": false
}
}
```
Next permitted action: Use the returned revision as the optimistic edit base.
**Example requests**
- “/semel inspect the exact version of the security reviewer skill”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `skill_list`, `skill_revision_list`, `skill_copy`.
---
### skill_list
List the complete workspace reviewer-skill library as bounded metadata; source bytes are returned only by skill_get or skill_compare.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `skills:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `q` — string; optional; maximum length 200. Optional case-insensitive search text used to filter reviewer skills by name or description. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200.
- `source` — "all" | "builtin" | "team" | "mine"; optional; default "all". Optional human-readable provenance for the decision. Omission uses the schema default "all". Allowed values: "all", "builtin", "team", "mine".
- `status` — "all" | "draft" | "published" | "archived"; optional; default "all". Current typed status; the schema enum or union branch lists every allowed value. Omission uses the schema default "all". Allowed values: "all", "draft", "published", "archived".
- `cursor` — string; optional; maximum length 2000. 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. Maximum accepted length or value is 2000.
- `limit` — integer; optional; default 25; minimum 1; maximum 50. Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omission uses the schema default 25. Accepted length or value is 1 through 50, inclusive. The value must be an integer.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"q": {
"type": "string",
"maxLength": 200,
"description": "Optional case-insensitive search text used to filter reviewer skills by name or description. Omit the field when it does not apply; omission is distinct from an empty value. Maximum accepted length or value is 200."
},
"source": {
"type": "string",
"enum": [
"all",
"builtin",
"team",
"mine"
],
"default": "all",
"description": "Optional human-readable provenance for the decision. Omission uses the schema default \"all\". Allowed values: \"all\", \"builtin\", \"team\", \"mine\"."
},
"status": {
"type": "string",
"enum": [
"all",
"draft",
"published",
"archived"
],
"default": "all",
"description": "Current typed status; the schema enum or union branch lists every allowed value. Omission uses the schema default \"all\". Allowed values: \"all\", \"draft\", \"published\", \"archived\"."
},
"cursor": {
"type": "string",
"maxLength": 2000,
"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. Maximum accepted length or value is 2000."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 25,
"description": "Maximum records requested for this page; omission uses the server default and the schema enforces the ceiling. Omission uses the schema default 25. Accepted length or value is 1 through 50, inclusive. The value must be an integer."
}
},
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"source": "all",
"status": "all",
"limit": 25
}
```
**Binding template**
```json
{
"source": "all",
"status": "all",
"limit": 25
}
```
**Returns**
- `skills` — array; required; maximum items 50. 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.
- `skills[]` — JSON value; required.
- `skills[] (anyOf branch 1)` — object; required.
- `skills[] (anyOf branch 1).kind` — constant "builtin"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "builtin".
- `skills[] (anyOf branch 1).id` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skills[] (anyOf branch 1).role` — "product" | "engineering" | "design" | "security" | "test"; required. Pinned reviewer or artifact role used by the execution bundle. Allowed values: "product", "engineering", "design", "security", "test".
- `skills[] (anyOf branch 1).name` — string; required; minimum length 1. Human-readable name displayed in Semel. Minimum accepted length or value is 1.
- `skills[] (anyOf branch 1).description` — string; required; minimum length 1. Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1.
- `skills[] (anyOf branch 1).status` — constant "published"; required. Current typed status; the schema enum or union branch lists every allowed value. This branch always uses "published".
- `skills[] (anyOf branch 1).versionId` — JSON value; 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 240, inclusive.
- `skills[] (anyOf branch 1).versionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skills[] (anyOf branch 1).versionId (anyOf branch 2)` — null; required.
- `skills[] (anyOf branch 1).versionLabel` — string | null; required. Display label for the immutable built-in reviewer-skill publication; null means no publication is available. A null value explicitly means no current value is available.
- `skills[] (anyOf branch 1).contentSha256` — JSON value; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `skills[] (anyOf branch 1).contentSha256 (anyOf branch 1)` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `skills[] (anyOf branch 1).contentSha256 (anyOf branch 2)` — null; required.
- `skills[] (anyOf branch 1).updatedAt` — null; required. RFC 3339 timestamp when this record was last updated.
- `skills[] (anyOf branch 1).canEdit` — constant false; required. Whether the current authenticated principal may edit this reviewer skill. This branch always uses false.
- `skills[] (anyOf branch 1).canCopy` — boolean; required. Whether the current authenticated principal may create a customer-owned copy of this reviewer skill version.
- `skills[] (anyOf branch 2)` — object; required.
- `skills[] (anyOf branch 2).kind` — constant "custom"; required. Discriminator identifying the typed variant represented by this object. This branch always uses "custom".
- `skills[] (anyOf branch 2).id` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skills[] (anyOf branch 2).name` — string; required; minimum length 1. Human-readable name displayed in Semel. Minimum accepted length or value is 1.
- `skills[] (anyOf branch 2).description` — string; required; minimum length 1. Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1.
- `skills[] (anyOf branch 2).audience` — "personal" | "team"; required. Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: "personal", "team".
- `skills[] (anyOf branch 2).ownerUserId` — JSON value; 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 240, inclusive.
- `skills[] (anyOf branch 2).ownerUserId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skills[] (anyOf branch 2).ownerUserId (anyOf branch 2)` — null; required.
- `skills[] (anyOf branch 2).status` — "draft" | "published" | "archived"; required. Current typed status; the schema enum or union branch lists every allowed value. Allowed values: "draft", "published", "archived".
- `skills[] (anyOf branch 2).draftHeadRevisionId` — JSON value; 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 240, inclusive.
- `skills[] (anyOf branch 2).draftHeadRevisionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skills[] (anyOf branch 2).draftHeadRevisionId (anyOf branch 2)` — null; required.
- `skills[] (anyOf branch 2).publishedHeadVersionId` — JSON value; 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 240, inclusive.
- `skills[] (anyOf branch 2).publishedHeadVersionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skills[] (anyOf branch 2).publishedHeadVersionId (anyOf branch 2)` — null; required.
- `skills[] (anyOf branch 2).publishedVersionNumber` — JSON value; required. Positive monotonic number of the current published reviewer-skill version; null means it has never been published. A null value explicitly means no current value is available. Minimum accepted length or value is 0. The value must be an integer.
- `skills[] (anyOf branch 2).publishedVersionNumber (anyOf branch 1)` — integer; required.
- `skills[] (anyOf branch 2).publishedVersionNumber (anyOf branch 2)` — null; required.
- `skills[] (anyOf branch 2).updatedAt` — string; required; format date-time. RFC 3339 timestamp assigned by Semel when this record was created. Use an RFC 3339 date-time string.
- `skills[] (anyOf branch 2).canEdit` — boolean; required. Whether the current authenticated principal may edit this reviewer skill.
- `skills[] (anyOf branch 2).canCopy` — boolean; required. Whether the current authenticated principal may create a customer-owned copy of this reviewer skill version.
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
- `authoringEnabled` — boolean; required. Whether customer reviewer-skill authoring is enabled for this workspace deployment.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"skills": {
"type": "array",
"items": {
"anyOf": [
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "builtin",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"builtin\"."
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"role": {
"type": "string",
"enum": [
"product",
"engineering",
"design",
"security",
"test"
],
"description": "Pinned reviewer or artifact role used by the execution bundle. Allowed values: \"product\", \"engineering\", \"design\", \"security\", \"test\"."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable name displayed in Semel. Minimum accepted length or value is 1."
},
"description": {
"type": "string",
"minLength": 1,
"description": "Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1."
},
"status": {
"type": "string",
"const": "published",
"description": "Current typed status; the schema enum or union branch lists every allowed value. This branch always uses \"published\"."
},
"versionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"versionLabel": {
"type": [
"string",
"null"
],
"description": "Display label for the immutable built-in reviewer-skill publication; null means no publication is available. A null value explicitly means no current value is available."
},
"contentSha256": {
"anyOf": [
{
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
{
"type": "null"
}
],
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
"updatedAt": {
"type": "null",
"description": "RFC 3339 timestamp when this record was last updated."
},
"canEdit": {
"type": "boolean",
"const": false,
"description": "Whether the current authenticated principal may edit this reviewer skill. This branch always uses false."
},
"canCopy": {
"type": "boolean",
"description": "Whether the current authenticated principal may create a customer-owned copy of this reviewer skill version."
}
},
"required": [
"kind",
"id",
"role",
"name",
"description",
"status",
"versionId",
"versionLabel",
"contentSha256",
"updatedAt",
"canEdit",
"canCopy"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"const": "custom",
"description": "Discriminator identifying the typed variant represented by this object. This branch always uses \"custom\"."
},
"id": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable name displayed in Semel. Minimum accepted length or value is 1."
},
"description": {
"type": "string",
"minLength": 1,
"description": "Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1."
},
"audience": {
"type": "string",
"enum": [
"personal",
"team"
],
"description": "Visibility of the customer reviewer skill: personal to its accountable owner or shared with workspace members. Allowed values: \"personal\", \"team\"."
},
"ownerUserId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"status": {
"type": "string",
"enum": [
"draft",
"published",
"archived"
],
"description": "Current typed status; the schema enum or union branch lists every allowed value. Allowed values: \"draft\", \"published\", \"archived\"."
},
"draftHeadRevisionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"publishedHeadVersionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"publishedVersionNumber": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"description": "Positive monotonic number of the current published reviewer-skill version; null means it has never been published. A null value explicitly means no current value is available. Minimum accepted length or value is 0. The value must be an integer."
},
"updatedAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp assigned by Semel when this record was created. Use an RFC 3339 date-time string."
},
"canEdit": {
"type": "boolean",
"description": "Whether the current authenticated principal may edit this reviewer skill."
},
"canCopy": {
"type": "boolean",
"description": "Whether the current authenticated principal may create a customer-owned copy of this reviewer skill version."
}
},
"required": [
"kind",
"id",
"name",
"description",
"audience",
"ownerUserId",
"status",
"draftHeadRevisionId",
"publishedHeadVersionId",
"publishedVersionNumber",
"updatedAt",
"canEdit",
"canCopy"
],
"additionalProperties": false
}
]
},
"maxItems": 50,
"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."
},
"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."
},
"authoringEnabled": {
"type": "boolean",
"description": "Whether customer reviewer-skill authoring is enabled for this workspace deployment."
}
},
"required": [
"skills",
"nextCursor",
"authoringEnabled"
],
"additionalProperties": false
}
```
**Example structured result (skill-list)**
```json
{
"skills": [
{
"kind": "builtin",
"id": "skl_recipe_catalog",
"role": "product",
"name": "Checkout reliability",
"description": "example",
"status": "published",
"versionId": "example",
"versionLabel": "example",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"updatedAt": null,
"canEdit": false,
"canCopy": false
}
],
"nextCursor": null,
"authoringEnabled": false
}
```
Bindings: catalogSkillId from structuredContent.skills[0].id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"skills\":[{\"kind\":\"builtin\",\"id\":\"skl_recipe_catalog\",\"role\":\"product\",\"name\":\"Checkout reliability\",\"description\":\"example\",\"status\":\"published\",\"versionId\":\"example\",\"versionLabel\":\"example\",\"contentSha256\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"updatedAt\":null,\"canEdit\":false,\"canCopy\":false}],\"nextCursor\":null,\"authoringEnabled\":false}"
}
],
"structuredContent": {
"skills": [
{
"kind": "builtin",
"id": "skl_recipe_catalog",
"role": "product",
"name": "Checkout reliability",
"description": "example",
"status": "published",
"versionId": "example",
"versionLabel": "example",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"updatedAt": null,
"canEdit": false,
"canCopy": false
}
],
"nextCursor": null,
"authoringEnabled": false
}
}
```
Next permitted action: Create a new draft only when no existing skill is the intended editable source.
**Example requests**
- “/semel list the team reviewer skills”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `skill_get`, `skill_revision_list`.
---
### skill_publish
Publish exactly expectedRevisionId as a new immutable version. Publishing does not run a review or select the version anywhere.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `skills:read`, `skills:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `expectedRevisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skillId` — string; required; minimum length 1; maximum length 240. Immutable tenant reviewer-skill identifier returned by skill_list or skill_create.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"expectedRevisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"description": "Immutable tenant reviewer-skill identifier returned by skill_list or skill_create."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"expectedRevisionId",
"skillId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"skillId": "skl_recipe_checkout",
"expectedRevisionId": "skr_recipe_checkout_2",
"idempotencyKey": "recipe-skill-publish-v1"
}
```
**Binding template**
```json
{
"skillId": "{{skillId}}",
"expectedRevisionId": "{{updatedRevisionId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `operationId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skillId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `versionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `revisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `versionNumber` — integer; required. Positive monotonic publication number assigned to this immutable reviewer-skill version. Minimum accepted length or value is 0. The value must be an integer.
- `contentSha256` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `state` — constant "published"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "published".
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"operationId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"versionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"revisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"versionNumber": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Positive monotonic publication number assigned to this immutable reviewer-skill version. Minimum accepted length or value is 0. The value must be an integer."
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
"state": {
"type": "string",
"const": "published",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"published\"."
}
},
"required": [
"operationId",
"skillId",
"versionId",
"revisionId",
"versionNumber",
"contentSha256",
"state"
],
"additionalProperties": false
}
```
**Example structured result (skill-published)**
```json
{
"operationId": "example",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1",
"revisionId": "skr_recipe_checkout_2",
"versionNumber": 1,
"contentSha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
"state": "published"
}
```
Bindings: publishedSkillVersionId from structuredContent.versionId; publishedSkillHash from structuredContent.contentSha256.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"operationId\":\"example\",\"skillId\":\"skl_recipe_checkout\",\"versionId\":\"skv_recipe_checkout_1\",\"revisionId\":\"skr_recipe_checkout_2\",\"versionNumber\":1,\"contentSha256\":\"dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd\",\"state\":\"published\"}"
}
],
"structuredContent": {
"operationId": "example",
"skillId": "skl_recipe_checkout",
"versionId": "skv_recipe_checkout_1",
"revisionId": "skr_recipe_checkout_2",
"versionNumber": 1,
"contentSha256": "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
"state": "published"
}
}
```
Next permitted action: Use the exact immutable publication in copies and cascade configuration.
**Example requests**
- “/semel publish the reviewer-skill revision I just inspected”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`, `CONFLICTING_IDEMPOTENCY_REPLAY`, `VALIDATION_FAILED`.
Related operations: `skill_get`, `skill_revision_list`.
---
### skill_restore
Create a new draft from an exact historical revision while preserving all existing revisions, publications, and reviews.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `skills:read`, `skills:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `revisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `expectedRevisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skillId` — string; required; minimum length 1; maximum length 240. Immutable tenant reviewer-skill identifier returned by skill_list or skill_create.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"revisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"expectedRevisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"description": "Immutable tenant reviewer-skill identifier returned by skill_list or skill_create."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"revisionId",
"expectedRevisionId",
"skillId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"skillId": "skl_recipe_checkout_copy",
"revisionId": "skr_recipe_checkout_copy_1",
"expectedRevisionId": "skr_recipe_checkout_copy_1",
"idempotencyKey": "recipe-skill-restore-v1"
}
```
**Binding template**
```json
{
"skillId": "{{copiedSkillId}}",
"revisionId": "{{copiedRevisionId}}",
"expectedRevisionId": "{{copiedRevisionId}}",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `operationId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skillId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `draftRevisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `contentSha256` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `state` — constant "draft"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "draft".
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"operationId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"draftRevisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
"state": {
"type": "string",
"const": "draft",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"draft\"."
}
},
"required": [
"operationId",
"skillId",
"draftRevisionId",
"contentSha256",
"state"
],
"additionalProperties": false
}
```
**Example structured result (skill-draft)**
```json
{
"operationId": "example",
"skillId": "skl_recipe_checkout_copy",
"draftRevisionId": "skr_recipe_checkout_copy_2",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "draft"
}
```
Bindings: restoredRevisionId from structuredContent.draftRevisionId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"operationId\":\"example\",\"skillId\":\"skl_recipe_checkout_copy\",\"draftRevisionId\":\"skr_recipe_checkout_copy_2\",\"contentSha256\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"state\":\"draft\"}"
}
],
"structuredContent": {
"operationId": "example",
"skillId": "skl_recipe_checkout_copy",
"draftRevisionId": "skr_recipe_checkout_copy_2",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "draft"
}
}
```
Next permitted action: Save the exact published original as a cascade preset.
**Example requests**
- “/semel restore this old skill revision as a new draft”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`, `CONFLICTING_IDEMPOTENCY_REPLAY`, `VALIDATION_FAILED`.
Related operations: `skill_revision_list`, `skill_compare`, `skill_publish`.
---
### skill_revision_list
List bounded immutable revision metadata for one customer skill without returning Markdown bodies.
- Mode: read
- Risk: low
- Scopes: `brief:read`, `skills:read`
- Confirmation: none
- Idempotency: none
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `skillId` — string; required; minimum length 1; maximum length 240. Immutable tenant reviewer-skill identifier returned by skill_list or skill_create.
- `cursor` — string; optional; maximum length 2000. Opaque cursor returned by the preceding skill_revision_list page.
- `limit` — integer; optional; default 25; minimum 1; maximum 50. Maximum revision metadata records to return; omission uses 25.
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"description": "Immutable tenant reviewer-skill identifier returned by skill_list or skill_create."
},
"cursor": {
"type": "string",
"maxLength": 2000,
"description": "Opaque cursor returned by the preceding skill_revision_list page."
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50,
"default": 25,
"description": "Maximum revision metadata records to return; omission uses 25."
}
},
"required": [
"skillId"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"skillId": "skl_recipe_checkout",
"limit": 25
}
```
**Binding template**
```json
{
"skillId": "{{skillId}}",
"limit": 25
}
```
**Returns**
- `revisions` — array; required; maximum items 50. Immutable reviewer-skill revision metadata in this page; an empty array means no authorized revisions matched. An empty array explicitly means no matching items.
- `revisions[]` — object; required.
- `revisions[].id` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `revisions[].sequence` — integer; required. Positive monotonic position of this immutable reviewer-skill revision in its history. Minimum accepted length or value is 0. The value must be an integer.
- `revisions[].parentRevisionId` — JSON value; 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 240, inclusive.
- `revisions[].parentRevisionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `revisions[].parentRevisionId (anyOf branch 2)` — null; required.
- `revisions[].restoredFromRevisionId` — JSON value; 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 240, inclusive.
- `revisions[].restoredFromRevisionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `revisions[].restoredFromRevisionId (anyOf branch 2)` — null; required.
- `revisions[].contentSha256` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `revisions[].byteLength` — integer; required; minimum 1; maximum 262144. Exact UTF-8 byte length of the immutable reviewer-skill or framing source. Accepted length or value is 1 through 262144, inclusive. The value must be an integer.
- `revisions[].name` — string; required; minimum length 1. Human-readable name displayed in Semel. Minimum accepted length or value is 1.
- `revisions[].description` — string; required; minimum length 1. Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1.
- `revisions[].actorKind` — "human" | "agent"; required. Whether the immutable reviewer-skill revision was authored by an authenticated human or an authorized agent. Allowed values: "human", "agent".
- `revisions[].actorId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `revisions[].createdAt` — string; required; format date-time. RFC 3339 timestamp assigned by Semel when this record was created. Use an RFC 3339 date-time string.
- `revisions[].state` — "draft" | "published"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: "draft", "published".
- `revisions[].publishedVersionId` — JSON value; 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 240, inclusive.
- `revisions[].publishedVersionId (anyOf branch 1)` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `revisions[].publishedVersionId (anyOf branch 2)` — null; required.
- `revisions[].publishedVersionNumber` — JSON value; required. Positive monotonic number of the current published reviewer-skill version; null means it has never been published. A null value explicitly means no current value is available. Minimum accepted length or value is 0. The value must be an integer.
- `revisions[].publishedVersionNumber (anyOf branch 1)` — integer; required.
- `revisions[].publishedVersionNumber (anyOf branch 2)` — null; required.
- `nextCursor` — string | null; required. Opaque cursor for the next page or sync; null means the current result is complete. A null value explicitly means no current value is available.
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"revisions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"sequence": {
"type": "integer",
"exclusiveMinimum": 0,
"description": "Positive monotonic position of this immutable reviewer-skill revision in its history. Minimum accepted length or value is 0. The value must be an integer."
},
"parentRevisionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"restoredFromRevisionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
"byteLength": {
"type": "integer",
"minimum": 1,
"maximum": 262144,
"description": "Exact UTF-8 byte length of the immutable reviewer-skill or framing source. Accepted length or value is 1 through 262144, inclusive. The value must be an integer."
},
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable name displayed in Semel. Minimum accepted length or value is 1."
},
"description": {
"type": "string",
"minLength": 1,
"description": "Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1."
},
"actorKind": {
"type": "string",
"enum": [
"human",
"agent"
],
"description": "Whether the immutable reviewer-skill revision was authored by an authenticated human or an authorized agent. Allowed values: \"human\", \"agent\"."
},
"actorId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"createdAt": {
"type": "string",
"format": "date-time",
"description": "RFC 3339 timestamp assigned by Semel when this record was created. Use an RFC 3339 date-time string."
},
"state": {
"type": "string",
"enum": [
"draft",
"published"
],
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. Allowed values: \"draft\", \"published\"."
},
"publishedVersionId": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
{
"type": "null"
}
],
"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 240, inclusive."
},
"publishedVersionNumber": {
"anyOf": [
{
"type": "integer",
"exclusiveMinimum": 0
},
{
"type": "null"
}
],
"description": "Positive monotonic number of the current published reviewer-skill version; null means it has never been published. A null value explicitly means no current value is available. Minimum accepted length or value is 0. The value must be an integer."
}
},
"required": [
"id",
"sequence",
"parentRevisionId",
"restoredFromRevisionId",
"contentSha256",
"byteLength",
"name",
"description",
"actorKind",
"actorId",
"createdAt",
"state",
"publishedVersionId",
"publishedVersionNumber"
],
"additionalProperties": false
},
"maxItems": 50,
"description": "Immutable reviewer-skill revision metadata in this page; an empty array means no authorized revisions matched. 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": [
"revisions",
"nextCursor"
],
"additionalProperties": false
}
```
**Example structured result (skill-revisions)**
```json
{
"revisions": [
{
"id": "skr_recipe_checkout_2",
"sequence": 1,
"parentRevisionId": "example",
"restoredFromRevisionId": "example",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"byteLength": 1,
"name": "Checkout reliability",
"description": "example",
"actorKind": "human",
"actorId": "example",
"createdAt": "2026-09-07T16:00:00.000Z",
"state": "draft",
"publishedVersionId": "example",
"publishedVersionNumber": 1
}
],
"nextCursor": null
}
```
Bindings: listedRevisionId from structuredContent.revisions[0].id.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"revisions\":[{\"id\":\"skr_recipe_checkout_2\",\"sequence\":1,\"parentRevisionId\":\"example\",\"restoredFromRevisionId\":\"example\",\"contentSha256\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"byteLength\":1,\"name\":\"Checkout reliability\",\"description\":\"example\",\"actorKind\":\"human\",\"actorId\":\"example\",\"createdAt\":\"2026-09-07T16:00:00.000Z\",\"state\":\"draft\",\"publishedVersionId\":\"example\",\"publishedVersionNumber\":1}],\"nextCursor\":null}"
}
],
"structuredContent": {
"revisions": [
{
"id": "skr_recipe_checkout_2",
"sequence": 1,
"parentRevisionId": "example",
"restoredFromRevisionId": "example",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"byteLength": 1,
"name": "Checkout reliability",
"description": "example",
"actorKind": "human",
"actorId": "example",
"createdAt": "2026-09-07T16:00:00.000Z",
"state": "draft",
"publishedVersionId": "example",
"publishedVersionNumber": 1
}
],
"nextCursor": null
}
}
```
Next permitted action: Compare the exact before and after revisions.
**Example requests**
- “/semel show the revision history for this reviewer skill”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`.
Related operations: `skill_get`, `skill_compare`, `skill_restore`.
---
### skill_update
Save a new immutable draft revision only when expectedRevisionId is still the current head.
- Mode: write
- Risk: medium
- Scopes: `brief:read`, `skills:read`, `skills:write`
- Confirmation: explicit
- Idempotency: required
- Prerequisites: authenticated connection, the listed scopes, and a server state that permits the operation.
**Parameters**
- `name` — string; required; minimum length 1. Human-readable name displayed in Semel. Minimum accepted length or value is 1.
- `description` — string; required; minimum length 1. Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1.
- `markdown` — string; required; minimum length 1. Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters. Minimum accepted length or value is 1.
- `expectedRevisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skillId` — string; required; minimum length 1; maximum length 240. Immutable tenant reviewer-skill identifier returned by skill_list or skill_create.
- `idempotencyKey` — string; required; minimum length 1. Caller-unique key making this mutation exactly-once (see the receipt contract).
**Complete raw parameter schema**
```json
{
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Human-readable name displayed in Semel. Minimum accepted length or value is 1."
},
"description": {
"type": "string",
"minLength": 1,
"description": "Human-readable explanatory text; null or omission means no description was supplied. Minimum accepted length or value is 1."
},
"markdown": {
"type": "string",
"minLength": 1,
"description": "Exact UTF-8 Markdown document returned by or submitted to the operation; preserve its text bytes when exact identity matters. Minimum accepted length or value is 1."
},
"expectedRevisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"description": "Immutable tenant reviewer-skill identifier returned by skill_list or skill_create."
},
"idempotencyKey": {
"type": "string",
"minLength": 1,
"description": "Caller-unique key making this mutation exactly-once (see the receipt contract)."
}
},
"required": [
"name",
"description",
"markdown",
"expectedRevisionId",
"skillId",
"idempotencyKey"
],
"additionalProperties": false
}
```
**Runnable instantiated arguments**
```json
{
"skillId": "skl_recipe_checkout",
"expectedRevisionId": "skr_recipe_checkout_1",
"name": "Checkout reliability reviewer",
"description": "Checks retry-safe checkout behavior and evidence.",
"markdown": "# Checkout reliability\n\nVerify idempotent payment behavior with evidence.",
"idempotencyKey": "recipe-skill-update-v1"
}
```
**Binding template**
```json
{
"skillId": "{{skillId}}",
"expectedRevisionId": "{{draftRevisionId}}",
"name": "Checkout reliability reviewer",
"description": "Checks retry-safe checkout behavior and evidence.",
"markdown": "# Checkout reliability\n\nVerify idempotent payment behavior with evidence.",
"idempotencyKey": "{{idempotencyKey}}"
}
```
**Returns**
- `operationId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `skillId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `draftRevisionId` — string; required; minimum length 1; maximum length 240. 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 240, inclusive.
- `contentSha256` — string; required. Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes.
- `state` — constant "draft"; required. Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses "draft".
**Complete raw result schema**
```json
{
"type": "object",
"properties": {
"operationId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"skillId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"draftRevisionId": {
"type": "string",
"minLength": 1,
"maxLength": 240,
"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 240, inclusive."
},
"contentSha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"description": "Lowercase SHA-256 digest of the exact immutable UTF-8 source bytes."
},
"state": {
"type": "string",
"const": "draft",
"description": "Current typed lifecycle state; the schema enum or union branch defines allowed values. This branch always uses \"draft\"."
}
},
"required": [
"operationId",
"skillId",
"draftRevisionId",
"contentSha256",
"state"
],
"additionalProperties": false
}
```
**Example structured result (skill-draft)**
```json
{
"operationId": "example",
"skillId": "skl_recipe_checkout",
"draftRevisionId": "skr_recipe_checkout_2",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "draft"
}
```
Bindings: updatedRevisionId from structuredContent.draftRevisionId.
**MCP wire envelope**
```json
{
"content": [
{
"type": "text",
"text": "{\"operationId\":\"example\",\"skillId\":\"skl_recipe_checkout\",\"draftRevisionId\":\"skr_recipe_checkout_2\",\"contentSha256\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"state\":\"draft\"}"
}
],
"structuredContent": {
"operationId": "example",
"skillId": "skl_recipe_checkout",
"draftRevisionId": "skr_recipe_checkout_2",
"contentSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"state": "draft"
}
}
```
Next permitted action: List immutable revisions and compare the intended edit.
**Example requests**
- “/semel save this reviewer-skill edit against the revision I inspected”
Errors: `PROJECT_ACCESS_DENIED`, `AUTHORIZATION_SCOPE_MISSING`, `CONFLICTING_IDEMPOTENCY_REPLAY`, `VALIDATION_FAILED`.
Related operations: `skill_get`, `skill_compare`, `skill_publish`.
## Calling a tool correctly
Validate the whole advertised input shape, including nested objects and enums, before calling. All tools require `brief:read`; writes add the scopes shown below and an `idempotencyKey`. Bind IDs, hashes, fence tokens, sequence values, and cursors from the previous response’s `structuredContent`. Do not parse display text. Responses may also include an MCP `resource_link`; fetch only a link returned for the active operation and principal.
> **Note:** An unchanged retry is safe only when the response says it is retryable or when you reuse the same idempotency key with identical arguments. After a timeout with no authoritative response, read status before deciding whether to replay.
## What is deliberately not here
Human-only actions do not appear as MCP tools: gate approval/rejection; proposal decision, commit, rebase, or revert; grant mint/approval; destructive review clear/restart; billing/spend; workspace or credential administration; connecting Slack/GitHub/a tracker; provider/BYOK consent; public share links; Brain writes; Done Check; and `/runs/:id/continue`. The codebase exception is `project_codebase_link`, which only links a repository already connected by a person. REST-only web reads and controls also stay outside MCP. If a tool expected by a recipe is missing, request only the needed capability or scope; see [Troubleshooting](https://docs.semel.ai/troubleshooting#missing-tools).
Canonical page: https://docs.semel.ai/tools