# propose_semantic_revision

Propose changed customer meaning for named-owner review. The current active revision remains authoritative until the new agreed revision is independently qualified and atomically activated.

Reviewed 2026-10-01. Read the [current operating instructions](https://app.balladeer.ai/agent) and the [tool index](/docs/mcp-reference.md). This reference does not authorize the action.

## Parameters

```json
{
  "type": "object",
  "properties": {
    "explicitHumanAction": {
      "description": "Must be true only when the person explicitly asked to protect or change this behavior. Ambient inference is forbidden.",
      "type": "boolean",
      "const": true
    },
    "reason": {
      "description": "Why, in the person's own words where they gave you any. It is recorded on the proposal and read by whoever decides it. Name nobody in it: Balladeer records who connected you as the person behind this act, and a name from git, a commit or a file is not the person in the conversation. Say \"the person\" or quote their words.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "promiseId": {
      "type": "string",
      "pattern": "^prom_[a-z0-9]{8,64}$"
    },
    "meaning": {
      "type": "object",
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 160
        },
        "oneSentenceOutcome": {
          "description": "The whole promise in one sentence a person could say to a customer, at most 160 characters. Write it in their words, and never as a restatement of the name.",
          "type": "string",
          "minLength": 1,
          "maxLength": 160
        },
        "beneficiary": {
          "description": "Who relies on this behavior, named the way a teammate would: a buyer, a promise owner, a person who installed the CLI.",
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "trigger": {
          "description": "The situation that sets this behavior off, in plain words a teammate would use for the work that meets it, such as 'a buyer edits an approved order'. Later work finds this promise by its trigger and beneficiary: name the situation in the software, not the product.",
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "preconditions": {
          "description": "What must be true for this behavior to apply, one condition each: which customers, accounts or plans; which role or actor; which environment, region or locale; which feature flag or rollout stage; which versions; from or until when. Write only limits the person stated or the work plainly shows. Never invent one, and leave the list empty when the behavior applies to everyone.",
          "maxItems": 24,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "observableOutcome": {
          "type": "string",
          "minLength": 1,
          "maxLength": 8000
        },
        "allowedVariations": {
          "maxItems": 24,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "nonGoals": {
          "description": "Who and what this promise does not cover, one each: the customers, roles, environments or situations a reader might wrongly assume are included. Later work is ruled in or out by these.",
          "maxItems": 24,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "passingExamples": {
          "minItems": 1,
          "maxItems": 12,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "setup": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "expectedOutcome": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "saidWords": {
                "description": "The person's own sentence this case was drawn from, quoted exactly. Leave it out rather than composing one.",
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              }
            },
            "required": [
              "label",
              "setup",
              "expectedOutcome"
            ],
            "additionalProperties": false
          }
        },
        "failingExamples": {
          "minItems": 1,
          "maxItems": 12,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "setup": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "expectedOutcome": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "saidWords": {
                "description": "The person's own sentence this case was drawn from, quoted exactly. Leave it out rather than composing one.",
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              }
            },
            "required": [
              "label",
              "setup",
              "expectedOutcome"
            ],
            "additionalProperties": false
          }
        },
        "refactorExamples": {
          "minItems": 1,
          "maxItems": 12,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "label": {
                "type": "string",
                "minLength": 1,
                "maxLength": 160
              },
              "setup": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "expectedOutcome": {
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              },
              "saidWords": {
                "description": "The person's own sentence this case was drawn from, quoted exactly. Leave it out rather than composing one.",
                "type": "string",
                "minLength": 1,
                "maxLength": 2000
              }
            },
            "required": [
              "label",
              "setup",
              "expectedOutcome"
            ],
            "additionalProperties": false
          }
        },
        "saidWords": {
          "description": "The person's own sentence the claim was drawn from, quoted exactly. Never a paraphrase, and never composed.",
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "scope": {
          "type": "object",
          "properties": {
            "repositoryId": {
              "type": "string",
              "format": "uuid",
              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
            },
            "surfaces": {
              "description": "One or more real repository-relative paths or one-token capability markers. Reuse an existing marker when known. For a new capability the person named, format its words as a hyphenated marker yourself: for example, supplier import becomes supplier-import. This is a descriptive marker, not a registered identifier; do not ask the person to supply its format. Use a file path only when you know it exists in this repository. Never invent paths or repository IDs; get the repositoryId from get_promise_setup.",
              "minItems": 1,
              "maxItems": 24,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 96,
                "pattern": "^[A-Za-z0-9_:.@/[\\]-]+$"
              }
            },
            "labels": {
              "default": [],
              "maxItems": 24,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 96,
                "pattern": "^[A-Za-z0-9_:.@/[\\]-]+$"
              }
            }
          },
          "required": [
            "repositoryId",
            "surfaces"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "title",
        "beneficiary",
        "trigger",
        "preconditions",
        "observableOutcome",
        "allowedVariations",
        "nonGoals",
        "passingExamples",
        "failingExamples",
        "scope"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "explicitHumanAction",
    "reason",
    "promiseId",
    "meaning"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}
```

## Effect annotations

```json
{
  "readOnlyHint": false,
  "destructiveHint": false,
  "idempotentHint": false,
  "openWorldHint": false
}
```