# propose_supersession

Propose that one approved promise is replaced by another, for the named meaning owner to decide. Name an existing successor promise, or describe the successor's meaning and it is filed as a proposal the owner must agree to first. This never retires anything.

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}$"
    },
    "successorPromiseId": {
      "description": "An existing agreed promise in this repository that replaces this one.",
      "type": "string",
      "pattern": "^prom_[a-z0-9]{8,64}$"
    },
    "successorMeaning": {
      "description": "The successor's meaning, when no promise holds it yet. It is filed as a proposal; a named person must agree to it before this promise can point at it.",
      "type": "object",
      "properties": {
        "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
        },
        "unresolvedQuestions": {
          "default": [],
          "maxItems": 0,
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2000
          }
        },
        "proposedOwnerId": {
          "description": "Membership ID of the person who should be asked to agree to the successor's meaning, from the members list on get_promise_setup. A name that is not on that list is refused and the refusal says who is. Omit it when the person did not name an owner.",
          "type": "string",
          "maxLength": 2000
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "wrongOutcome": {
          "description": "What going wrong looks like for the successor, in the person's own words, as a must-not. Refused when it is missing, exactly as it is for propose_promise.",
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        },
        "leastSure": {
          "description": "Balladeer no longer stores outstanding questions. Before writing, ask the person only about ambiguity that changes the commitment, then put their answer in the meaning and cases. Do not invent an answer or change agreed meaning. Nothing was recorded; refresh your Balladeer instructions before retrying.",
          "type": "string",
          "minLength": 1,
          "maxLength": 2000
        }
      },
      "required": [
        "meaning",
        "confidence"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "explicitHumanAction",
    "reason",
    "promiseId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}
```

## Effect annotations

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