DefProd 1
MCP Server Reference
56
Total Tools
9
Modules
Overview
Welcome to the DefProd MCP server documentation. This MCP server provides AI agents with access to DefProd's functionality and data. When AI agents interact with your product definition, the magic really starts to happen!
Tool Summary
The DefProd MCP server provides these tools:
- assessChangeRisk: Score a change against the risk rubric and record the assessment. Give severity, occurrence and detection on the 1-10 ordinal scales, each with the evidence behind it — an axis without evidence is rejected, because an unsupported score is not an assessment. Detection is INVERTED: 1 means certain to be caught before a customer sees it, 10 means silent. You do NOT supply the category. It is derived from the vector by a severity-weighted lookup and returned on the change; supplying one is rejected. The only way to move the category is to move an axis and evidence it. Before scoring, perform the lookups the rubric mandates: enumerate what the change touches (and whether any of it is billing, authentication, authorisation or tenant isolation) for severity; find the prior art and check docs/rules and the incident record for the failure pattern for occurrence; run coverage over the changed paths and name the test that would fail — or state that none exists — for detection. Scoring occurrence LOW because the subsystem is unfamiliar is the classic error: unfamiliarity is an argument for a HIGH occurrence. For a change involving a database migration, use overlay "dbm" and declare both writeSet and sideEffects. Empty arrays are permitted but must be stated explicitly. Reversibility is then DERIVED from those declarations and overrides your authored value unless you record a justification; both values are kept. Re-assess freely as the change progresses — the current assessment is replaced and the full history is kept in the change event trail. Assessing never moves the change through its pipeline and never disturbs recorded stage times. Re-assessing is also safe for the change's pipeline confirmation, in one direction only. A score that RAISES the category out of an auto-confirmed band clears the confirmation, so the record never states an oversight level the current assessment contradicts, and a fresh confirmation is then required. A score that LOWERS it leaves the stricter confirmation standing and does not auto-confirm the lighter band: an agent does not reduce oversight below an explicit human choice, so a fall is a proposal a person accepts by calling confirmChangePipeline. The trail records that the lighter selection was held rather than applied.
- cancelChange: Cancel a change (change-level). The position is preserved — a later reopenChange resumes exactly where it stopped. Any in-progress stage work is cancelled with it. The first cancellation stamps cancelledAt permanently. Shipped (frozen) changes cannot be cancelled. Emits changeCancelled.
- cancelChangeStage: Cancel in-progress stage work without finishing it — the stage returns to not started and the working actor is cleared; the change stays alive at the same position. The escape valve for a crashed agent or a human pulled away. Emits changeStageCancelled.
- confirmChangePipeline: Freeze onto the change, in full, the pipeline it runs under — every stage, whether it is enabled, and who drives it — together with the risk category that selected it. You do NOT supply the category, and you do NOT supply the pipeline. The category is read from the change's own current risk assessment and the pipeline is resolved from it; a change with no assessment is rejected, because there is nothing to resolve from. Assess first, then confirm. The record is deliberately self-contained rather than a reference to configuration: it must still name the pipeline this change was SELECTED for after the repository's configuration has been edited. It is not a record of what oversight the change actually received — that is answered per stage by the driver reported when the stage was stamped. Automation never lowers it. A re-assessment that falls below a band already confirmed leaves the stricter confirmation standing rather than replacing it, because an agent does not reduce oversight below an explicit human choice. Calling this tool, by contrast, always applies the change's current category — that is how a human accepts a proposed reduction. You may pass per-stage driver overrides ONLY where the change's repository sets allowConfirmedPipelineOverride. Where it does not, supplying them is rejected rather than quietly ignored, so you never believe you confirmed a pipeline you did not. Overrides target judgement stages only (design, define, code, test, review, merge, push) and may set human or agent, never cicd. Where a repository auto-confirms a band — low, unless it says otherwise — the pipeline is already confirmed as part of recording the assessment, and calling this is unnecessary for changes in that band. Re-confirm freely while the change is in flight: the record is replaced and the full history is kept in the change event trail. Confirming never moves the change through its pipeline and never disturbs recorded stage times. Whether the confirmed pipeline then GOVERNS the change is the repository's decision, not this call's: where the repo grants confirmed pipelines authority, the change runs under this pipeline and a later configuration edit cannot reach it; where it does not, the confirmation is recorded and drives nothing. Read effectivePipelineSource on the change to see which applies rather than inferring it.
- createArchitectureElement: Create a new architecture element
- createArea: Create a new product area
- createChange: Create a new change record. Creating a change is the accept gate: the record enters the pipeline with acceptance completed. Origin is an external reference (e.g. a JIRA key or brain intent), never a DefProd entity. An externally-sourced change whose origin is already carried by an ACTIVE change is rejected (duplicate promotion); a cancelled predecessor suggests reopenChange; shipped predecessors do not block.
- createProduct: Create a new product definition
- createRepo: Create a new repository connection
- createUserStory: Create a new user story
- deleteArchitectureElement: Delete an architecture element
- deleteArea: Delete a product area
- deleteChange: Delete a change record. Shipped changes are frozen and cannot be deleted — use cancelChange for cancelled work; delete is for records that should never have existed.
- deleteProduct: Delete a product definition
- deleteRepo: Delete a repository connection
- deleteUserStory: Delete a user story
- failChangeStage: Report in-progress stage work as failed — the stage is recorded as failed rather than returned to not started, so an attempt that did not succeed is never mistaken for one that never began. The change stays alive at the same position and can be retried by starting the stage again. The counterpart to cancelChangeStage, which is for deliberate abandonment. Emits changeStageFailed.
- finishCdRun: Report a CD run's terminal facts — outcome (shipped | failed | aborted), failing stage, stage timeline, and log tail (one-way, best-effort ingestion). On a successful production ship the server mints one release per delivered product; the pipeline never creates a release itself.
- finishChangeStage: Finish a pipeline stage. Omit `stage` and the server finishes the stage currently in progress (or, if idle, the next enabled stage). The caller reports the fact ("review is done") — the backend owns the workflow. Finishing an unstarted stage is legal (startedAt stays null = start unrecorded). Stamps the first-entry finishedAt; finishing `ship` freezes the record permanently; emits changeStageFinished. Optionally report `driver` — who actually drove this stage — on the same terms as startChangeStage. It is accepted here as well as there because a stage whose start was never reported (a CI-stamped stage, for one) would otherwise have no way to record one. The first report wins, so a driver already recorded at the start is not overwritten.
- getArchitectureForProduct: Get the architecture for a product
- getArchitectureTree: Get the architecture tree for an architecture
- getArea: Get a product area
- getBriefForProduct: Get the brief for a product
- getCdRun: Get a CD deployment run by id — its outcome, target environment, triggering commit, per-stage timeline and log tail.
- getChange: Get a change record by id, or by productId + key (key lookup tolerates zero-padding: CHG-7, CHG-07 and CHG-007 resolve to the same record).
- getChangeAnalytics: Read one period of change analytics for a team, a repository, or a single product — the investment mix, how long change work took from acceptance to production, and the risk and capability layers. Returns the chosen period AND the one before it, because the comparison that matters is a scope against its own previous period. Comparing scopes against each other is not supported and is not an omission: change granularity is a local convention, so counts do not travel between teams or products. Every headline figure counts only changes that SHIPPED inside the period, so accepting a large batch of new work does not move it. Newly accepted work is reported separately. Durations always arrive paired with the open-work count and age spread. A median computed over only the changes that finished is survivorship-biased and improves as a team gets more backed up, so it is never returned alone. Waiting time is attributed to what the change was waiting on — a person, an agent, or automated delivery — from the pipeline it ran under. That is a queue fact, never a claim about how much work a named individual did. A closed period is served from its frozen rollup where one exists, so a figure quoted from it does not later change; `isProvisional` is true for the current, still-running period.
- getEffectiveChangePipeline: Resolve a product's effective change pipeline: the repository-level default with the product's judgement-stage driver overrides applied. This is the same resolution the change stage engine uses, so agents and tools see the same enabled stages and drivers the UI shows.
- getProduct: Get a product definition
- getProductBySlug: Get a product definition by its globally-unique slug
- getRelease: Get a release (a per-product production-ship artifact) by id, including its version, the changes it delivered, and any release notes.
- getRepo: Get a repository by ID with discovered packages
- getUserStory: Get a user story
- linkProductToRepo: Atomically link an existing product to an existing repo.products[] entry discovered by the scanner
- listAreas: List areas for a product
- listCdRuns: List a team's CD deployment runs, newest first (every outcome — in progress, shipped, failed, aborted). Optionally narrow to runs that touched a given product, environment, or outcome. Returns a COMPACT SUMMARY per run: outcome, products, changes, triggering commit, environment, version, stage timeline and timings. It deliberately carries no log output — read a run's log tail from getCdRun. Results are a bounded slice and the response reports the true total so a slice is never mistaken for the whole set. This is the data behind the Deployments view.
- listChanges: List change records for a product, optionally filtered by stage, stage state, type, cancellation, or external origin reference (originSystem/originRef — e.g. find the change for JIRA ticket PROJ-123). Returns a COMPACT SUMMARY per change: identity, type, lifecycle position, the owning product, link counts, the assessed risk category and when the current stage began. It deliberately carries no long-form narrative (intent, design), no pipeline configuration and no risk evidence — fetch the full record for one change with getChange. Results are a bounded slice, newest-updated first, and the response reports the true total so a slice is never mistaken for the whole set.
- listProducts: List all product definitions
- listReleases: List a product's releases, newest first — the version each shipped, the changes it delivered, and any release notes. This is the data behind the per-product Releases view.
- listRepos: List repositories for a team
- listTeamChanges: List change records across every product in a team, optionally filtered by repository, product, stage, stage state, type, cancellation, or external origin reference. Returns the same COMPACT SUMMARY per change as listChanges — identity, type, lifecycle position, the owning product, link counts, the assessed risk category and when the current stage began — with no long-form narrative, pipeline configuration or risk evidence; fetch the full record for one change with getChange. Results are a bounded slice, newest-updated first, reporting the true total, and are limited to the products the caller may read.
- listUserStories: List user stories for a product
- moveArchitectureElement: Move an architecture element to a new parent and/or position
- patchArchitectureElement: Apply patch changes to an architecture element
- patchArea: Apply patch changes to a product area
- patchBrief: Apply patch changes to a product brief
- patchChange: Apply patch changes to a change record (content only; lifecycle position and cancellation are written solely via the stage-action cases; historical stage times are set or corrected via the setChangeStageTimes case, not here; shipped records are frozen)
- patchProduct: Apply patch changes to a product definition
- patchRelease: Edit a release. Only the human-authored notes changelog (/notes) is editable; version, delivered changes, source run and shipped date are immutable records of what actually shipped.
- patchRepo: Apply patch changes to a repository (e.g. update discovered packages, link packages to products)
- patchUserStory: Apply patch changes to a user story
- recordChangeDefect: Classify the defect a fix repaired, so risk predictions can later be scored against what actually happened. Applies to a change of type bug only. One classification per change, holding the MOST SEVERE defect the fix repaired: rank by who it affected — customer beats staff beats developer — and break ties by impact severity. A fix that repaired several defects records the one nearest the customer and lets the rest go; the number this produces is "customer-facing defects", not "defects". impactSeverity is scored on the SAME 1-10 anchors as the risk rubric's Severity axis, and for the same reason the assessment demands evidence: an unsupported score is not an assessment. Score it WITHIN the audience you named in affects — the anchors are written assuming a customer, so a staff-only defect breaking a core admin workflow reads as an 8 and wildly overstates its business impact. Never compare severities across audiences. foundBy is what actually exposed the defect, not what should have. It is the field that tells the team which gate to invest in, and it is the cheapest one here — you cannot fix a bug without already knowing how you found it. THE COMMIT IS THE THING TO SUPPLY, not the change. Give introducedInCommit from bisect or blame, and introducedInCommitTrailer as the Change: trailer read off that same commit; the change link, and how long the defect lay undetected, are derived from those. Do not look a change up yourself. Where the defect is in code that never worked there is no introducing commit — record age "base" and omit them both, rather than guessing. Recording a classification never moves the change through its pipeline, never disturbs stage times, and never blocks a fix from shipping. It can also be recorded or amended AFTER the change has shipped, unlike every other content field — realised impact is often only learned once a customer explains what actually happened, and the full history is kept in the change event trail.
- reopenChange: Reopen a cancelled change — it resumes at the position (stage and state) it held when cancelled, with all stamps intact. Only cancelled changes can be reopened. Emits changeReopened.
- reportCdRunStage: Report the progress of a single stage while a CD run is in progress (one-way, best-effort ingestion from the pipeline). The stage timeline builds up during the run instead of arriving only at the terminal report. A report against an already-terminal run is ignored (the terminal report's timeline is authoritative). The app never drives the pipeline — this only records what the pipeline reports.
- setChangeStageTimes: Set or correct a change's historical stage start/finish times. Give a `stamps` array, one entry per stage `{ stage, startedAt?, finishedAt? }` (times as ISO string, epoch millis, or Date). Fills blank times OR corrects already-recorded ones. Never moves lifecycle position or current-stage state. Guards: only a stage the change has already reached may be timed; per stage startedAt <= finishedAt; no future dates; shipped records are frozen. The durable audit trail remains the stage started/finished events — this writes only the summary stamps.
- startCdRun: Report the start of a CD deployment run (one-way, best-effort ingestion from the pipeline). Creates the run in progress; as a side effect the server reconciles any prior dangling in-progress run for the team to aborted. The app never drives the pipeline — this only records what the pipeline reports.
- startChangeStage: Start work on a pipeline stage. Omit `stage` and the server resolves the next enabled stage in the product's change pipeline — callers need no workflow knowledge. An explicit stage is a deliberate jump (skip ahead, or rework an earlier stage). Records who is working (the calling actor) and the first-entry startedAt stamp; emits changeStageStarted. Optionally report `driver` — who is actually driving this stage. It cannot be derived server-side: a per-run driver override legitimately deviates from the configured pipeline, and the calling actor is the API-key identity, so an agent stage authenticates as the person whose key it holds. It is a fact report, not validated against configuration, and the first report wins. Omit it and the stage records no driver, which reads as unknown and is never inferred from configuration.
Transports
The DefProd MCP server supports both MCP transport protocols:
- SSE (Server-Sent Events) -
https://mcp.defprod.one/mcp/sse - HTTP Streaming -
https://mcp.defprod.one/mcp
Both transports provide real-time bidirectional communication between MCP clients and the MCP server. Which one you use will often depend on the capabilities of the MCP client you are using.
Authentication
All requests to the MCP server require authentication using an API key. The API key must be provided in the x-api-key header.
Users can generate API keys through their user settings in the DefProd application. Each user can create multiple API keys for different purposes.
MCP Client Configuration
To connect to the DefProd MCP server, configure your MCP client with the appropriate transport URL and authentication headers. Here are the typical configuration examples for some popular MCP clients:
SSE Transport Configuration
{
"defprod-mcp-sse": {
"type": "sse",
"url": "https://mcp.defprod.one/mcp/sse",
"headers": {
"x-api-key": "<key>"
}
}
}
HTTP Streaming Transport Configuration
{
"defprod-mcp": {
"type": "http",
"url": "https://mcp.defprod.one/mcp",
"headers": {
"x-api-key": "<key>"
}
}
}
Replace <key> with your actual API key obtained from your DefProd user settings.
Tools
architecture(6 tools)
createArchitectureElement
Create a new architecture element
Input Schema
{
"type": "object",
"properties": {
"architectureId": {
"type": "string",
"description": "Architecture ID"
},
"name": {
"type": "string",
"description": "Architecture element name"
},
"content": {
"type": "string",
"description": "Architecture element content"
},
"type": {
"type": "string",
"enum": [
"architecture",
"frontend",
"backend",
"module",
"layer",
"component",
"service",
"repository",
"database",
"externalSystem",
"library",
"other"
],
"description": "Architecture element type"
},
"parentId": {
"type": "string",
"description": "Parent architecture element ID"
}
},
"required": [
"architectureId",
"name",
"content",
"type",
"parentId"
],
"description": "Create architecture element request"
}
Example Input
{
"architectureId": "ARCHITECTURE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"name": "API Gateway",
"content": "Main API gateway component",
"type": "component",
"parentId": "ARCHITECTURE_ELEMENT-12345678-1234-1234-1234-123456789012"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"architectureId": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"architecture",
"frontend",
"backend",
"module",
"layer",
"component",
"service",
"repository",
"database",
"externalSystem",
"library",
"other"
]
},
"content": {
"type": "string"
},
"parentId": {
"type": "string",
"nullable": true
},
"childrenIds": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"_id",
"architectureId",
"name",
"type"
],
"description": "Output for creating an architecture element"
}
Example Output
{
"_id": "ARCHITECTURE_ELEMENT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"architectureId": "ARCHITECTURE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"name": "API Gateway",
"type": "component",
"content": "Main API gateway component",
"parentId": "ARCHITECTURE_ELEMENT-12345678-1234-1234-1234-123456789012",
"childrenIds": []
}
deleteArchitectureElement
Delete an architecture element
Input Schema
{
"type": "object",
"properties": {
"architectureElementId": {
"type": "string",
"description": "Architecture element ID"
}
},
"required": [
"architectureElementId"
],
"description": "Architecture element selector"
}
Example Input
{
"architectureElementId": "ARCHITECTURE_ELEMENT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {},
"description": "This operation returns no data; the response carries only the envelope meta."
}
getArchitectureForProduct
Get the architecture for a product
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
}
},
"required": [
"productId"
],
"description": "Product selector"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"name": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"description": {
"type": "string"
},
"metadata": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"_id",
"name",
"createdAt",
"updatedAt"
]
}
Example Output
{
"architecture": {
"_id": "ARCHITECTURE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"name": "System Architecture",
"description": "Main system architecture",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
}
getArchitectureTree
Get the architecture tree for an architecture
Input Schema
{
"type": "object",
"properties": {
"architectureId": {
"type": "string",
"description": "Architecture ID"
}
},
"required": [
"architectureId"
],
"description": "Architecture selector"
}
Example Input
{
"architectureId": "ARCH-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"architectureId": {
"type": "string"
},
"name": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"architecture",
"frontend",
"backend",
"module",
"layer",
"component",
"service",
"repository",
"database",
"externalSystem",
"library",
"other"
]
},
"content": {
"type": "string"
},
"parentId": {
"type": "string",
"nullable": true
},
"childrenIds": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object",
"additionalProperties": {}
}
},
"required": [
"_id",
"architectureId",
"name",
"type"
]
}
Example Output
{
"_id": "ARCHELEM-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"architectureId": "ARCH-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"name": "Root Element",
"type": "component",
"content": "Root architecture element",
"parentId": null,
"children": [
{
"_id": "ARCHELEM-e152210e-9d1c-4f46-8b7f-2964161e1d06",
"architectureId": "ARCH-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"createdAt": "2025-06-02T08:34:06.140Z",
"name": "Frontend",
"parentId": "ARCHELEM-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"type": "frontend",
"updatedAt": "2025-06-04T00:57:33.349Z",
"content": "Our chief weapons are components! Components and services... Our two weapons are components and services... and an almost fanatical devotion to RxJS Observables! Our *three* weapons are..."
}
]
}
moveArchitectureElement
Move an architecture element to a new parent and/or position
Input Schema
{
"type": "object",
"properties": {
"architectureElementId": {
"type": "string",
"description": "Architecture element ID to move"
},
"newParentId": {
"type": "string",
"description": "New parent ID (null for root, undefined to keep current parent)",
"nullable": true
},
"order": {
"type": "number",
"description": "New order position (defaults to last sibling if not provided)"
}
},
"required": [
"architectureElementId"
],
"description": "Parameters for moving an architecture element"
}
Example Input
{
"architectureElementId": "ARCHELEM-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"newParentId": "ARCHELEM-12345678-1234-1234-1234-123456789012",
"order": 1
}
Output Schema
{
"type": "object",
"properties": {},
"description": "This operation returns no data; the response carries only the envelope meta."
}
Example Output
{}
patchArchitectureElement
Apply patch changes to an architecture element
Input Schema
{
"type": "object",
"properties": {
"architectureElementId": {
"type": "string",
"description": "Architecture element ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"comment": {
"type": "string",
"description": "Patch comment"
}
},
"required": [
"architectureElementId",
"patch"
],
"description": "Parameters for patching an architecture element"
}
Example Input
{
"architectureElementId": "ARCHITECTURE_ELEMENT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/name",
"value": "Updated Element Name"
}
],
"comment": "Update element name"
}
Output Schema
{
"type": "object",
"properties": {
"architectureElementId": {
"type": "string",
"description": "Architecture element ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"patchId": {
"type": "string",
"description": "Patch ID"
}
},
"required": [
"architectureElementId",
"patch",
"patchId"
],
"description": "Output for patching an architecture element"
}
Example Output
{
"architectureElementId": "ARCHITECTURE_ELEMENT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/name",
"value": "Updated Element Name"
}
],
"patchId": "PATCH-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
area(5 tools)
createArea
Create a new product area
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the area"
},
"productId": {
"type": "string",
"description": "ID of the product this area belongs to"
},
"key": {
"type": "string",
"description": "Display identifier for the area"
},
"description": {
"type": "string",
"description": "Description of the area (optional)"
}
},
"required": [
"name",
"productId",
"key"
]
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"name": "User Management",
"description": "Area for managing users",
"key": "USER",
"order": 1
}
Output Schema
{
"type": "object",
"properties": {
"areaId": {
"type": "string",
"description": "Area ID"
},
"key": {
"type": "string",
"description": "Area key (unique within the product)"
},
"name": {
"type": "string",
"description": "Area name"
},
"productId": {
"type": "string",
"description": "Product ID this area belongs to"
}
},
"required": [
"areaId",
"key",
"name",
"productId"
],
"description": "Create area response"
}
Example Output
{
"areaId": "AREA-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "USER",
"name": "User Management",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
deleteArea
Delete a product area
Input Schema
{
"type": "object",
"properties": {
"areaId": {
"type": "string",
"description": "Area ID"
}
},
"required": [
"areaId"
],
"description": "Area selector"
}
Example Input
{
"areaId": "AREA-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {},
"description": "This operation returns no data; the response carries only the envelope meta."
}
getArea
Get a product area
Input Schema
{
"type": "object",
"properties": {
"areaId": {
"type": "string",
"description": "Area ID"
}
},
"required": [
"areaId"
],
"description": "Area selector"
}
Example Input
{
"areaId": "AREA-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"productId": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"description": {
"type": "string"
},
"order": {
"type": "number"
}
},
"required": [
"_id",
"key",
"name",
"productId",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "AREA-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"name": "User Management",
"description": "Area for managing users",
"key": "USER",
"order": 1,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z",
"visibility": "public"
}
listAreas
List areas for a product
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
}
},
"required": [
"productId"
],
"description": "Product selector"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"key": {
"type": "string"
},
"name": {
"type": "string"
},
"productId": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"description": {
"type": "string"
},
"order": {
"type": "number"
}
},
"required": [
"_id",
"key",
"name",
"productId",
"createdAt",
"updatedAt"
]
}
}
Example Output
[
{
"_id": "AREA-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"name": "User Management",
"description": "Area for managing users",
"key": "USER",
"order": 1,
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z",
"visibility": "public"
}
]
patchArea
Apply patch changes to a product area
Input Schema
{
"type": "object",
"properties": {
"areaId": {
"type": "string",
"description": "Area ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"comment": {
"type": "string",
"description": "Patch comment"
}
},
"required": [
"areaId",
"patch"
],
"description": "Parameters for patching an area"
}
Example Input
{
"areaId": "AREA-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/name",
"value": "Updated Area Name"
}
],
"comment": "Update area name"
}
Output Schema
{
"type": "object",
"properties": {
"areaId": {
"type": "string",
"description": "Area ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"patchId": {
"type": "string",
"description": "Patch ID"
}
},
"required": [
"areaId",
"patch",
"patchId"
],
"description": "Output for patching an area"
}
Example Output
{
"areaId": "AREA-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/name",
"value": "Updated Area Name"
}
],
"patchId": "PATCH-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
brief(2 tools)
getBriefForProduct
Get the brief for a product
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
}
},
"required": [
"productId"
],
"description": "Product selector"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Brief ID"
},
"productId": {
"type": "string",
"description": "Product ID"
},
"description": {
"type": "string",
"description": "Brief description"
},
"positioning": {
"type": "string",
"description": "Product positioning statement — market category, differentiation, competitive context"
},
"userId": {
"type": "string",
"description": "User ID"
},
"problem": {
"type": "object",
"properties": {
"summary": {
"type": "string"
},
"context": {
"type": "string"
},
"impact": {
"type": "string"
}
},
"required": [
"summary",
"context",
"impact"
],
"description": "Problem definition"
},
"users": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"goals": {
"type": "array",
"items": {
"type": "string"
}
},
"painPoints": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"title",
"description",
"goals",
"painPoints"
]
},
"description": "User personas"
},
"requirements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"must",
"should",
"could",
"wont"
]
}
},
"required": [
"id",
"title",
"description",
"priority"
]
},
"description": "Requirements"
},
"aesthetics": {
"type": "object",
"properties": {
"tone": {
"type": "string"
},
"visualStyle": {
"type": "string"
},
"interactionPrinciples": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"tone",
"visualStyle",
"interactionPrinciples"
],
"description": "Aesthetics"
},
"successCriteria": {
"type": "array",
"items": {
"type": "string"
},
"description": "Success criteria"
},
"outOfScope": {
"type": "array",
"items": {
"type": "string"
},
"description": "Out of scope items"
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"inspiration",
"competitor",
"other"
]
},
"url": {
"oneOf": [
{
"type": "string"
},
{
"type": "string"
},
{
"type": "string",
"enum": [
""
]
}
],
"description": "An absolute URL (https://example.com/doc), a repository-relative path to a project document (docs/onboarding.md), or \"\" when there is no link",
"nullable": true
},
"description": {
"type": "string"
}
},
"required": [
"type"
]
},
"description": "References"
},
"createdAt": {
"type": "string",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"description": "Last update timestamp"
}
},
"required": [
"_id",
"productId",
"description",
"positioning",
"userId",
"problem",
"users",
"requirements",
"aesthetics",
"successCriteria",
"outOfScope",
"references",
"createdAt",
"updatedAt"
],
"description": "Brief"
}
Example Output
{
"_id": "BRIEF-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"description": "A product brief",
"userId": "USER-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"problem": {
"statement": "Problem statement",
"context": "Problem context"
},
"users": [],
"requirements": [],
"aesthetics": {
"style": "modern",
"colorScheme": "blue"
},
"successCriteria": [],
"outOfScope": [],
"references": [],
"version": 1,
"history": [],
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
patchBrief
Apply patch changes to a product brief
Input Schema
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"description": "Brief ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"comment": {
"type": "string",
"description": "Patch comment"
}
},
"required": [
"briefId",
"patch"
],
"description": "Parameters for patching a brief"
}
Example Input
{
"briefId": "BRIEF-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/description",
"value": "Updated brief description"
}
],
"comment": "Update brief description"
}
Output Schema
{
"type": "object",
"properties": {
"briefId": {
"type": "string",
"description": "Brief ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"patchId": {
"type": "string",
"description": "Patch ID"
}
},
"required": [
"briefId",
"patch",
"patchId"
],
"description": "Output for patching a brief"
}
Example Output
{
"briefId": "BRIEF-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/description",
"value": "Updated brief description"
}
],
"patchId": "PATCH-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
cdRun(5 tools)
finishCdRun
Report a CD run's terminal facts — outcome (shipped | failed | aborted), failing stage, stage timeline, and log tail (one-way, best-effort ingestion). On a successful production ship the server mints one release per delivered product; the pipeline never creates a release itself.
Input Schema
{
"type": "object",
"properties": {
"cdRunId": {
"type": "string",
"description": "CD run ID (from startCdRun)"
},
"outcome": {
"type": "string",
"enum": [
"shipped",
"failed",
"aborted"
],
"description": "Terminal outcome (shipped | failed | aborted)"
},
"failingStage": {
"type": "string",
"enum": [
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage at which a failed run failed"
},
"stageTimeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this timeline entry covers"
},
"status": {
"type": "string",
"enum": [
"inProgress",
"succeeded",
"failed"
],
"description": "How this stage ended"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage started (null = start unrecorded)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage finished (null = still running / not reached)",
"nullable": true
}
},
"required": [
"stage",
"status"
],
"description": "One stage entry in a CD run timeline"
},
"description": "Run-level per-stage timeline"
},
"logTail": {
"type": "string",
"description": "Bounded tail of the run log (~last 200 lines)"
},
"logPath": {
"type": "string",
"description": "Pointer to the log file on the build host"
},
"version": {
"type": "string",
"description": "Shipped version vX.Y.Z — required for a successful production ship (drives Release minting)"
}
},
"required": [
"cdRunId",
"outcome"
],
"description": "Report the terminal facts of a CD run"
}
Example Input
{
"cdRunId": "CDRUN-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"outcome": "shipped",
"version": "v1.2.3",
"stageTimeline": [
{
"stage": "build",
"startedAt": "2026-07-20T10:00:00.000Z",
"finishedAt": "2026-07-20T10:02:00.000Z",
"status": "succeeded"
},
{
"stage": "ship",
"startedAt": "2026-07-20T10:05:00.000Z",
"finishedAt": "2026-07-20T10:06:00.000Z",
"status": "succeeded"
}
],
"logTail": "... deploy complete"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"teamId": {
"type": "string"
},
"productIds": {
"type": "array",
"items": {
"type": "string"
}
},
"changeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"triggerCommit": {
"type": "object",
"properties": {
"sha": {
"type": "string",
"description": "Full or abbreviated commit SHA"
},
"subject": {
"type": "string",
"description": "Commit subject line"
},
"author": {
"type": "string",
"description": "Commit author (name or handle)"
}
},
"required": [
"sha",
"subject",
"author"
],
"description": "The commit that triggered a CD run"
},
"environment": {
"type": "string",
"enum": [
"staging",
"production"
],
"description": "CD run target environment (staging | production)"
},
"outcome": {
"type": "string",
"enum": [
"inProgress",
"shipped",
"failed",
"aborted"
],
"description": "CD run outcome (inProgress | shipped | failed | aborted)"
},
"stageTimeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this timeline entry covers"
},
"status": {
"type": "string",
"enum": [
"inProgress",
"succeeded",
"failed"
],
"description": "How this stage ended"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage started (null = start unrecorded)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage finished (null = still running / not reached)",
"nullable": true
}
},
"required": [
"stage",
"status"
],
"description": "One stage entry in a CD run timeline"
}
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"changes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "ID of the change the run carried"
},
"key": {
"type": "string",
"description": "Per-product display key, e.g. CHG-01"
},
"title": {
"type": "string",
"description": "Short title of the change"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "The kind of change work (feature | enhancement | bug)"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The change's current pipeline stage"
}
},
"required": [
"changeId",
"key",
"title",
"type",
"stage"
],
"description": "Derived summary of a tracked change carried by a CD run"
}
},
"version": {
"type": "string",
"nullable": true
},
"failingStage": {
"type": "string",
"enum": [
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "CD run pipeline stage",
"nullable": true
},
"logTail": {
"type": "string",
"nullable": true
},
"logPath": {
"type": "string",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"_id",
"teamId",
"productIds",
"changeIds",
"triggerCommit",
"environment",
"outcome",
"stageTimeline",
"startedAt",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CDRUN-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"teamId": "TEAM-716ade97-9279-4840-b030-c2f7f50e4d31",
"productIds": [
"PRODUCT-4b1655bb-95d1-4c9e-b0c2-46a9d2103957"
],
"changeIds": [
"CHANGE-1"
],
"triggerCommit": {
"sha": "dcf61092",
"subject": "feat(cd): release tracking",
"author": "Mark Abrahams"
},
"environment": "production",
"outcome": "shipped",
"stageTimeline": [],
"startedAt": "2026-07-20T10:00:00.000Z",
"finishedAt": "2026-07-20T10:06:00.000Z",
"createdAt": "2026-07-20T10:00:00.000Z",
"updatedAt": "2026-07-20T10:06:00.000Z"
}
getCdRun
Get a CD deployment run by id — its outcome, target environment, triggering commit, per-stage timeline and log tail.
Input Schema
{
"type": "object",
"properties": {
"cdRunId": {
"type": "string",
"description": "CD run ID"
}
},
"required": [
"cdRunId"
],
"description": "Get-CD-run selector"
}
Example Input
{
"cdRunId": "CDRUN-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"teamId": {
"type": "string"
},
"productIds": {
"type": "array",
"items": {
"type": "string"
}
},
"changeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"triggerCommit": {
"type": "object",
"properties": {
"sha": {
"type": "string",
"description": "Full or abbreviated commit SHA"
},
"subject": {
"type": "string",
"description": "Commit subject line"
},
"author": {
"type": "string",
"description": "Commit author (name or handle)"
}
},
"required": [
"sha",
"subject",
"author"
],
"description": "The commit that triggered a CD run"
},
"environment": {
"type": "string",
"enum": [
"staging",
"production"
],
"description": "CD run target environment (staging | production)"
},
"outcome": {
"type": "string",
"enum": [
"inProgress",
"shipped",
"failed",
"aborted"
],
"description": "CD run outcome (inProgress | shipped | failed | aborted)"
},
"stageTimeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this timeline entry covers"
},
"status": {
"type": "string",
"enum": [
"inProgress",
"succeeded",
"failed"
],
"description": "How this stage ended"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage started (null = start unrecorded)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage finished (null = still running / not reached)",
"nullable": true
}
},
"required": [
"stage",
"status"
],
"description": "One stage entry in a CD run timeline"
}
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"changes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "ID of the change the run carried"
},
"key": {
"type": "string",
"description": "Per-product display key, e.g. CHG-01"
},
"title": {
"type": "string",
"description": "Short title of the change"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "The kind of change work (feature | enhancement | bug)"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The change's current pipeline stage"
}
},
"required": [
"changeId",
"key",
"title",
"type",
"stage"
],
"description": "Derived summary of a tracked change carried by a CD run"
}
},
"version": {
"type": "string",
"nullable": true
},
"failingStage": {
"type": "string",
"enum": [
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "CD run pipeline stage",
"nullable": true
},
"logTail": {
"type": "string",
"nullable": true
},
"logPath": {
"type": "string",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"_id",
"teamId",
"productIds",
"changeIds",
"triggerCommit",
"environment",
"outcome",
"stageTimeline",
"startedAt",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CDRUN-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"teamId": "TEAM-716ade97-9279-4840-b030-c2f7f50e4d31",
"productIds": [
"PRODUCT-4b1655bb-95d1-4c9e-b0c2-46a9d2103957"
],
"changeIds": [
"CHANGE-1"
],
"triggerCommit": {
"sha": "dcf61092",
"subject": "feat(cd): release tracking",
"author": "Mark Abrahams"
},
"environment": "production",
"outcome": "shipped",
"stageTimeline": [
{
"stage": "ship",
"startedAt": "2026-07-20T10:05:00.000Z",
"finishedAt": "2026-07-20T10:06:00.000Z",
"status": "succeeded"
}
],
"startedAt": "2026-07-20T10:00:00.000Z",
"finishedAt": "2026-07-20T10:06:00.000Z",
"createdAt": "2026-07-20T10:00:00.000Z",
"updatedAt": "2026-07-20T10:06:00.000Z"
}
listCdRuns
List a team's CD deployment runs, newest first (every outcome — in progress, shipped, failed, aborted). Optionally narrow to runs that touched a given product, environment, or outcome. Returns a COMPACT SUMMARY per run: outcome, products, changes, triggering commit, environment, version, stage timeline and timings. It deliberately carries no log output — read a run's log tail from getCdRun. Results are a bounded slice and the response reports the true total so a slice is never mistaken for the whole set. This is the data behind the Deployments view.
Input Schema
{
"type": "object",
"properties": {
"teamId": {
"type": "string",
"description": "ID of the team whose runs to list"
},
"productId": {
"type": "string",
"description": "Filter to runs that deployed this product"
},
"environment": {
"type": "string",
"enum": [
"staging",
"production"
],
"description": "Filter by target environment"
},
"outcome": {
"type": "string",
"enum": [
"inProgress",
"shipped",
"failed",
"aborted"
],
"description": "Filter by outcome"
},
"limit": {
"type": "number",
"description": "Maximum runs to return, newest first (default 50). The response always reports the true total, so a smaller slice is never mistaken for the whole set."
}
},
"required": [
"teamId"
],
"description": "Parameters for listing CD runs"
}
Example Input
{
"teamId": "TEAM-716ade97-9279-4840-b030-c2f7f50e4d31"
}
Output Schema
{
"type": "object",
"properties": {
"runs": {
"type": "array",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"teamId": {
"type": "string"
},
"productIds": {
"type": "array",
"items": {
"type": "string"
}
},
"changeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"triggerCommit": {
"type": "object",
"properties": {
"sha": {
"type": "string",
"description": "Full or abbreviated commit SHA"
},
"subject": {
"type": "string",
"description": "Commit subject line"
},
"author": {
"type": "string",
"description": "Commit author (name or handle)"
}
},
"required": [
"sha",
"subject",
"author"
],
"description": "The commit that triggered a CD run"
},
"environment": {
"type": "string",
"enum": [
"staging",
"production"
],
"description": "CD run target environment (staging | production)"
},
"outcome": {
"type": "string",
"enum": [
"inProgress",
"shipped",
"failed",
"aborted"
],
"description": "CD run outcome (inProgress | shipped | failed | aborted)"
},
"stageTimeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this timeline entry covers"
},
"status": {
"type": "string",
"enum": [
"inProgress",
"succeeded",
"failed"
],
"description": "How this stage ended"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage started (null = start unrecorded)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage finished (null = still running / not reached)",
"nullable": true
}
},
"required": [
"stage",
"status"
],
"description": "One stage entry in a CD run timeline"
}
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"changes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "ID of the change the run carried"
},
"key": {
"type": "string",
"description": "Per-product display key, e.g. CHG-01"
},
"title": {
"type": "string",
"description": "Short title of the change"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "The kind of change work (feature | enhancement | bug)"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The change's current pipeline stage"
}
},
"required": [
"changeId",
"key",
"title",
"type",
"stage"
],
"description": "Derived summary of a tracked change carried by a CD run"
}
},
"version": {
"type": "string",
"nullable": true
},
"failingStage": {
"type": "string",
"enum": [
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "CD run pipeline stage",
"nullable": true
},
"logPath": {
"type": "string",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"_id",
"teamId",
"productIds",
"changeIds",
"triggerCommit",
"environment",
"outcome",
"stageTimeline",
"startedAt",
"createdAt",
"updatedAt"
]
},
"description": "The runs returned, newest first"
},
"total": {
"type": "number",
"description": "Total runs matching the filters, whether or not they were returned"
},
"limit": {
"type": "number",
"description": "Maximum number of runs this call was willing to return"
}
},
"required": [
"runs",
"total",
"limit"
],
"description": "A bounded slice of CD runs with the true total"
}
Example Output
{
"runs": [
{
"_id": "CDRUN-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"teamId": "TEAM-716ade97-9279-4840-b030-c2f7f50e4d31",
"productIds": [
"PRODUCT-4b1655bb-95d1-4c9e-b0c2-46a9d2103957"
],
"changeIds": [
"CHANGE-1"
],
"triggerCommit": {
"sha": "dcf61092",
"subject": "feat(cd): release tracking",
"author": "Mark Abrahams"
},
"environment": "production",
"outcome": "shipped",
"stageTimeline": [],
"startedAt": "2026-07-20T10:00:00.000Z",
"finishedAt": "2026-07-20T10:06:00.000Z",
"createdAt": "2026-07-20T10:00:00.000Z",
"updatedAt": "2026-07-20T10:06:00.000Z"
}
],
"total": 1,
"limit": 50
}
reportCdRunStage
Report the progress of a single stage while a CD run is in progress (one-way, best-effort ingestion from the pipeline). The stage timeline builds up during the run instead of arriving only at the terminal report. A report against an already-terminal run is ignored (the terminal report's timeline is authoritative). The app never drives the pipeline — this only records what the pipeline reports.
Input Schema
{
"type": "object",
"properties": {
"cdRunId": {
"type": "string",
"description": "CD run ID (from startCdRun)"
},
"stage": {
"type": "string",
"enum": [
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this report covers"
},
"status": {
"type": "string",
"enum": [
"inProgress",
"succeeded",
"failed"
],
"description": "This stage's status now (inProgress | succeeded | failed)"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage started (reported at stage start)"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage finished (reported at stage finish)"
}
},
"required": [
"cdRunId",
"stage",
"status"
],
"description": "Report the progress of a single stage of an in-progress CD run"
}
Example Input
{
"cdRunId": "CDRUN-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"stage": "build",
"status": "inProgress",
"startedAt": "2026-07-20T10:00:00.000Z"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"teamId": {
"type": "string"
},
"productIds": {
"type": "array",
"items": {
"type": "string"
}
},
"changeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"triggerCommit": {
"type": "object",
"properties": {
"sha": {
"type": "string",
"description": "Full or abbreviated commit SHA"
},
"subject": {
"type": "string",
"description": "Commit subject line"
},
"author": {
"type": "string",
"description": "Commit author (name or handle)"
}
},
"required": [
"sha",
"subject",
"author"
],
"description": "The commit that triggered a CD run"
},
"environment": {
"type": "string",
"enum": [
"staging",
"production"
],
"description": "CD run target environment (staging | production)"
},
"outcome": {
"type": "string",
"enum": [
"inProgress",
"shipped",
"failed",
"aborted"
],
"description": "CD run outcome (inProgress | shipped | failed | aborted)"
},
"stageTimeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this timeline entry covers"
},
"status": {
"type": "string",
"enum": [
"inProgress",
"succeeded",
"failed"
],
"description": "How this stage ended"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage started (null = start unrecorded)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage finished (null = still running / not reached)",
"nullable": true
}
},
"required": [
"stage",
"status"
],
"description": "One stage entry in a CD run timeline"
}
},
"startedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"changes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "ID of the change the run carried"
},
"key": {
"type": "string",
"description": "Per-product display key, e.g. CHG-01"
},
"title": {
"type": "string",
"description": "Short title of the change"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "The kind of change work (feature | enhancement | bug)"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The change's current pipeline stage"
}
},
"required": [
"changeId",
"key",
"title",
"type",
"stage"
],
"description": "Derived summary of a tracked change carried by a CD run"
}
},
"version": {
"type": "string",
"nullable": true
},
"failingStage": {
"type": "string",
"enum": [
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "CD run pipeline stage",
"nullable": true
},
"logTail": {
"type": "string",
"nullable": true
},
"logPath": {
"type": "string",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"_id",
"teamId",
"productIds",
"changeIds",
"triggerCommit",
"environment",
"outcome",
"stageTimeline",
"startedAt",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CDRUN-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"teamId": "TEAM-716ade97-9279-4840-b030-c2f7f50e4d31",
"productIds": [
"PRODUCT-4b1655bb-95d1-4c9e-b0c2-46a9d2103957"
],
"changeIds": [
"CHANGE-1"
],
"triggerCommit": {
"sha": "dcf61092",
"subject": "feat(cd): release tracking",
"author": "Mark Abrahams"
},
"environment": "production",
"outcome": "inProgress",
"stageTimeline": [
{
"stage": "build",
"startedAt": "2026-07-20T10:00:00.000Z",
"finishedAt": null,
"status": "inProgress"
}
],
"startedAt": "2026-07-20T10:00:00.000Z",
"createdAt": "2026-07-20T10:00:00.000Z",
"updatedAt": "2026-07-20T10:00:00.000Z"
}
startCdRun
Report the start of a CD deployment run (one-way, best-effort ingestion from the pipeline). Creates the run in progress; as a side effect the server reconciles any prior dangling in-progress run for the team to aborted. The app never drives the pipeline — this only records what the pipeline reports.
Input Schema
{
"type": "object",
"properties": {
"teamId": {
"type": "string",
"description": "ID of the team that owns this run"
},
"productIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Products this run deploys"
},
"triggerCommit": {
"type": "object",
"properties": {
"sha": {
"type": "string",
"description": "Full or abbreviated commit SHA"
},
"subject": {
"type": "string",
"description": "Commit subject line"
},
"author": {
"type": "string",
"description": "Commit author (name or handle)"
}
},
"required": [
"sha",
"subject",
"author"
],
"description": "The commit that triggered the run"
},
"environment": {
"type": "string",
"enum": [
"staging",
"production"
],
"description": "Target environment (staging | production)"
},
"changeIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tracked changes attempted in this run (range ∩ Change: trailer)"
}
},
"required": [
"teamId",
"productIds",
"triggerCommit",
"environment"
],
"description": "Report the start of a CD run"
}
Example Input
{
"teamId": "TEAM-716ade97-9279-4840-b030-c2f7f50e4d31",
"productIds": [
"PRODUCT-4b1655bb-95d1-4c9e-b0c2-46a9d2103957"
],
"changeIds": [
"CHANGE-1",
"CHANGE-2"
],
"triggerCommit": {
"sha": "dcf61092",
"subject": "feat(cd): release tracking",
"author": "Mark Abrahams"
},
"environment": "production"
}
Output Schema
{
"type": "object",
"properties": {
"cdRunId": {
"type": "string",
"description": "CD run ID"
}
},
"required": [
"cdRunId"
],
"description": "CD run selector"
}
Example Output
{
"cdRunId": "CDRUN-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
change(18 tools)
assessChangeRisk
Score a change against the risk rubric and record the assessment.
Give severity, occurrence and detection on the 1-10 ordinal scales, each with the evidence behind it — an axis without evidence is rejected, because an unsupported score is not an assessment. Detection is INVERTED: 1 means certain to be caught before a customer sees it, 10 means silent.
You do NOT supply the category. It is derived from the vector by a severity-weighted lookup and returned on the change; supplying one is rejected. The only way to move the category is to move an axis and evidence it.
Before scoring, perform the lookups the rubric mandates: enumerate what the change touches (and whether any of it is billing, authentication, authorisation or tenant isolation) for severity; find the prior art and check docs/rules and the incident record for the failure pattern for occurrence; run coverage over the changed paths and name the test that would fail — or state that none exists — for detection. Scoring occurrence LOW because the subsystem is unfamiliar is the classic error: unfamiliarity is an argument for a HIGH occurrence.
For a change involving a database migration, use overlay "dbm" and declare both writeSet and sideEffects. Empty arrays are permitted but must be stated explicitly. Reversibility is then DERIVED from those declarations and overrides your authored value unless you record a justification; both values are kept.
Re-assess freely as the change progresses — the current assessment is replaced and the full history is kept in the change event trail. Assessing never moves the change through its pipeline and never disturbs recorded stage times.
Re-assessing is also safe for the change's pipeline confirmation, in one direction only. A score that RAISES the category out of an auto-confirmed band clears the confirmation, so the record never states an oversight level the current assessment contradicts, and a fresh confirmation is then required. A score that LOWERS it leaves the stricter confirmation standing and does not auto-confirm the lighter band: an agent does not reduce oversight below an explicit human choice, so a fall is a proposal a person accepts by calling confirmChangePipeline. The trail records that the lighter selection was held rather than applied.
Input Schema
{
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"changeId": {
"type": "string",
"description": "Change ID"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"note": {
"type": "string",
"description": "Optional note (lands in the change's event trail)"
},
"overrideFrozen": {
"type": "boolean",
"description": "Override the shipped-record freeze for THIS CALL ONLY, to correct a record that is wrong. Requires a signed-in team owner or administrator: every API-key-authenticated caller is refused whatever its scope, because no key scope distinguishes a person's credentials from the delivery pipeline's own — and the pipeline must never be able to correct a record it wrote. Never persists: the record is frozen again the moment the call returns."
},
"overrideReason": {
"type": "string",
"description": "Why the shipped record is being corrected. REQUIRED whenever overrideFrozen is set, and recorded permanently in the change's event trail alongside the identity that performed the override, so a correction to the historical record is never silent."
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"changeId"
],
"description": "Parameters for recording a change risk assessment. Score the axes against the rubric; the category is derived, not supplied."
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"overlay": "dbm",
"severity": 7,
"severityEvidence": "Writes userStory.surface across every team. A wrong value routes stories to the wrong test generator, breaking a core workflow for a subset of customers. Touches no billing, auth or tenancy.",
"occurrence": 5,
"occurrenceEvidence": "Single-collection field write behind a non-trivial predicate. Two comparable backfills in this repo; docs/rules and the incident record carry nothing on this pattern.",
"detection": 8,
"detectionEvidence": "No test asserts the post-state. Coverage over the migration path is zero; a wrong value is visible only by querying userStory directly.",
"doNothingSeverity": 5,
"doNothingSeverityEvidence": "Surface stays unset, and the ambiguity keeps costing time on every generation run.",
"authoredReversibility": "reversible",
"writeSet": [
{
"collection": "userStory",
"operation": "setField",
"fieldLevel": true,
"preImageCaptured": false
}
],
"sideEffects": [],
"note": "Scored at the end of code, with the diff in hand"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"stamps": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When work on this stage first started (null = start unrecorded)",
"nullable": true
},
"startedAtSource": {
"type": "string",
"enum": [
"reported",
"correctedManually",
"recoveredFromEvent",
"derivedFromPreviousStage"
],
"description": "How startedAt was obtained (null = the stamp pre-dates this field, which is not a claim that it was measured)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage was first finished",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage, as reported by the caller (null = not reported, which is never inferred from configuration)",
"nullable": true
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "The authenticated identity that performed the stage action (server-observed, never caller-supplied; first report wins)",
"nullable": true
}
},
"description": "First-entry start/finish stamps for a stage, who drove it, and the identity that performed it"
},
"description": "Per-stage first-entry stamps, keyed by stage (only stamped stages present)"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"intent": {
"type": "string"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"stampLedger": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage this commit drove"
},
"sha": {
"type": "string",
"description": "The commit sha that drove it"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage started (absent if it never did)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage finished (absent if it never did)",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who the report attested was driving; absent when the report named none",
"nullable": true
}
},
"required": [
"stage",
"sha"
],
"description": "One commit's record of driving one stage: which stage, which commit, and when it reported the start and the finish"
},
"description": "Append-only record of which commit drove which stage and when; never cleared by a rework jump-back",
"nullable": true
},
"shipCorrectedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"design": {
"type": "string",
"nullable": true
},
"designDocPath": {
"type": "string",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"riskAssessment": {
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"effectiveReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"assessedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"derivedReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"assessedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"effectiveReversibility",
"category",
"assessedAt",
"revision"
],
"description": "A change's current risk assessment",
"nullable": true
},
"confirmedPipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each",
"nullable": true
},
"confirmedPipelineCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"confirmedPipelineAuthoritative": {
"type": "boolean",
"nullable": true
},
"effectivePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
},
"effectivePipelineSource": {
"type": "string",
"enum": [
"confirmed",
"assessed",
"configuration"
],
"description": "Where the pipeline in force for a change came from (confirmed | assessed | configuration)"
},
"defect": {
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"classifiedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedInChangeId": {
"type": "string",
"description": "The change that introduced the defect. Server-derived from the commit's Change: trailer — not supplied by the caller.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"dormancyDays": {
"type": "number",
"nullable": true
},
"classifiedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"classifiedAt",
"revision"
],
"description": "The defect a Fix change repaired — the realised counterpart of the change risk assessment",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"introducedInChange": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Display key of the referenced change, e.g. CHG-42"
},
"productSlug": {
"type": "string",
"description": "Slug of the product owning the referenced change; absent where that product has no slug",
"nullable": true
}
},
"required": [
"key"
],
"description": "Derived reference to another change, resolved from a stored change id"
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"stamps",
"isCancelled",
"source",
"intent",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-01",
"title": "Backfill user story surface",
"type": "chore",
"stage": "code",
"stageState": "completed",
"isCancelled": false,
"source": "internal",
"intent": "Default every story's surface so test generation stops guessing.",
"riskAssessment": {
"overlay": "dbm",
"severity": 7,
"occurrence": 5,
"detection": 8,
"authoredReversibility": "reversible",
"derivedReversibility": "irreversible",
"effectiveReversibility": "irreversible",
"category": "high",
"revision": 1
},
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-14T08:00:00.000Z"
}
cancelChange
Cancel a change (change-level). The position is preserved — a later reopenChange resumes exactly where it stopped. Any in-progress stage work is cancelled with it. The first cancellation stamps cancelledAt permanently. Shipped (frozen) changes cannot be cancelled. Emits changeCancelled.
Input Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
},
"note": {
"type": "string",
"description": "Optional note (lands in the change's event trail)"
},
"overrideFrozen": {
"type": "boolean",
"description": "Override the shipped-record freeze for THIS CALL ONLY, to correct a record that is wrong. Requires a signed-in team owner or administrator: every API-key-authenticated caller is refused whatever its scope, because no key scope distinguishes a person's credentials from the delivery pipeline's own — and the pipeline must never be able to correct a record it wrote. Never persists: the record is frozen again the moment the call returns."
},
"overrideReason": {
"type": "string",
"description": "Why the shipped record is being corrected. REQUIRED whenever overrideFrozen is set, and recorded permanently in the change's event trail alongside the identity that performed the override, so a correction to the historical record is never silent."
}
},
"required": [
"changeId"
],
"description": "Parameters for cancelling a change (change-level; position is preserved for a later reopen)"
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"note": "superseded by the v2 platform plan"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"stamps": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When work on this stage first started (null = start unrecorded)",
"nullable": true
},
"startedAtSource": {
"type": "string",
"enum": [
"reported",
"correctedManually",
"recoveredFromEvent",
"derivedFromPreviousStage"
],
"description": "How startedAt was obtained (null = the stamp pre-dates this field, which is not a claim that it was measured)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage was first finished",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage, as reported by the caller (null = not reported, which is never inferred from configuration)",
"nullable": true
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "The authenticated identity that performed the stage action (server-observed, never caller-supplied; first report wins)",
"nullable": true
}
},
"description": "First-entry start/finish stamps for a stage, who drove it, and the identity that performed it"
},
"description": "Per-stage first-entry stamps, keyed by stage (only stamped stages present)"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"intent": {
"type": "string"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"stampLedger": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage this commit drove"
},
"sha": {
"type": "string",
"description": "The commit sha that drove it"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage started (absent if it never did)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage finished (absent if it never did)",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who the report attested was driving; absent when the report named none",
"nullable": true
}
},
"required": [
"stage",
"sha"
],
"description": "One commit's record of driving one stage: which stage, which commit, and when it reported the start and the finish"
},
"description": "Append-only record of which commit drove which stage and when; never cleared by a rework jump-back",
"nullable": true
},
"shipCorrectedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"design": {
"type": "string",
"nullable": true
},
"designDocPath": {
"type": "string",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"riskAssessment": {
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"effectiveReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"assessedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"derivedReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"assessedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"effectiveReversibility",
"category",
"assessedAt",
"revision"
],
"description": "A change's current risk assessment",
"nullable": true
},
"confirmedPipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each",
"nullable": true
},
"confirmedPipelineCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"confirmedPipelineAuthoritative": {
"type": "boolean",
"nullable": true
},
"effectivePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
},
"effectivePipelineSource": {
"type": "string",
"enum": [
"confirmed",
"assessed",
"configuration"
],
"description": "Where the pipeline in force for a change came from (confirmed | assessed | configuration)"
},
"defect": {
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"classifiedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedInChangeId": {
"type": "string",
"description": "The change that introduced the defect. Server-derived from the commit's Change: trailer — not supplied by the caller.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"dormancyDays": {
"type": "number",
"nullable": true
},
"classifiedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"classifiedAt",
"revision"
],
"description": "The defect a Fix change repaired — the realised counterpart of the change risk assessment",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"introducedInChange": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Display key of the referenced change, e.g. CHG-42"
},
"productSlug": {
"type": "string",
"description": "Slug of the product owning the referenced change; absent where that product has no slug",
"nullable": true
}
},
"required": [
"key"
],
"description": "Derived reference to another change, resolved from a stored change id"
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"stamps",
"isCancelled",
"source",
"intent",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-01",
"title": "Bulk CSV export",
"type": "feature",
"stage": "code",
"stageState": "notStarted",
"stamps": {
"accept": {
"startedAt": "2026-06-12T00:00:00.000Z",
"finishedAt": "2026-06-12T00:00:00.000Z"
}
},
"isCancelled": true,
"cancelledAt": "2026-06-14T00:00:00.000Z",
"source": "external",
"intent": "Customers need to export their story list as CSV.",
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-14T00:00:00.000Z"
}
cancelChangeStage
Cancel in-progress stage work without finishing it — the stage returns to not started and the working actor is cleared; the change stays alive at the same position. The escape valve for a crashed agent or a human pulled away. Emits changeStageCancelled.
Input Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
},
"note": {
"type": "string",
"description": "Optional note (lands in the change's event trail)"
},
"overrideFrozen": {
"type": "boolean",
"description": "Override the shipped-record freeze for THIS CALL ONLY, to correct a record that is wrong. Requires a signed-in team owner or administrator: every API-key-authenticated caller is refused whatever its scope, because no key scope distinguishes a person's credentials from the delivery pipeline's own — and the pipeline must never be able to correct a record it wrote. Never persists: the record is frozen again the moment the call returns."
},
"overrideReason": {
"type": "string",
"description": "Why the shipped record is being corrected. REQUIRED whenever overrideFrozen is set, and recorded permanently in the change's event trail alongside the identity that performed the override, so a correction to the historical record is never silent."
}
},
"required": [
"changeId"
],
"description": "Parameters for cancelling in-progress stage work (the stage returns to not started; the change stays alive)"
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"note": "agent session crashed mid-review"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"stamps": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When work on this stage first started (null = start unrecorded)",
"nullable": true
},
"startedAtSource": {
"type": "string",
"enum": [
"reported",
"correctedManually",
"recoveredFromEvent",
"derivedFromPreviousStage"
],
"description": "How startedAt was obtained (null = the stamp pre-dates this field, which is not a claim that it was measured)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage was first finished",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage, as reported by the caller (null = not reported, which is never inferred from configuration)",
"nullable": true
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "The authenticated identity that performed the stage action (server-observed, never caller-supplied; first report wins)",
"nullable": true
}
},
"description": "First-entry start/finish stamps for a stage, who drove it, and the identity that performed it"
},
"description": "Per-stage first-entry stamps, keyed by stage (only stamped stages present)"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"intent": {
"type": "string"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"stampLedger": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage this commit drove"
},
"sha": {
"type": "string",
"description": "The commit sha that drove it"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage started (absent if it never did)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage finished (absent if it never did)",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who the report attested was driving; absent when the report named none",
"nullable": true
}
},
"required": [
"stage",
"sha"
],
"description": "One commit's record of driving one stage: which stage, which commit, and when it reported the start and the finish"
},
"description": "Append-only record of which commit drove which stage and when; never cleared by a rework jump-back",
"nullable": true
},
"shipCorrectedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"design": {
"type": "string",
"nullable": true
},
"designDocPath": {
"type": "string",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"riskAssessment": {
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"effectiveReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"assessedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"derivedReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"assessedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"effectiveReversibility",
"category",
"assessedAt",
"revision"
],
"description": "A change's current risk assessment",
"nullable": true
},
"confirmedPipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each",
"nullable": true
},
"confirmedPipelineCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"confirmedPipelineAuthoritative": {
"type": "boolean",
"nullable": true
},
"effectivePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
},
"effectivePipelineSource": {
"type": "string",
"enum": [
"confirmed",
"assessed",
"configuration"
],
"description": "Where the pipeline in force for a change came from (confirmed | assessed | configuration)"
},
"defect": {
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"classifiedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedInChangeId": {
"type": "string",
"description": "The change that introduced the defect. Server-derived from the commit's Change: trailer — not supplied by the caller.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"dormancyDays": {
"type": "number",
"nullable": true
},
"classifiedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"classifiedAt",
"revision"
],
"description": "The defect a Fix change repaired — the realised counterpart of the change risk assessment",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"introducedInChange": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Display key of the referenced change, e.g. CHG-42"
},
"productSlug": {
"type": "string",
"description": "Slug of the product owning the referenced change; absent where that product has no slug",
"nullable": true
}
},
"required": [
"key"
],
"description": "Derived reference to another change, resolved from a stored change id"
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"stamps",
"isCancelled",
"source",
"intent",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-01",
"title": "Bulk CSV export",
"type": "feature",
"stage": "review",
"stageState": "notStarted",
"stamps": {
"accept": {
"startedAt": "2026-06-12T00:00:00.000Z",
"finishedAt": "2026-06-12T00:00:00.000Z"
},
"review": {
"startedAt": "2026-06-14T00:00:00.000Z"
}
},
"isCancelled": false,
"source": "external",
"intent": "Customers need to export their story list as CSV.",
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-14T01:00:00.000Z"
}
confirmChangePipeline
Freeze onto the change, in full, the pipeline it runs under — every stage, whether it is enabled, and who drives it — together with the risk category that selected it.
You do NOT supply the category, and you do NOT supply the pipeline. The category is read from the change's own current risk assessment and the pipeline is resolved from it; a change with no assessment is rejected, because there is nothing to resolve from. Assess first, then confirm.
The record is deliberately self-contained rather than a reference to configuration: it must still name the pipeline this change was SELECTED for after the repository's configuration has been edited. It is not a record of what oversight the change actually received — that is answered per stage by the driver reported when the stage was stamped.
Automation never lowers it. A re-assessment that falls below a band already confirmed leaves the stricter confirmation standing rather than replacing it, because an agent does not reduce oversight below an explicit human choice. Calling this tool, by contrast, always applies the change's current category — that is how a human accepts a proposed reduction.
You may pass per-stage driver overrides ONLY where the change's repository sets allowConfirmedPipelineOverride. Where it does not, supplying them is rejected rather than quietly ignored, so you never believe you confirmed a pipeline you did not. Overrides target judgement stages only (design, define, code, test, review, merge, push) and may set human or agent, never cicd.
Where a repository auto-confirms a band — low, unless it says otherwise — the pipeline is already confirmed as part of recording the assessment, and calling this is unnecessary for changes in that band.
Re-confirm freely while the change is in flight: the record is replaced and the full history is kept in the change event trail. Confirming never moves the change through its pipeline and never disturbs recorded stage times.
Whether the confirmed pipeline then GOVERNS the change is the repository's decision, not this call's: where the repo grants confirmed pipelines authority, the change runs under this pipeline and a later configuration edit cannot reach it; where it does not, the confirmation is recorded and drives nothing. Read effectivePipelineSource on the change to see which applies rather than inferring it.
Input Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
},
"overrides": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The judgement stage this override targets"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives that stage for this change (human or agent)"
}
},
"required": [
"stage",
"driver"
],
"description": "A confirmation-time driver override for one judgement stage"
},
"description": "Optional per-stage driver deviations from the category's pipeline. Only accepted when the change's repository sets allowConfirmedPipelineOverride; supplying them otherwise is rejected rather than ignored."
},
"note": {
"type": "string",
"description": "Optional note (lands in the change's event trail)"
},
"overrideFrozen": {
"type": "boolean",
"description": "Override the shipped-record freeze for THIS CALL ONLY, to correct a record that is wrong. Requires a signed-in team owner or administrator: every API-key-authenticated caller is refused whatever its scope, because no key scope distinguishes a person's credentials from the delivery pipeline's own — and the pipeline must never be able to correct a record it wrote. Never persists: the record is frozen again the moment the call returns."
},
"overrideReason": {
"type": "string",
"description": "Why the shipped record is being corrected. REQUIRED whenever overrideFrozen is set, and recorded permanently in the change's event trail alongside the identity that performed the override, so a correction to the historical record is never silent."
}
},
"required": [
"changeId"
],
"description": "Parameters for confirming the pipeline a change runs under. The category comes from the change's own assessment and the pipeline is resolved from it; neither is supplied."
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"note": "Confirmed at the accept boundary, with the assessment in hand"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"stamps": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When work on this stage first started (null = start unrecorded)",
"nullable": true
},
"startedAtSource": {
"type": "string",
"enum": [
"reported",
"correctedManually",
"recoveredFromEvent",
"derivedFromPreviousStage"
],
"description": "How startedAt was obtained (null = the stamp pre-dates this field, which is not a claim that it was measured)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage was first finished",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage, as reported by the caller (null = not reported, which is never inferred from configuration)",
"nullable": true
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "The authenticated identity that performed the stage action (server-observed, never caller-supplied; first report wins)",
"nullable": true
}
},
"description": "First-entry start/finish stamps for a stage, who drove it, and the identity that performed it"
},
"description": "Per-stage first-entry stamps, keyed by stage (only stamped stages present)"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"intent": {
"type": "string"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"stampLedger": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage this commit drove"
},
"sha": {
"type": "string",
"description": "The commit sha that drove it"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage started (absent if it never did)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage finished (absent if it never did)",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who the report attested was driving; absent when the report named none",
"nullable": true
}
},
"required": [
"stage",
"sha"
],
"description": "One commit's record of driving one stage: which stage, which commit, and when it reported the start and the finish"
},
"description": "Append-only record of which commit drove which stage and when; never cleared by a rework jump-back",
"nullable": true
},
"shipCorrectedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"design": {
"type": "string",
"nullable": true
},
"designDocPath": {
"type": "string",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"riskAssessment": {
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"effectiveReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"assessedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"derivedReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"assessedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"effectiveReversibility",
"category",
"assessedAt",
"revision"
],
"description": "A change's current risk assessment",
"nullable": true
},
"confirmedPipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each",
"nullable": true
},
"confirmedPipelineCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"confirmedPipelineAuthoritative": {
"type": "boolean",
"nullable": true
},
"effectivePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
},
"effectivePipelineSource": {
"type": "string",
"enum": [
"confirmed",
"assessed",
"configuration"
],
"description": "Where the pipeline in force for a change came from (confirmed | assessed | configuration)"
},
"defect": {
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"classifiedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedInChangeId": {
"type": "string",
"description": "The change that introduced the defect. Server-derived from the commit's Change: trailer — not supplied by the caller.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"dormancyDays": {
"type": "number",
"nullable": true
},
"classifiedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"classifiedAt",
"revision"
],
"description": "The defect a Fix change repaired — the realised counterpart of the change risk assessment",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"introducedInChange": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Display key of the referenced change, e.g. CHG-42"
},
"productSlug": {
"type": "string",
"description": "Slug of the product owning the referenced change; absent where that product has no slug",
"nullable": true
}
},
"required": [
"key"
],
"description": "Derived reference to another change, resolved from a stored change id"
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"stamps",
"isCancelled",
"source",
"intent",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-01",
"title": "Backfill user story surface",
"type": "chore",
"stage": "accept",
"stageState": "completed",
"isCancelled": false,
"source": "internal",
"intent": "Default every story's surface so test generation stops guessing.",
"confirmedPipelineCategory": "high",
"confirmedPipeline": [
{
"stage": "accept",
"enabled": true,
"driver": "human"
},
{
"stage": "design",
"enabled": true,
"driver": "human"
},
{
"stage": "code",
"enabled": true,
"driver": "agent"
},
{
"stage": "review",
"enabled": true,
"driver": "human"
},
{
"stage": "ship",
"enabled": true,
"driver": "cicd"
}
],
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-14T08:00:00.000Z"
}
createChange
Create a new change record. Creating a change is the accept gate: the record enters the pipeline with acceptance completed. Origin is an external reference (e.g. a JIRA key or brain intent), never a DefProd entity. An externally-sourced change whose origin is already carried by an ACTIVE change is rejected (duplicate promotion); a cancelled predecessor suggests reopenChange; shipped predecessors do not block.
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
},
"title": {
"type": "string",
"description": "Short title of the change"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type (feature | enhancement | bug)"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Provenance: external (came from outside the team) or internal"
},
"intent": {
"type": "string",
"description": "Markdown — what we are changing and why (the accepted decision)"
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference, e.g. {system: 'jira', ref: 'PROJ-123', url: '…'}"
},
"design": {
"type": "string",
"description": "Markdown — frozen inline design (optional; skippable like the designed state)"
},
"designDocPath": {
"type": "string",
"description": "Pointer to a living design doc maintained outside the record"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Forward links to in-scope user story IDs"
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Forward links to implementation pull requests"
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Cross-links to sibling changes in other products of the same team"
}
},
"required": [
"productId",
"title",
"type",
"source",
"intent"
],
"description": "Create change request"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"title": "Bulk CSV export",
"type": "feature",
"source": "external",
"intent": "Customers need to export their story list as CSV for offline review.",
"origin": {
"system": "jira",
"ref": "PROJ-123",
"url": "https://example.atlassian.net/browse/PROJ-123"
}
}
Output Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
}
},
"required": [
"changeId"
],
"description": "Change selector"
}
Example Output
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
deleteChange
Delete a change record. Shipped changes are frozen and cannot be deleted — use cancelChange for cancelled work; delete is for records that should never have existed.
Input Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
},
"overrideFrozen": {
"type": "boolean",
"description": "Override the shipped-record freeze for THIS CALL ONLY, to correct a record that is wrong. Requires a signed-in team owner or administrator: every API-key-authenticated caller is refused whatever its scope, because no key scope distinguishes a person's credentials from the delivery pipeline's own — and the pipeline must never be able to correct a record it wrote. Never persists: the record is frozen again the moment the call returns."
},
"overrideReason": {
"type": "string",
"description": "Why the shipped record is being corrected. REQUIRED whenever overrideFrozen is set, and recorded permanently in the change's event trail alongside the identity that performed the override, so a correction to the historical record is never silent."
}
},
"required": [
"changeId"
],
"description": "Parameters for deleting a change"
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {},
"description": "This operation returns no data; the response carries only the envelope meta."
}
failChangeStage
Report in-progress stage work as failed — the stage is recorded as failed rather than returned to not started, so an attempt that did not succeed is never mistaken for one that never began. The change stays alive at the same position and can be retried by starting the stage again. The counterpart to cancelChangeStage, which is for deliberate abandonment. Emits changeStageFailed.
Input Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
},
"note": {
"type": "string",
"description": "Why the stage failed — lands in the change's event trail (e.g. the aborting stage, exit code and reason)"
},
"overrideFrozen": {
"type": "boolean",
"description": "Override the shipped-record freeze for THIS CALL ONLY, to correct a record that is wrong. Requires a signed-in team owner or administrator: every API-key-authenticated caller is refused whatever its scope, because no key scope distinguishes a person's credentials from the delivery pipeline's own — and the pipeline must never be able to correct a record it wrote. Never persists: the record is frozen again the moment the call returns."
},
"overrideReason": {
"type": "string",
"description": "Why the shipped record is being corrected. REQUIRED whenever overrideFrozen is set, and recorded permanently in the change's event trail alongside the identity that performed the override, so a correction to the historical record is never silent."
}
},
"required": [
"changeId"
],
"description": "Parameters for reporting in-progress stage work as failed (the stage is recorded as failed, not returned to not started; the change stays alive and can be retried)"
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"note": "cd.sh aborted during 'package' (exit 1)"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"stamps": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When work on this stage first started (null = start unrecorded)",
"nullable": true
},
"startedAtSource": {
"type": "string",
"enum": [
"reported",
"correctedManually",
"recoveredFromEvent",
"derivedFromPreviousStage"
],
"description": "How startedAt was obtained (null = the stamp pre-dates this field, which is not a claim that it was measured)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage was first finished",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage, as reported by the caller (null = not reported, which is never inferred from configuration)",
"nullable": true
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "The authenticated identity that performed the stage action (server-observed, never caller-supplied; first report wins)",
"nullable": true
}
},
"description": "First-entry start/finish stamps for a stage, who drove it, and the identity that performed it"
},
"description": "Per-stage first-entry stamps, keyed by stage (only stamped stages present)"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"intent": {
"type": "string"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"stampLedger": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage this commit drove"
},
"sha": {
"type": "string",
"description": "The commit sha that drove it"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage started (absent if it never did)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage finished (absent if it never did)",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who the report attested was driving; absent when the report named none",
"nullable": true
}
},
"required": [
"stage",
"sha"
],
"description": "One commit's record of driving one stage: which stage, which commit, and when it reported the start and the finish"
},
"description": "Append-only record of which commit drove which stage and when; never cleared by a rework jump-back",
"nullable": true
},
"shipCorrectedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"design": {
"type": "string",
"nullable": true
},
"designDocPath": {
"type": "string",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"riskAssessment": {
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"effectiveReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"assessedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"derivedReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"assessedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"effectiveReversibility",
"category",
"assessedAt",
"revision"
],
"description": "A change's current risk assessment",
"nullable": true
},
"confirmedPipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each",
"nullable": true
},
"confirmedPipelineCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"confirmedPipelineAuthoritative": {
"type": "boolean",
"nullable": true
},
"effectivePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
},
"effectivePipelineSource": {
"type": "string",
"enum": [
"confirmed",
"assessed",
"configuration"
],
"description": "Where the pipeline in force for a change came from (confirmed | assessed | configuration)"
},
"defect": {
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"classifiedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedInChangeId": {
"type": "string",
"description": "The change that introduced the defect. Server-derived from the commit's Change: trailer — not supplied by the caller.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"dormancyDays": {
"type": "number",
"nullable": true
},
"classifiedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"classifiedAt",
"revision"
],
"description": "The defect a Fix change repaired — the realised counterpart of the change risk assessment",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"introducedInChange": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Display key of the referenced change, e.g. CHG-42"
},
"productSlug": {
"type": "string",
"description": "Slug of the product owning the referenced change; absent where that product has no slug",
"nullable": true
}
},
"required": [
"key"
],
"description": "Derived reference to another change, resolved from a stored change id"
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"stamps",
"isCancelled",
"source",
"intent",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-01",
"title": "Bulk CSV export",
"type": "feature",
"stage": "package",
"stageState": "failed",
"stamps": {
"accept": {
"startedAt": "2026-06-12T00:00:00.000Z",
"finishedAt": "2026-06-12T00:00:00.000Z"
},
"package": {
"startedAt": "2026-06-14T00:00:00.000Z"
}
},
"isCancelled": false,
"source": "external",
"intent": "Customers need to export their story list as CSV.",
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-14T01:00:00.000Z"
}
finishChangeStage
Finish a pipeline stage. Omit `stage` and the server finishes the stage currently in progress (or, if idle, the next enabled stage). The caller reports the fact ("review is done") — the backend owns the workflow. Finishing an unstarted stage is legal (startedAt stays null = start unrecorded). Stamps the first-entry finishedAt; finishing `ship` freezes the record permanently; emits changeStageFinished.
Optionally report `driver` — who actually drove this stage — on the same terms as startChangeStage. It is accepted here as well as there because a stage whose start was never reported (a CI-stamped stage, for one) would otherwise have no way to record one. The first report wins, so a driver already recorded at the start is not overwritten.
Input Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Stage to finish. Omitted → the stage currently in progress, or the next enabled stage if idle. Explicit finishes that stage even if its start was never reported."
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage (human | agent | cicd). A fact report, not validated against the configured pipeline — a per-run driver override legitimately deviates from it. First report wins, like the stage times. Omitted → the stage records no driver; it is never inferred from configuration."
},
"stageCeilings": {
"type": "array",
"items": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"description": "The ceilings declared by the commits that correlated this change, each from a commit's `Change: <slug>/CHG-NN:<stage>` trailer. The stamp proceeds if ANY of them entitles the reported stage; a report beyond ALL of them is recorded as having had no effect — the change is neither advanced to the reported stage nor moved back to a ceiling. Omit entirely when any correlated commit carried no suffix, which means that commit delivers the change in full: the default and majority case. A SET rather than one value because a deploy range routinely carries several commits for one change — a design commit and the landing commit often ship together, and the landing is what entitles the ship."
},
"commitSha": {
"type": "string",
"description": "The commit this report is derived from. Idempotency key: the same commit never advances the same stage of the same change twice, however many times a deploy range re-includes it. Omitted means the report is not attributable to a commit and is not de-duplicated."
},
"note": {
"type": "string",
"description": "Optional note (lands in the change's event trail)"
},
"overrideFrozen": {
"type": "boolean",
"description": "Override the shipped-record freeze for THIS CALL ONLY, to correct a record that is wrong. Requires a signed-in team owner or administrator: every API-key-authenticated caller is refused whatever its scope, because no key scope distinguishes a person's credentials from the delivery pipeline's own — and the pipeline must never be able to correct a record it wrote. Never persists: the record is frozen again the moment the call returns."
},
"overrideReason": {
"type": "string",
"description": "Why the shipped record is being corrected. REQUIRED whenever overrideFrozen is set, and recorded permanently in the change's event trail alongside the identity that performed the override, so a correction to the historical record is never silent."
}
},
"required": [
"changeId"
],
"description": "Parameters for finishing a pipeline stage"
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"stage": "test",
"note": "e2e suite green"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"stamps": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When work on this stage first started (null = start unrecorded)",
"nullable": true
},
"startedAtSource": {
"type": "string",
"enum": [
"reported",
"correctedManually",
"recoveredFromEvent",
"derivedFromPreviousStage"
],
"description": "How startedAt was obtained (null = the stamp pre-dates this field, which is not a claim that it was measured)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage was first finished",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage, as reported by the caller (null = not reported, which is never inferred from configuration)",
"nullable": true
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "The authenticated identity that performed the stage action (server-observed, never caller-supplied; first report wins)",
"nullable": true
}
},
"description": "First-entry start/finish stamps for a stage, who drove it, and the identity that performed it"
},
"description": "Per-stage first-entry stamps, keyed by stage (only stamped stages present)"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"intent": {
"type": "string"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"stampLedger": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage this commit drove"
},
"sha": {
"type": "string",
"description": "The commit sha that drove it"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage started (absent if it never did)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage finished (absent if it never did)",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who the report attested was driving; absent when the report named none",
"nullable": true
}
},
"required": [
"stage",
"sha"
],
"description": "One commit's record of driving one stage: which stage, which commit, and when it reported the start and the finish"
},
"description": "Append-only record of which commit drove which stage and when; never cleared by a rework jump-back",
"nullable": true
},
"shipCorrectedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"design": {
"type": "string",
"nullable": true
},
"designDocPath": {
"type": "string",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"riskAssessment": {
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"effectiveReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"assessedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"derivedReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"assessedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"effectiveReversibility",
"category",
"assessedAt",
"revision"
],
"description": "A change's current risk assessment",
"nullable": true
},
"confirmedPipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each",
"nullable": true
},
"confirmedPipelineCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"confirmedPipelineAuthoritative": {
"type": "boolean",
"nullable": true
},
"effectivePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
},
"effectivePipelineSource": {
"type": "string",
"enum": [
"confirmed",
"assessed",
"configuration"
],
"description": "Where the pipeline in force for a change came from (confirmed | assessed | configuration)"
},
"defect": {
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"classifiedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedInChangeId": {
"type": "string",
"description": "The change that introduced the defect. Server-derived from the commit's Change: trailer — not supplied by the caller.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"dormancyDays": {
"type": "number",
"nullable": true
},
"classifiedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"classifiedAt",
"revision"
],
"description": "The defect a Fix change repaired — the realised counterpart of the change risk assessment",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"introducedInChange": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Display key of the referenced change, e.g. CHG-42"
},
"productSlug": {
"type": "string",
"description": "Slug of the product owning the referenced change; absent where that product has no slug",
"nullable": true
}
},
"required": [
"key"
],
"description": "Derived reference to another change, resolved from a stored change id"
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"stamps",
"isCancelled",
"source",
"intent",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-01",
"title": "Bulk CSV export",
"type": "feature",
"stage": "test",
"stageState": "completed",
"stamps": {
"accept": {
"startedAt": "2026-06-12T00:00:00.000Z",
"finishedAt": "2026-06-12T00:00:00.000Z"
},
"test": {
"startedAt": "2026-06-13T22:00:00.000Z",
"finishedAt": "2026-06-14T00:00:00.000Z"
}
},
"isCancelled": false,
"source": "external",
"intent": "Customers need to export their story list as CSV.",
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-14T00:00:00.000Z"
}
getChange
Get a change record by id, or by productId + key (key lookup tolerates zero-padding: CHG-7, CHG-07 and CHG-007 resolve to the same record).
Input Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID (provide this, or productId + key)"
},
"productId": {
"type": "string",
"description": "Product ID (required when looking up by key)"
},
"key": {
"type": "string",
"description": "Change display key, e.g. 'CHG-07' (zero-padding tolerated)"
}
},
"description": "Get-change selector: changeId, or productId + key"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-01"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"stamps": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When work on this stage first started (null = start unrecorded)",
"nullable": true
},
"startedAtSource": {
"type": "string",
"enum": [
"reported",
"correctedManually",
"recoveredFromEvent",
"derivedFromPreviousStage"
],
"description": "How startedAt was obtained (null = the stamp pre-dates this field, which is not a claim that it was measured)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage was first finished",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage, as reported by the caller (null = not reported, which is never inferred from configuration)",
"nullable": true
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "The authenticated identity that performed the stage action (server-observed, never caller-supplied; first report wins)",
"nullable": true
}
},
"description": "First-entry start/finish stamps for a stage, who drove it, and the identity that performed it"
},
"description": "Per-stage first-entry stamps, keyed by stage (only stamped stages present)"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"intent": {
"type": "string"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"stampLedger": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage this commit drove"
},
"sha": {
"type": "string",
"description": "The commit sha that drove it"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage started (absent if it never did)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage finished (absent if it never did)",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who the report attested was driving; absent when the report named none",
"nullable": true
}
},
"required": [
"stage",
"sha"
],
"description": "One commit's record of driving one stage: which stage, which commit, and when it reported the start and the finish"
},
"description": "Append-only record of which commit drove which stage and when; never cleared by a rework jump-back",
"nullable": true
},
"shipCorrectedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"design": {
"type": "string",
"nullable": true
},
"designDocPath": {
"type": "string",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"riskAssessment": {
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"effectiveReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"assessedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"derivedReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"assessedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"effectiveReversibility",
"category",
"assessedAt",
"revision"
],
"description": "A change's current risk assessment",
"nullable": true
},
"confirmedPipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each",
"nullable": true
},
"confirmedPipelineCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"confirmedPipelineAuthoritative": {
"type": "boolean",
"nullable": true
},
"effectivePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
},
"effectivePipelineSource": {
"type": "string",
"enum": [
"confirmed",
"assessed",
"configuration"
],
"description": "Where the pipeline in force for a change came from (confirmed | assessed | configuration)"
},
"defect": {
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"classifiedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedInChangeId": {
"type": "string",
"description": "The change that introduced the defect. Server-derived from the commit's Change: trailer — not supplied by the caller.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"dormancyDays": {
"type": "number",
"nullable": true
},
"classifiedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"classifiedAt",
"revision"
],
"description": "The defect a Fix change repaired — the realised counterpart of the change risk assessment",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"introducedInChange": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Display key of the referenced change, e.g. CHG-42"
},
"productSlug": {
"type": "string",
"description": "Slug of the product owning the referenced change; absent where that product has no slug",
"nullable": true
}
},
"required": [
"key"
],
"description": "Derived reference to another change, resolved from a stored change id"
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"stamps",
"isCancelled",
"source",
"intent",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-01",
"title": "Bulk CSV export",
"type": "feature",
"stage": "code",
"stageState": "inProgress",
"stageActor": {
"type": "agent",
"id": "definitionAgent",
"name": "Definition Agent"
},
"stamps": {
"accept": {
"startedAt": "2026-06-12T00:00:00.000Z",
"finishedAt": "2026-06-12T00:00:00.000Z"
},
"code": {
"startedAt": "2026-06-13T00:00:00.000Z"
}
},
"isCancelled": false,
"source": "external",
"intent": "Customers need to export their story list as CSV.",
"userStoryIds": [
"STORY-1"
],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-13T00:00:00.000Z"
}
getChangeAnalytics
Read one period of change analytics for a team, a repository, or a single product — the investment mix, how long change work took from acceptance to production, and the risk and capability layers.
Returns the chosen period AND the one before it, because the comparison that matters is a scope against its own previous period. Comparing scopes against each other is not supported and is not an omission: change granularity is a local convention, so counts do not travel between teams or products.
Every headline figure counts only changes that SHIPPED inside the period, so accepting a large batch of new work does not move it. Newly accepted work is reported separately.
Durations always arrive paired with the open-work count and age spread. A median computed over only the changes that finished is survivorship-biased and improves as a team gets more backed up, so it is never returned alone.
Waiting time is attributed to what the change was waiting on — a person, an agent, or automated delivery — from the pipeline it ran under. That is a queue fact, never a claim about how much work a named individual did.
A closed period is served from its frozen rollup where one exists, so a figure quoted from it does not later change; `isProvisional` is true for the current, still-running period.
Input Schema
{
"type": "object",
"properties": {
"teamId": {
"type": "string",
"description": "Team ID — the scope anchor, and the tenant boundary the framework enforces"
},
"repoId": {
"type": "string",
"description": "Narrow to changes belonging to products in this repository. Repo scope allows a per-stage breakdown, because a repo owns stage enablement."
},
"productId": {
"type": "string",
"description": "Narrow to a single product within the team. Takes precedence over repoId when both are given."
},
"grain": {
"type": "string",
"enum": [
"week",
"month",
"quarter",
"year"
],
"description": "Reporting grain. Each grain is materialised independently over its own true calendar boundaries — a month is NOT the sum of its weeks, because ISO weeks straddle month ends."
},
"periodAt": {
"type": "string",
"format": "date-time",
"description": "Any instant within the period wanted; resolved server-side to that period. Omitted = the current, open period."
}
},
"required": [
"teamId"
],
"description": "Parameters for reading one period of a scope's change analytics"
}
Example Input
{
"teamId": "TEAM-716ade97-9279-4840-b030-c2f7f50e4d31",
"grain": "month"
}
Output Schema
{
"type": "object",
"properties": {
"scopeType": {
"type": "string",
"enum": [
"team",
"repo",
"product"
],
"description": "What a change analytics rollup is computed over (team | repo | product)"
},
"teamId": {
"type": "string"
},
"grain": {
"type": "string",
"enum": [
"week",
"month",
"quarter",
"year"
],
"description": "Reporting grain of a change analytics rollup (week | month | quarter | year)"
},
"periodStart": {
"type": "string",
"format": "date-time"
},
"periodEnd": {
"type": "string",
"format": "date-time"
},
"periodLabel": {
"type": "string"
},
"isProvisional": {
"type": "boolean"
},
"current": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"teamId": {
"type": "string"
},
"scopeType": {
"type": "string",
"enum": [
"team",
"repo",
"product"
],
"description": "What a change analytics rollup is computed over (team | repo | product)"
},
"grain": {
"type": "string",
"enum": [
"week",
"month",
"quarter",
"year"
],
"description": "Reporting grain of a change analytics rollup (week | month | quarter | year)"
},
"periodStart": {
"type": "string",
"format": "date-time"
},
"periodEnd": {
"type": "string",
"format": "date-time"
},
"frozen": {
"type": "boolean"
},
"schemaVersion": {
"type": "number"
},
"computedAt": {
"type": "string",
"format": "date-time"
},
"shippedTotal": {
"type": "number"
},
"shippedByType": {
"type": "object",
"properties": {
"feature": {
"type": "number"
},
"enhancement": {
"type": "number"
},
"bug": {
"type": "number"
},
"chore": {
"type": "number"
}
},
"required": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Shipped change counts by kind"
},
"acceptToShip": {
"type": "object",
"properties": {
"count": {
"type": "number"
},
"histogram": {
"type": "array",
"items": {
"type": "number"
}
},
"p50Ms": {
"type": "number",
"nullable": true
},
"p90Ms": {
"type": "number",
"nullable": true
}
},
"required": [
"count",
"histogram"
],
"description": "A duration distribution: exact percentiles plus the bucketed histogram"
},
"openWork": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"ageHistogram": {
"type": "array",
"items": {
"type": "number"
}
},
"idleOverSevenDays": {
"type": "number"
},
"oldestAgeMs": {
"type": "number",
"nullable": true
}
},
"required": [
"total",
"ageHistogram",
"idleOverSevenDays"
],
"description": "Changes still open at period end, with their age distribution"
},
"intake": {
"type": "object",
"properties": {
"accepted": {
"type": "number"
},
"peakDayAccepted": {
"type": "number"
},
"peakDayAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"accepted",
"peakDayAccepted"
],
"description": "Newly accepted change work in the period, isolated from the shipped headlines"
},
"stageTimes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"workMs": {
"type": "number"
},
"waitMs": {
"type": "number"
},
"workCount": {
"type": "number"
},
"waitCount": {
"type": "number"
},
"expectedDriver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Expected driver of a pipeline stage (human | agent | cicd)",
"nullable": true
}
},
"required": [
"stage",
"workMs",
"waitMs",
"workCount",
"waitCount"
],
"description": "Aggregate work and wait time at one pipeline stage, with its denominators"
}
},
"waitByDriver": {
"type": "object",
"properties": {
"humanMs": {
"type": "number"
},
"agentMs": {
"type": "number"
},
"cicdMs": {
"type": "number"
}
},
"required": [
"humanMs",
"agentMs",
"cicdMs"
],
"description": "Waiting time by what the change was waiting on — a queue attribution, never a labour claim"
},
"totalWorkMs": {
"type": "number"
},
"capability": {
"type": "object",
"properties": {
"linked": {
"type": "number"
},
"unlinked": {
"type": "number"
},
"byArea": {
"type": "array",
"items": {
"type": "object",
"properties": {
"areaName": {
"type": "string"
},
"count": {
"type": "number"
},
"areaId": {
"type": "string",
"nullable": true
},
"areaKey": {
"type": "string",
"nullable": true
}
},
"required": [
"areaName",
"count"
],
"description": "One product area's share of the period's story-linked change work"
}
}
},
"required": [
"linked",
"unlinked",
"byArea"
],
"description": "Which product areas the period's work landed in, with unlinked work as its own share"
},
"risk": {
"type": "object",
"properties": {
"assessed": {
"type": "number"
},
"unassessed": {
"type": "number"
},
"byCategory": {
"type": "object",
"properties": {
"low": {
"type": "number"
},
"medium": {
"type": "number"
},
"high": {
"type": "number"
}
},
"required": [
"low",
"medium",
"high"
]
},
"highWithHumanReview": {
"type": "number"
}
},
"required": [
"assessed",
"unassessed",
"byCategory",
"highWithHumanReview"
],
"description": "Assessed risk of the period's shipped changes and the oversight they ran under"
},
"deploy": {
"type": "object",
"properties": {
"shipped": {
"type": "number"
},
"failed": {
"type": "number"
},
"superseded": {
"type": "number"
}
},
"required": [
"shipped",
"failed",
"superseded"
],
"description": "Production deployment outcomes, with superseded runs kept apart from failures"
},
"rework": {
"type": "object",
"properties": {
"repeatedStageEntries": {
"type": "number"
},
"changesWithRepeatedStage": {
"type": "number"
}
},
"required": [
"repeatedStageEntries",
"changesWithRepeatedStage"
],
"description": "How often a change re-entered a stage it had already begun"
},
"annotations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"intakeSpike",
"pipelineChanged"
],
"description": "Why a period moved for a reason other than delivery behaviour"
},
"detail": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"kind",
"detail"
],
"description": "A note explaining a movement that is configuration or intake, not delivery"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"scopeRepoId": {
"type": "string",
"nullable": true
},
"scopeProductId": {
"type": "string",
"nullable": true
}
},
"required": [
"_id",
"teamId",
"scopeType",
"grain",
"periodStart",
"periodEnd",
"frozen",
"schemaVersion",
"computedAt",
"shippedTotal",
"shippedByType",
"acceptToShip",
"openWork",
"intake",
"stageTimes",
"waitByDriver",
"totalWorkMs",
"capability",
"risk",
"deploy",
"rework",
"annotations",
"createdAt",
"updatedAt"
]
},
"findings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"compositionShift",
"constraintMoved",
"waitDominance",
"speedShift",
"throughputShift",
"agingWork",
"intakeAnomaly",
"deployReliability",
"capabilityConcentration",
"oversight"
],
"description": "Which generator produced a briefing finding"
},
"text": {
"type": "string"
},
"direction": {
"type": "string",
"enum": [
"up",
"down",
"flat",
"new"
],
"description": "Which way a figure moved against the previous period — never a verdict"
},
"materiality": {
"type": "number"
},
"drillThrough": {
"type": "object",
"properties": {
"changeType": {
"type": "string",
"nullable": true
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage",
"nullable": true
},
"openOnly": {
"type": "boolean",
"nullable": true
}
},
"description": "The board facets a finding drills through to",
"nullable": true
}
},
"required": [
"kind",
"text",
"direction",
"materiality"
],
"description": "One ranked line of the period briefing"
}
},
"supportsStageBreakdown": {
"type": "boolean"
},
"repoId": {
"type": "string",
"nullable": true
},
"productId": {
"type": "string",
"nullable": true
},
"prior": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"teamId": {
"type": "string"
},
"scopeType": {
"type": "string",
"enum": [
"team",
"repo",
"product"
],
"description": "What a change analytics rollup is computed over (team | repo | product)"
},
"grain": {
"type": "string",
"enum": [
"week",
"month",
"quarter",
"year"
],
"description": "Reporting grain of a change analytics rollup (week | month | quarter | year)"
},
"periodStart": {
"type": "string",
"format": "date-time"
},
"periodEnd": {
"type": "string",
"format": "date-time"
},
"frozen": {
"type": "boolean"
},
"schemaVersion": {
"type": "number"
},
"computedAt": {
"type": "string",
"format": "date-time"
},
"shippedTotal": {
"type": "number"
},
"shippedByType": {
"type": "object",
"properties": {
"feature": {
"type": "number"
},
"enhancement": {
"type": "number"
},
"bug": {
"type": "number"
},
"chore": {
"type": "number"
}
},
"required": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Shipped change counts by kind"
},
"acceptToShip": {
"type": "object",
"properties": {
"count": {
"type": "number"
},
"histogram": {
"type": "array",
"items": {
"type": "number"
}
},
"p50Ms": {
"type": "number",
"nullable": true
},
"p90Ms": {
"type": "number",
"nullable": true
}
},
"required": [
"count",
"histogram"
],
"description": "A duration distribution: exact percentiles plus the bucketed histogram"
},
"openWork": {
"type": "object",
"properties": {
"total": {
"type": "number"
},
"ageHistogram": {
"type": "array",
"items": {
"type": "number"
}
},
"idleOverSevenDays": {
"type": "number"
},
"oldestAgeMs": {
"type": "number",
"nullable": true
}
},
"required": [
"total",
"ageHistogram",
"idleOverSevenDays"
],
"description": "Changes still open at period end, with their age distribution"
},
"intake": {
"type": "object",
"properties": {
"accepted": {
"type": "number"
},
"peakDayAccepted": {
"type": "number"
},
"peakDayAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"accepted",
"peakDayAccepted"
],
"description": "Newly accepted change work in the period, isolated from the shipped headlines"
},
"stageTimes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"workMs": {
"type": "number"
},
"waitMs": {
"type": "number"
},
"workCount": {
"type": "number"
},
"waitCount": {
"type": "number"
},
"expectedDriver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Expected driver of a pipeline stage (human | agent | cicd)",
"nullable": true
}
},
"required": [
"stage",
"workMs",
"waitMs",
"workCount",
"waitCount"
],
"description": "Aggregate work and wait time at one pipeline stage, with its denominators"
}
},
"waitByDriver": {
"type": "object",
"properties": {
"humanMs": {
"type": "number"
},
"agentMs": {
"type": "number"
},
"cicdMs": {
"type": "number"
}
},
"required": [
"humanMs",
"agentMs",
"cicdMs"
],
"description": "Waiting time by what the change was waiting on — a queue attribution, never a labour claim"
},
"totalWorkMs": {
"type": "number"
},
"capability": {
"type": "object",
"properties": {
"linked": {
"type": "number"
},
"unlinked": {
"type": "number"
},
"byArea": {
"type": "array",
"items": {
"type": "object",
"properties": {
"areaName": {
"type": "string"
},
"count": {
"type": "number"
},
"areaId": {
"type": "string",
"nullable": true
},
"areaKey": {
"type": "string",
"nullable": true
}
},
"required": [
"areaName",
"count"
],
"description": "One product area's share of the period's story-linked change work"
}
}
},
"required": [
"linked",
"unlinked",
"byArea"
],
"description": "Which product areas the period's work landed in, with unlinked work as its own share"
},
"risk": {
"type": "object",
"properties": {
"assessed": {
"type": "number"
},
"unassessed": {
"type": "number"
},
"byCategory": {
"type": "object",
"properties": {
"low": {
"type": "number"
},
"medium": {
"type": "number"
},
"high": {
"type": "number"
}
},
"required": [
"low",
"medium",
"high"
]
},
"highWithHumanReview": {
"type": "number"
}
},
"required": [
"assessed",
"unassessed",
"byCategory",
"highWithHumanReview"
],
"description": "Assessed risk of the period's shipped changes and the oversight they ran under"
},
"deploy": {
"type": "object",
"properties": {
"shipped": {
"type": "number"
},
"failed": {
"type": "number"
},
"superseded": {
"type": "number"
}
},
"required": [
"shipped",
"failed",
"superseded"
],
"description": "Production deployment outcomes, with superseded runs kept apart from failures"
},
"rework": {
"type": "object",
"properties": {
"repeatedStageEntries": {
"type": "number"
},
"changesWithRepeatedStage": {
"type": "number"
}
},
"required": [
"repeatedStageEntries",
"changesWithRepeatedStage"
],
"description": "How often a change re-entered a stage it had already begun"
},
"annotations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"intakeSpike",
"pipelineChanged"
],
"description": "Why a period moved for a reason other than delivery behaviour"
},
"detail": {
"type": "string"
},
"at": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"kind",
"detail"
],
"description": "A note explaining a movement that is configuration or intake, not delivery"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"scopeRepoId": {
"type": "string",
"nullable": true
},
"scopeProductId": {
"type": "string",
"nullable": true
}
},
"required": [
"_id",
"teamId",
"scopeType",
"grain",
"periodStart",
"periodEnd",
"frozen",
"schemaVersion",
"computedAt",
"shippedTotal",
"shippedByType",
"acceptToShip",
"openWork",
"intake",
"stageTimes",
"waitByDriver",
"totalWorkMs",
"capability",
"risk",
"deploy",
"rework",
"annotations",
"createdAt",
"updatedAt"
],
"nullable": true
},
"coverageCaveat": {
"type": "string",
"nullable": true
}
},
"required": [
"scopeType",
"teamId",
"grain",
"periodStart",
"periodEnd",
"periodLabel",
"isProvisional",
"current",
"findings",
"supportsStageBreakdown"
],
"description": "One period of change analytics for one scope, with its prior period and briefing"
}
getEffectiveChangePipeline
Resolve a product's effective change pipeline: the repository-level default with the product's judgement-stage driver overrides applied. This is the same resolution the change stage engine uses, so agents and tools see the same enabled stages and drivers the UI shows.
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
},
"riskCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Resolve against this risk category's preset. Omitted = the category-blind configuration resolution. Neither is necessarily the pipeline a given change is running under — read effectivePipeline on the change for that."
}
},
"required": [
"productId"
],
"description": "Parameters for resolving a product's effective change pipeline (repo default with product overrides applied)"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
}
Example Output
[
{
"stage": "accept",
"enabled": true,
"driver": "human"
},
{
"stage": "design",
"enabled": true,
"driver": "human"
},
{
"stage": "code",
"enabled": true,
"driver": "agent"
},
{
"stage": "review",
"enabled": true,
"driver": "human"
},
{
"stage": "ship",
"enabled": true,
"driver": "cicd"
}
]
listChanges
List change records for a product, optionally filtered by stage, stage state, type, cancellation, or external origin reference (originSystem/originRef — e.g. find the change for JIRA ticket PROJ-123). Returns a COMPACT SUMMARY per change: identity, type, lifecycle position, the owning product, link counts, the assessed risk category and when the current stage began. It deliberately carries no long-form narrative (intent, design), no pipeline configuration and no risk evidence — fetch the full record for one change with getChange. Results are a bounded slice, newest-updated first, and the response reports the true total so a slice is never mistaken for the whole set.
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Filter by current pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "Filter by the state of the current stage"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Filter by change type"
},
"isCancelled": {
"type": "boolean",
"description": "Filter by cancellation (true = cancelled changes only, false = live changes only)"
},
"originSystem": {
"type": "string",
"description": "Filter by origin system (lowercase, e.g. 'jira')"
},
"originRef": {
"type": "string",
"description": "Filter by origin reference (e.g. 'PROJ-123')"
},
"limit": {
"type": "number",
"description": "Maximum changes to return, most recently updated first (default 40). The response always reports the true total, so a smaller slice is never mistaken for the whole set."
}
},
"required": [
"productId"
],
"description": "Parameters for listing changes"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"originSystem": "jira",
"originRef": "PROJ-123"
}
Output Schema
{
"type": "object",
"properties": {
"changes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"productSlug": {
"type": "string",
"nullable": true
},
"productName": {
"type": "string"
},
"riskCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"currentStageStartedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"shippedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"isCancelled",
"source",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
},
"description": "The changes returned, most recently updated first"
},
"total": {
"type": "number",
"description": "Total changes matching the filters, whether or not they were returned"
},
"limit": {
"type": "number",
"description": "Maximum number of changes this call was willing to return"
}
},
"required": [
"changes",
"total",
"limit"
],
"description": "A bounded slice of changes with the true total"
}
Example Output
{
"changes": [
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productSlug": "acme-app",
"productName": "Acme App",
"key": "CHG-01",
"title": "Bulk CSV export",
"type": "feature",
"stage": "accept",
"stageState": "completed",
"currentStageStartedAt": "2026-06-12T00:00:00.000Z",
"riskCategory": "low",
"isCancelled": false,
"source": "external",
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-12T00:00:00.000Z"
}
],
"total": 1,
"limit": 40
}
listTeamChanges
List change records across every product in a team, optionally filtered by repository, product, stage, stage state, type, cancellation, or external origin reference. Returns the same COMPACT SUMMARY per change as listChanges — identity, type, lifecycle position, the owning product, link counts, the assessed risk category and when the current stage began — with no long-form narrative, pipeline configuration or risk evidence; fetch the full record for one change with getChange. Results are a bounded slice, newest-updated first, reporting the true total, and are limited to the products the caller may read.
Input Schema
{
"type": "object",
"properties": {
"teamId": {
"type": "string",
"description": "Team ID — the scope of the listing"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Filter by current pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "Filter by the state of the current stage"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Filter by change type"
},
"isCancelled": {
"type": "boolean",
"description": "Filter by cancellation (true = cancelled changes only, false = live changes only)"
},
"originSystem": {
"type": "string",
"description": "Filter by origin system (lowercase, e.g. 'jira')"
},
"originRef": {
"type": "string",
"description": "Filter by origin reference (e.g. 'PROJ-123')"
},
"repoId": {
"type": "string",
"description": "Filter to changes belonging to products in this repository"
},
"productId": {
"type": "string",
"description": "Filter to a single product within the team"
},
"limit": {
"type": "number",
"description": "Maximum changes to return, most recently updated first (default 40). The response always reports the true total, so a smaller slice is never mistaken for the whole set."
}
},
"required": [
"teamId"
],
"description": "Parameters for listing a team's changes across its products"
}
Example Input
{
"teamId": "TEAM-716ade97-9279-4840-b030-c2f7f50e4d31",
"isCancelled": false
}
Output Schema
{
"type": "object",
"properties": {
"changes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"productSlug": {
"type": "string",
"nullable": true
},
"productName": {
"type": "string"
},
"riskCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"currentStageStartedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"shippedAt": {
"type": "string",
"format": "date-time",
"nullable": true
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"isCancelled",
"source",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
},
"description": "The changes returned, most recently updated first"
},
"total": {
"type": "number",
"description": "Total changes matching the filters, whether or not they were returned"
},
"limit": {
"type": "number",
"description": "Maximum number of changes this call was willing to return"
}
},
"required": [
"changes",
"total",
"limit"
],
"description": "A bounded slice of changes with the true total"
}
Example Output
{
"changes": [
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productSlug": "acme-app",
"productName": "Acme App",
"key": "CHG-01",
"title": "Bulk CSV export",
"type": "feature",
"stage": "code",
"stageState": "inProgress",
"currentStageStartedAt": "2026-06-12T00:00:00.000Z",
"riskCategory": "medium",
"isCancelled": false,
"source": "external",
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-12T00:00:00.000Z"
}
],
"total": 1,
"limit": 40
}
patchChange
Apply patch changes to a change record (content only; lifecycle position and cancellation are written solely via the stage-action cases; historical stage times are set or corrected via the setChangeStageTimes case, not here; shipped records are frozen)
Input Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"comment": {
"type": "string",
"description": "Patch comment"
},
"overrideFrozen": {
"type": "boolean",
"description": "Override the shipped-record freeze for THIS CALL ONLY, to correct a record that is wrong. Requires a signed-in team owner or administrator: every API-key-authenticated caller is refused whatever its scope, because no key scope distinguishes a person's credentials from the delivery pipeline's own — and the pipeline must never be able to correct a record it wrote. Never persists: the record is frozen again the moment the call returns."
},
"overrideReason": {
"type": "string",
"description": "Why the shipped record is being corrected. REQUIRED whenever overrideFrozen is set, and recorded permanently in the change's event trail alongside the identity that performed the override, so a correction to the historical record is never silent."
}
},
"required": [
"changeId",
"patch"
],
"description": "Parameters for patching a change (content only — lifecycle position and cancellation are written solely via the stage-action cases; historical stage times are set or corrected via setChangeStageTimes)"
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/design",
"value": "## Design\nUpdated design notes"
}
],
"comment": "Refine design"
}
Output Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"patchId": {
"type": "string",
"description": "Patch ID"
}
},
"required": [
"changeId",
"patch",
"patchId"
],
"description": "Output for patching a change"
}
Example Output
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/design",
"value": "## Design\nUpdated design notes"
}
],
"patchId": "PATCH-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
recordChangeDefect
Classify the defect a fix repaired, so risk predictions can later be scored against what actually happened.
Applies to a change of type bug only. One classification per change, holding the MOST SEVERE defect the fix repaired: rank by who it affected — customer beats staff beats developer — and break ties by impact severity. A fix that repaired several defects records the one nearest the customer and lets the rest go; the number this produces is "customer-facing defects", not "defects".
impactSeverity is scored on the SAME 1-10 anchors as the risk rubric's Severity axis, and for the same reason the assessment demands evidence: an unsupported score is not an assessment. Score it WITHIN the audience you named in affects — the anchors are written assuming a customer, so a staff-only defect breaking a core admin workflow reads as an 8 and wildly overstates its business impact. Never compare severities across audiences.
foundBy is what actually exposed the defect, not what should have. It is the field that tells the team which gate to invest in, and it is the cheapest one here — you cannot fix a bug without already knowing how you found it.
THE COMMIT IS THE THING TO SUPPLY, not the change. Give introducedInCommit from bisect or blame, and introducedInCommitTrailer as the Change: trailer read off that same commit; the change link, and how long the defect lay undetected, are derived from those. Do not look a change up yourself. Where the defect is in code that never worked there is no introducing commit — record age "base" and omit them both, rather than guessing.
Recording a classification never moves the change through its pipeline, never disturbs stage times, and never blocks a fix from shipping. It can also be recorded or amended AFTER the change has shipped, unlike every other content field — realised impact is often only learned once a customer explains what actually happened, and the full history is kept in the change event trail.
Input Schema
{
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"changeId": {
"type": "string",
"description": "Change ID"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"description": "The introducing commit's date, read from that commit. Frozen on write — it is not re-derived later, because a rewritten SHA would take the date with it.",
"nullable": true
},
"introducedInCommitTrailer": {
"type": "string",
"description": "The Change: trailer read off the introducing commit, verbatim (e.g. \"defprod/CHG-42\"). The change link is resolved from this — do not look a change up yourself. Requires introducedInCommit."
},
"note": {
"type": "string",
"description": "Optional note (lands in the change's event trail)"
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"changeId"
],
"description": "Parameters for classifying the defect a Fix change repaired. Give the commit that introduced it where you can find one; the change it belonged to, the date, and how long it lay undetected are derived from that commit."
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"affects": "customer",
"impactSeverity": 7,
"impactSeverityEvidence": "Every customer on a grandfathered price saw their plan silently unset by the hourly billing sweep, so the subscription page showed no plan and upgrades were refused. Core workflow, awkward workaround only (support re-set it by hand).",
"foundBy": "customerReport",
"target": "code",
"defectType": "checking",
"qualifier": "missing",
"age": "new",
"introducedInCommit": "4f2a1c9d8b3e5a7c1f0d2b6e9a4c8d3f5b7e1a2c",
"introducedInCommitTrailer": "defprod/CHG-88",
"introducedAt": "2026-07-30T09:14:00.000Z",
"note": "Classified at the end of code, with the diff in hand"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"stamps": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When work on this stage first started (null = start unrecorded)",
"nullable": true
},
"startedAtSource": {
"type": "string",
"enum": [
"reported",
"correctedManually",
"recoveredFromEvent",
"derivedFromPreviousStage"
],
"description": "How startedAt was obtained (null = the stamp pre-dates this field, which is not a claim that it was measured)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage was first finished",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage, as reported by the caller (null = not reported, which is never inferred from configuration)",
"nullable": true
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "The authenticated identity that performed the stage action (server-observed, never caller-supplied; first report wins)",
"nullable": true
}
},
"description": "First-entry start/finish stamps for a stage, who drove it, and the identity that performed it"
},
"description": "Per-stage first-entry stamps, keyed by stage (only stamped stages present)"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"intent": {
"type": "string"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"stampLedger": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage this commit drove"
},
"sha": {
"type": "string",
"description": "The commit sha that drove it"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage started (absent if it never did)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage finished (absent if it never did)",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who the report attested was driving; absent when the report named none",
"nullable": true
}
},
"required": [
"stage",
"sha"
],
"description": "One commit's record of driving one stage: which stage, which commit, and when it reported the start and the finish"
},
"description": "Append-only record of which commit drove which stage and when; never cleared by a rework jump-back",
"nullable": true
},
"shipCorrectedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"design": {
"type": "string",
"nullable": true
},
"designDocPath": {
"type": "string",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"riskAssessment": {
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"effectiveReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"assessedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"derivedReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"assessedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"effectiveReversibility",
"category",
"assessedAt",
"revision"
],
"description": "A change's current risk assessment",
"nullable": true
},
"confirmedPipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each",
"nullable": true
},
"confirmedPipelineCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"confirmedPipelineAuthoritative": {
"type": "boolean",
"nullable": true
},
"effectivePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
},
"effectivePipelineSource": {
"type": "string",
"enum": [
"confirmed",
"assessed",
"configuration"
],
"description": "Where the pipeline in force for a change came from (confirmed | assessed | configuration)"
},
"defect": {
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"classifiedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedInChangeId": {
"type": "string",
"description": "The change that introduced the defect. Server-derived from the commit's Change: trailer — not supplied by the caller.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"dormancyDays": {
"type": "number",
"nullable": true
},
"classifiedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"classifiedAt",
"revision"
],
"description": "The defect a Fix change repaired — the realised counterpart of the change risk assessment",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"introducedInChange": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Display key of the referenced change, e.g. CHG-42"
},
"productSlug": {
"type": "string",
"description": "Slug of the product owning the referenced change; absent where that product has no slug",
"nullable": true
}
},
"required": [
"key"
],
"description": "Derived reference to another change, resolved from a stored change id"
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"stamps",
"isCancelled",
"source",
"intent",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-92",
"title": "Fix hourly billing sweep nulling planId on grandfathered subscriptions",
"type": "bug",
"stage": "ship",
"stageState": "completed",
"isCancelled": false,
"source": "internal",
"intent": "Stop the sweep unsetting planId for subscriptions held on grandfathered Stripe prices.",
"defect": {
"affects": "customer",
"impactSeverity": 7,
"foundBy": "customerReport",
"target": "code",
"defectType": "checking",
"qualifier": "missing",
"age": "new",
"introducedInCommit": "4f2a1c9d8b3e5a7c1f0d2b6e9a4c8d3f5b7e1a2c",
"introducedInChangeId": "CHANGE-1c3e5a79-2b4d-6f80-a1c3-e5a792b4d6f8",
"dormancyDays": 9,
"revision": 1
},
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-08-08T00:00:00.000Z",
"updatedAt": "2026-08-09T08:00:00.000Z"
}
reopenChange
Reopen a cancelled change — it resumes at the position (stage and state) it held when cancelled, with all stamps intact. Only cancelled changes can be reopened. Emits changeReopened.
Input Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
},
"note": {
"type": "string",
"description": "Optional note (lands in the change's event trail)"
}
},
"required": [
"changeId"
],
"description": "Parameters for reopening a cancelled change — it resumes at the position it held when cancelled"
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"note": "customer escalated — back on the roadmap"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"stamps": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When work on this stage first started (null = start unrecorded)",
"nullable": true
},
"startedAtSource": {
"type": "string",
"enum": [
"reported",
"correctedManually",
"recoveredFromEvent",
"derivedFromPreviousStage"
],
"description": "How startedAt was obtained (null = the stamp pre-dates this field, which is not a claim that it was measured)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage was first finished",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage, as reported by the caller (null = not reported, which is never inferred from configuration)",
"nullable": true
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "The authenticated identity that performed the stage action (server-observed, never caller-supplied; first report wins)",
"nullable": true
}
},
"description": "First-entry start/finish stamps for a stage, who drove it, and the identity that performed it"
},
"description": "Per-stage first-entry stamps, keyed by stage (only stamped stages present)"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"intent": {
"type": "string"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"stampLedger": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage this commit drove"
},
"sha": {
"type": "string",
"description": "The commit sha that drove it"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage started (absent if it never did)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage finished (absent if it never did)",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who the report attested was driving; absent when the report named none",
"nullable": true
}
},
"required": [
"stage",
"sha"
],
"description": "One commit's record of driving one stage: which stage, which commit, and when it reported the start and the finish"
},
"description": "Append-only record of which commit drove which stage and when; never cleared by a rework jump-back",
"nullable": true
},
"shipCorrectedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"design": {
"type": "string",
"nullable": true
},
"designDocPath": {
"type": "string",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"riskAssessment": {
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"effectiveReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"assessedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"derivedReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"assessedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"effectiveReversibility",
"category",
"assessedAt",
"revision"
],
"description": "A change's current risk assessment",
"nullable": true
},
"confirmedPipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each",
"nullable": true
},
"confirmedPipelineCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"confirmedPipelineAuthoritative": {
"type": "boolean",
"nullable": true
},
"effectivePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
},
"effectivePipelineSource": {
"type": "string",
"enum": [
"confirmed",
"assessed",
"configuration"
],
"description": "Where the pipeline in force for a change came from (confirmed | assessed | configuration)"
},
"defect": {
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"classifiedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedInChangeId": {
"type": "string",
"description": "The change that introduced the defect. Server-derived from the commit's Change: trailer — not supplied by the caller.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"dormancyDays": {
"type": "number",
"nullable": true
},
"classifiedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"classifiedAt",
"revision"
],
"description": "The defect a Fix change repaired — the realised counterpart of the change risk assessment",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"introducedInChange": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Display key of the referenced change, e.g. CHG-42"
},
"productSlug": {
"type": "string",
"description": "Slug of the product owning the referenced change; absent where that product has no slug",
"nullable": true
}
},
"required": [
"key"
],
"description": "Derived reference to another change, resolved from a stored change id"
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"stamps",
"isCancelled",
"source",
"intent",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-01",
"title": "Bulk CSV export",
"type": "feature",
"stage": "code",
"stageState": "notStarted",
"stamps": {
"accept": {
"startedAt": "2026-06-12T00:00:00.000Z",
"finishedAt": "2026-06-12T00:00:00.000Z"
}
},
"isCancelled": false,
"cancelledAt": "2026-06-14T00:00:00.000Z",
"source": "external",
"intent": "Customers need to export their story list as CSV.",
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-16T00:00:00.000Z"
}
setChangeStageTimes
Set or correct a change's historical stage start/finish times. Give a `stamps` array, one entry per stage `{ stage, startedAt?, finishedAt? }` (times as ISO string, epoch millis, or Date). Fills blank times OR corrects already-recorded ones. Never moves lifecycle position or current-stage state. Guards: only a stage the change has already reached may be timed; per stage startedAt <= finishedAt; no future dates; shipped records are frozen. The durable audit trail remains the stage started/finished events — this writes only the summary stamps.
Input Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
},
"stamps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Pipeline stage to set times for (must be a stage the change has already reached)"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "Historical start time (ISO string, epoch millis, or Date). Omit to leave unchanged.",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "Historical finish time (ISO string, epoch millis, or Date). Omit to leave unchanged.",
"nullable": true
}
},
"required": [
"stage"
],
"description": "Historical start/finish times to set for one stage"
},
"description": "Historical stage times to set, one entry per stage (at least one). Fills blanks or corrects existing times; only stages the change has already reached may be set."
},
"note": {
"type": "string",
"description": "Optional note (lands in the change's event trail)"
},
"overrideFrozen": {
"type": "boolean",
"description": "Override the shipped-record freeze for THIS CALL ONLY, to correct a record that is wrong. Requires a signed-in team owner or administrator: every API-key-authenticated caller is refused whatever its scope, because no key scope distinguishes a person's credentials from the delivery pipeline's own — and the pipeline must never be able to correct a record it wrote. Never persists: the record is frozen again the moment the call returns."
},
"overrideReason": {
"type": "string",
"description": "Why the shipped record is being corrected. REQUIRED whenever overrideFrozen is set, and recorded permanently in the change's event trail alongside the identity that performed the override, so a correction to the historical record is never silent."
}
},
"required": [
"changeId",
"stamps"
],
"description": "Parameters for setting or correcting a change's historical stage start/finish times (position, current-stage state and cancellation are untouched)"
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"stamps": [
{
"stage": "code",
"startedAt": "2026-06-13T09:00:00Z",
"finishedAt": "2026-06-13T17:30:00Z"
},
{
"stage": "test",
"finishedAt": "2026-06-14T00:00:00Z"
}
],
"note": "Reconstructed from the PR timeline"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"stamps": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When work on this stage first started (null = start unrecorded)",
"nullable": true
},
"startedAtSource": {
"type": "string",
"enum": [
"reported",
"correctedManually",
"recoveredFromEvent",
"derivedFromPreviousStage"
],
"description": "How startedAt was obtained (null = the stamp pre-dates this field, which is not a claim that it was measured)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage was first finished",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage, as reported by the caller (null = not reported, which is never inferred from configuration)",
"nullable": true
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "The authenticated identity that performed the stage action (server-observed, never caller-supplied; first report wins)",
"nullable": true
}
},
"description": "First-entry start/finish stamps for a stage, who drove it, and the identity that performed it"
},
"description": "Per-stage first-entry stamps, keyed by stage (only stamped stages present)"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"intent": {
"type": "string"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"stampLedger": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage this commit drove"
},
"sha": {
"type": "string",
"description": "The commit sha that drove it"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage started (absent if it never did)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage finished (absent if it never did)",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who the report attested was driving; absent when the report named none",
"nullable": true
}
},
"required": [
"stage",
"sha"
],
"description": "One commit's record of driving one stage: which stage, which commit, and when it reported the start and the finish"
},
"description": "Append-only record of which commit drove which stage and when; never cleared by a rework jump-back",
"nullable": true
},
"shipCorrectedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"design": {
"type": "string",
"nullable": true
},
"designDocPath": {
"type": "string",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"riskAssessment": {
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"effectiveReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"assessedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"derivedReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"assessedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"effectiveReversibility",
"category",
"assessedAt",
"revision"
],
"description": "A change's current risk assessment",
"nullable": true
},
"confirmedPipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each",
"nullable": true
},
"confirmedPipelineCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"confirmedPipelineAuthoritative": {
"type": "boolean",
"nullable": true
},
"effectivePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
},
"effectivePipelineSource": {
"type": "string",
"enum": [
"confirmed",
"assessed",
"configuration"
],
"description": "Where the pipeline in force for a change came from (confirmed | assessed | configuration)"
},
"defect": {
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"classifiedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedInChangeId": {
"type": "string",
"description": "The change that introduced the defect. Server-derived from the commit's Change: trailer — not supplied by the caller.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"dormancyDays": {
"type": "number",
"nullable": true
},
"classifiedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"classifiedAt",
"revision"
],
"description": "The defect a Fix change repaired — the realised counterpart of the change risk assessment",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"introducedInChange": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Display key of the referenced change, e.g. CHG-42"
},
"productSlug": {
"type": "string",
"description": "Slug of the product owning the referenced change; absent where that product has no slug",
"nullable": true
}
},
"required": [
"key"
],
"description": "Derived reference to another change, resolved from a stored change id"
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"stamps",
"isCancelled",
"source",
"intent",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-01",
"title": "Bulk CSV export",
"type": "feature",
"stage": "review",
"stageState": "inProgress",
"stamps": {
"accept": {
"startedAt": "2026-06-12T00:00:00.000Z",
"finishedAt": "2026-06-12T00:00:00.000Z"
},
"code": {
"startedAt": "2026-06-13T09:00:00.000Z",
"finishedAt": "2026-06-13T17:30:00.000Z"
},
"test": {
"finishedAt": "2026-06-14T00:00:00.000Z"
}
},
"isCancelled": false,
"source": "external",
"intent": "Customers need to export their story list as CSV.",
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-14T08:00:00.000Z"
}
startChangeStage
Start work on a pipeline stage. Omit `stage` and the server resolves the next enabled stage in the product's change pipeline — callers need no workflow knowledge. An explicit stage is a deliberate jump (skip ahead, or rework an earlier stage). Records who is working (the calling actor) and the first-entry startedAt stamp; emits changeStageStarted.
Optionally report `driver` — who is actually driving this stage. It cannot be derived server-side: a per-run driver override legitimately deviates from the configured pipeline, and the calling actor is the API-key identity, so an agent stage authenticates as the person whose key it holds. It is a fact report, not validated against configuration, and the first report wins. Omit it and the stage records no driver, which reads as unknown and is never inferred from configuration.
Input Schema
{
"type": "object",
"properties": {
"changeId": {
"type": "string",
"description": "Change ID"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Stage to start. Omitted → the next enabled stage after the current position. Explicit → jump (skip ahead or rework an earlier stage)."
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage (human | agent | cicd). A fact report, not validated against the configured pipeline — a per-run driver override legitimately deviates from it. First report wins, like the stage times. Omitted → the stage records no driver; it is never inferred from configuration."
},
"stageCeilings": {
"type": "array",
"items": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"description": "The ceilings declared by the commits that correlated this change, each from a commit's `Change: <slug>/CHG-NN:<stage>` trailer. The stamp proceeds if ANY of them entitles the reported stage; a report beyond ALL of them is recorded as having had no effect — the change is neither advanced to the reported stage nor moved back to a ceiling. Omit entirely when any correlated commit carried no suffix, which means that commit delivers the change in full: the default and majority case. A SET rather than one value because a deploy range routinely carries several commits for one change — a design commit and the landing commit often ship together, and the landing is what entitles the ship."
},
"commitSha": {
"type": "string",
"description": "The commit this report is derived from. Idempotency key: the same commit never advances the same stage of the same change twice, however many times a deploy range re-includes it. Omitted means the report is not attributable to a commit and is not de-duplicated."
},
"note": {
"type": "string",
"description": "Optional note (lands in the change's event trail)"
},
"overrideFrozen": {
"type": "boolean",
"description": "Override the shipped-record freeze for THIS CALL ONLY, to correct a record that is wrong. Requires a signed-in team owner or administrator: every API-key-authenticated caller is refused whatever its scope, because no key scope distinguishes a person's credentials from the delivery pipeline's own — and the pipeline must never be able to correct a record it wrote. Never persists: the record is frozen again the moment the call returns."
},
"overrideReason": {
"type": "string",
"description": "Why the shipped record is being corrected. REQUIRED whenever overrideFrozen is set, and recorded permanently in the change's event trail alongside the identity that performed the override, so a correction to the historical record is never silent."
}
},
"required": [
"changeId"
],
"description": "Parameters for starting work on a pipeline stage"
}
Example Input
{
"changeId": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"stage": "review",
"note": "code-review agent picking this up"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"key": {
"type": "string"
},
"title": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"feature",
"enhancement",
"bug",
"chore"
],
"description": "Change type"
},
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "Change pipeline stage"
},
"stageState": {
"type": "string",
"enum": [
"notStarted",
"inProgress",
"completed",
"failed"
],
"description": "State of the change at its current stage"
},
"stamps": {
"type": "object",
"additionalProperties": {
"type": "object",
"properties": {
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When work on this stage first started (null = start unrecorded)",
"nullable": true
},
"startedAtSource": {
"type": "string",
"enum": [
"reported",
"correctedManually",
"recoveredFromEvent",
"derivedFromPreviousStage"
],
"description": "How startedAt was obtained (null = the stamp pre-dates this field, which is not a claim that it was measured)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this stage was first finished",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who actually drove this stage, as reported by the caller (null = not reported, which is never inferred from configuration)",
"nullable": true
},
"actor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "The authenticated identity that performed the stage action (server-observed, never caller-supplied; first report wins)",
"nullable": true
}
},
"description": "First-entry start/finish stamps for a stage, who drove it, and the identity that performed it"
},
"description": "Per-stage first-entry stamps, keyed by stage (only stamped stages present)"
},
"isCancelled": {
"type": "boolean"
},
"source": {
"type": "string",
"enum": [
"external",
"internal"
],
"description": "Change source (external | internal)"
},
"intent": {
"type": "string"
},
"userStoryIds": {
"type": "array",
"items": {
"type": "string"
}
},
"prUrls": {
"type": "array",
"items": {
"type": "string"
}
},
"relatedChangeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"stageActor": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
},
"stampLedger": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The stage this commit drove"
},
"sha": {
"type": "string",
"description": "The commit sha that drove it"
},
"startedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage started (absent if it never did)",
"nullable": true
},
"finishedAt": {
"type": "string",
"format": "date-time",
"description": "When this commit reported the stage finished (absent if it never did)",
"nullable": true
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who the report attested was driving; absent when the report named none",
"nullable": true
}
},
"required": [
"stage",
"sha"
],
"description": "One commit's record of driving one stage: which stage, which commit, and when it reported the start and the finish"
},
"description": "Append-only record of which commit drove which stage and when; never cleared by a rework jump-back",
"nullable": true
},
"shipCorrectedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"cancelledAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"origin": {
"type": "object",
"properties": {
"system": {
"type": "string",
"description": "Originating system identifier, e.g. 'jira', 'notion', 'linear', 'brain'. Free string, lowercase-normalised on write."
},
"ref": {
"type": "string",
"description": "Reference within the originating system, e.g. 'PROJ-123', 'INT0001'."
},
"url": {
"type": "string",
"description": "Optional deep link back into the originating system.",
"nullable": true
}
},
"required": [
"system",
"ref"
],
"description": "External origin reference for a change",
"nullable": true
},
"design": {
"type": "string",
"nullable": true
},
"designDocPath": {
"type": "string",
"nullable": true
},
"walkthroughUrl": {
"type": "string",
"nullable": true
},
"riskAssessment": {
"type": "object",
"properties": {
"overlay": {
"type": "string",
"enum": [
"core",
"dbm"
],
"description": "Anchor set the assessment was scored against (core | dbm)"
},
"severity": {
"type": "number",
"description": "Severity 1-10: how bad the effect is if this change fails (10 = worst). Rated on effect alone. See the risk rubric for anchors."
},
"severityEvidence": {
"type": "string",
"description": "What the change touches, and whether any of it is billing, authentication, authorisation or tenant isolation"
},
"occurrence": {
"type": "number",
"description": "Occurrence 1-10: how likely the cause is (10 = most likely). Unfamiliar subsystem scores HIGH, not low. See the risk rubric for anchors."
},
"occurrenceEvidence": {
"type": "string",
"description": "Prior art in this repo, and what docs/rules and the incident record say about this failure pattern"
},
"detection": {
"type": "number",
"description": "Detection 1-10, INVERTED: 1 = certain to be caught before a customer sees it, 10 = silent. See the risk rubric for anchors."
},
"detectionEvidence": {
"type": "string",
"description": "The specific test that would fail on this failure mode, or a plain statement that none exists"
},
"authoredReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Your own reversibility judgement (reversible | compensable | irreversible)"
},
"effectiveReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"assessedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"doNothingSeverity": {
"type": "number",
"description": "Do-nothing severity 1-10: the harm of NOT making this change. Recorded only when the result is High.",
"nullable": true
},
"doNothingSeverityEvidence": {
"type": "string",
"description": "What continues to go wrong if this change is not made",
"nullable": true
},
"derivedReversibility": {
"type": "string",
"enum": [
"reversible",
"compensable",
"irreversible"
],
"description": "Reversibility (reversible | compensable | irreversible)",
"nullable": true
},
"reversibilityOverrideJustification": {
"type": "string",
"nullable": true
},
"writeSet": {
"type": "array",
"items": {
"type": "object",
"properties": {
"collection": {
"type": "string",
"description": "The collection written"
},
"operation": {
"type": "string",
"enum": [
"setField",
"unsetField",
"renameField",
"renameCollection",
"replaceDocument",
"insertDocument",
"deleteDocument",
"dropCollection",
"createIndex",
"dropIndex"
],
"description": "What the migration does to the collection"
},
"fieldLevel": {
"type": "boolean",
"description": "True when specific fields are written; false when whole documents are replaced or removed"
},
"preImageCaptured": {
"type": "boolean",
"description": "True when the information needed to undo the write is recorded somewhere the migration does not itself destroy — the prior value for a field write, an identifying marker for an insert, or the index definition for an index drop"
}
},
"required": [
"collection",
"operation",
"fieldLevel",
"preImageCaptured"
],
"description": "One write a migration performs"
},
"nullable": true
},
"sideEffects": {
"type": "array",
"items": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"email",
"payment",
"webhook",
"thirdPartyRecord",
"other"
],
"description": "Kind of effect reaching outside the database"
},
"description": {
"type": "string",
"description": "What the effect is"
},
"compensable": {
"type": "boolean",
"description": "True when a compensating action can make the harm good; false when nothing can undo it"
}
},
"required": [
"kind",
"description",
"compensable"
],
"description": "One effect a migration has outside the database"
},
"nullable": true
},
"assessedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"overlay",
"severity",
"severityEvidence",
"occurrence",
"occurrenceEvidence",
"detection",
"detectionEvidence",
"authoredReversibility",
"effectiveReversibility",
"category",
"assessedAt",
"revision"
],
"description": "A change's current risk assessment",
"nullable": true
},
"confirmedPipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each",
"nullable": true
},
"confirmedPipelineCategory": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller",
"nullable": true
},
"confirmedPipelineAuthoritative": {
"type": "boolean",
"nullable": true
},
"effectivePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Per-product change pipeline configuration: which stages are enabled and who drives each"
},
"effectivePipelineSource": {
"type": "string",
"enum": [
"confirmed",
"assessed",
"configuration"
],
"description": "Where the pipeline in force for a change came from (confirmed | assessed | configuration)"
},
"defect": {
"type": "object",
"properties": {
"affects": {
"type": "string",
"enum": [
"customer",
"staff",
"developer"
],
"description": "Who the defect affected: customer (external user) | staff (internal person using the running product) | developer (only people building it — tests, build, tooling)"
},
"impactSeverity": {
"type": "number",
"description": "Realised impact severity 1-10, scored against the SAME anchors as the risk rubric's Severity axis so predicted and realised are comparable. Scored within the audience named by `affects` — never compared across audiences."
},
"impactSeverityEvidence": {
"type": "string",
"description": "What actually went wrong for whom, in enough detail to justify the severity chosen"
},
"foundBy": {
"type": "string",
"enum": [
"preflight",
"blockingSuite",
"nightlySuite",
"reviewStage",
"manualUse",
"alert",
"customerReport",
"unknown"
],
"description": "What exposed the defect, roughly ordered by escape distance: preflight | blockingSuite | nightlySuite | reviewStage | manualUse | alert | customerReport | unknown"
},
"target": {
"type": "string",
"enum": [
"definition",
"code",
"data",
"test",
"config",
"build",
"docs"
],
"description": "What had to be fixed: definition (the acceptance criteria were wrong) | code | data | test | config | build | docs"
},
"defectType": {
"type": "string",
"enum": [
"assignment",
"checking",
"algorithm",
"function",
"timing",
"interface",
"relationship",
"buildPackageMerge"
],
"description": "ODC defect type — the nature of the mistake: assignment | checking | algorithm | function | timing | interface | relationship | buildPackageMerge"
},
"qualifier": {
"type": "string",
"enum": [
"missing",
"incorrect",
"extraneous"
],
"description": "Whether the thing was missing (nobody thought of it), incorrect (thought of, got wrong), or extraneous (should not have been there)"
},
"age": {
"type": "string",
"enum": [
"new",
"base",
"rewritten",
"refixed"
],
"description": "State of the code the defect lived in: new | base (pre-existing, never worked) | rewritten | refixed (a previous fix did not hold)"
},
"classifiedAt": {
"type": "string",
"format": "date-time"
},
"revision": {
"type": "number"
},
"introducedInCommit": {
"type": "string",
"description": "The commit that introduced the defect, from bisect/blame. Omit for a defect in code that never worked — record age `base` instead.",
"nullable": true
},
"introducedInChangeId": {
"type": "string",
"description": "The change that introduced the defect. Server-derived from the commit's Change: trailer — not supplied by the caller.",
"nullable": true
},
"introducedAt": {
"type": "string",
"format": "date-time",
"nullable": true
},
"dormancyDays": {
"type": "number",
"nullable": true
},
"classifiedBy": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"user",
"agent",
"system"
],
"description": "Actor type"
},
"id": {
"type": "string",
"description": "Stable actor identifier"
},
"name": {
"type": "string",
"description": "Human-readable display name"
},
"apiKeyId": {
"type": "string",
"description": "API key ID when acting via API key",
"nullable": true
},
"apiKeyName": {
"type": "string",
"description": "User-assigned API key label",
"nullable": true
}
},
"required": [
"type",
"id",
"name"
],
"description": "Identity of the actor who performed an action",
"nullable": true
}
},
"required": [
"affects",
"impactSeverity",
"impactSeverityEvidence",
"foundBy",
"target",
"defectType",
"qualifier",
"age",
"classifiedAt",
"revision"
],
"description": "The defect a Fix change repaired — the realised counterpart of the change risk assessment",
"nullable": true
},
"createdBy": {
"type": "string",
"nullable": true
},
"createdByName": {
"type": "string"
},
"shippedRelease": {
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "ID of the release that delivered the change"
},
"version": {
"type": "string",
"description": "Version the change shipped in, e.g. v1.2.3"
}
},
"required": [
"releaseId",
"version"
],
"description": "Derived reference to the release that shipped a change"
},
"introducedInChange": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Display key of the referenced change, e.g. CHG-42"
},
"productSlug": {
"type": "string",
"description": "Slug of the product owning the referenced change; absent where that product has no slug",
"nullable": true
}
},
"required": [
"key"
],
"description": "Derived reference to another change, resolved from a stored change id"
}
},
"required": [
"_id",
"productId",
"key",
"title",
"type",
"stage",
"stageState",
"stamps",
"isCancelled",
"source",
"intent",
"userStoryIds",
"prUrls",
"relatedChangeIds",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "CHANGE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"key": "CHG-01",
"title": "Bulk CSV export",
"type": "feature",
"stage": "review",
"stageState": "inProgress",
"stageActor": {
"type": "agent",
"id": "definitionAgent",
"name": "Definition Agent"
},
"stamps": {
"accept": {
"startedAt": "2026-06-12T00:00:00.000Z",
"finishedAt": "2026-06-12T00:00:00.000Z"
},
"review": {
"startedAt": "2026-06-14T00:00:00.000Z"
}
},
"isCancelled": false,
"source": "external",
"intent": "Customers need to export their story list as CSV.",
"userStoryIds": [],
"prUrls": [],
"relatedChangeIds": [],
"createdAt": "2026-06-12T00:00:00.000Z",
"updatedAt": "2026-06-14T00:00:00.000Z"
}
product(7 tools)
createProduct
Create a new product definition
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Product name"
},
"teamId": {
"type": "string",
"description": "Team ID"
},
"description": {
"type": "string",
"description": "Product description"
},
"isTemplate": {
"type": "boolean",
"description": "True to create a template"
},
"repoId": {
"type": "string",
"description": "Associated repository ID"
},
"repoPackagePath": {
"type": "string",
"description": "Path to package within the repository"
},
"onboardingStatus": {
"type": "string",
"enum": [
"idle",
"onboarding",
"onboarded"
],
"description": "Initial onboarding status (defaults to idle)"
},
"createdFromTemplateId": {
"type": "string",
"description": "Non-functional provenance breadcrumb: the template this product was created from. Never read to alter behaviour."
}
},
"required": [
"name",
"teamId"
],
"description": "Create product request"
}
Example Input
{
"name": "My New Product",
"description": "A sample product description"
}
Output Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
}
},
"required": [
"productId"
],
"description": "Product selector"
}
Example Output
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
deleteProduct
Delete a product definition
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
}
},
"required": [
"productId"
],
"description": "Product selector"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {},
"description": "This operation returns no data; the response carries only the envelope meta."
}
getProduct
Get a product definition
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
}
},
"required": [
"productId"
],
"description": "Product selector"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Product ID"
},
"name": {
"type": "string",
"description": "Product name"
},
"createdAt": {
"type": "string",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"description": "Last update timestamp"
},
"teamId": {
"type": "string",
"description": "Team ID"
},
"createdBy": {
"type": "string",
"description": "User ID of creator"
},
"slug": {
"type": "string",
"description": "Globally-unique, URL-safe slug derived from the name at creation (server-generated; not client-editable)",
"nullable": true
},
"description": {
"type": "string",
"description": "Product description"
},
"status": {
"type": "string",
"enum": [
"draft",
"rejected",
"building",
"released",
"retired"
],
"description": "Product status"
},
"onboardingStatus": {
"type": "string",
"enum": [
"idle",
"onboarding",
"onboarded"
],
"description": "Product onboarding status"
},
"lastActivityAt": {
"type": "string",
"description": "Last activity timestamp"
},
"userId": {
"type": "string",
"description": "User ID (deprecated, use teamId)"
},
"isTemplate": {
"type": "boolean",
"description": "True if this product is a template"
},
"createdFromTemplateId": {
"type": "string",
"description": "Non-functional provenance breadcrumb: the template this product was created from (null if created directly).",
"nullable": true
},
"repoId": {
"type": "string",
"description": "Associated repository ID",
"nullable": true
},
"repoPackagePath": {
"type": "string",
"description": "Path to package within the repository",
"nullable": true
},
"onboardingProgress": {
"type": "object",
"properties": {
"completedSteps": {
"type": "array",
"items": {
"type": "string",
"enum": [
"productCreated",
"briefPopulated",
"areasCreated",
"storiesCreated",
"storiesValidated",
"discrepanciesFixed",
"architectureDefined",
"architectureSkipped"
],
"description": "Product onboarding workflow step"
},
"description": "Completed onboarding workflow steps"
}
},
"description": "Onboarding workflow progress"
},
"implementationStatus": {
"type": "string",
"enum": [
"idle",
"implementing",
"implemented"
],
"description": "Product implementation status"
},
"implementationProgress": {
"type": "object",
"properties": {
"scaffolded": {
"type": "boolean",
"description": "Whether the project has been scaffolded"
},
"areas": {
"type": "array",
"items": {
"type": "object",
"properties": {
"areaId": {
"type": "string",
"description": "Area ID"
},
"key": {
"type": "string",
"description": "Area key"
},
"status": {
"type": "string",
"enum": [
"pending",
"implementing",
"implemented"
],
"description": "Area implementation status"
}
},
"required": [
"areaId",
"key",
"status"
]
},
"description": "Per-area implementation progress"
}
},
"description": "Implementation workflow progress"
},
"changePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The judgement stage this override targets"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "The overriding driver (human | agent; never cicd)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Risk category this override applies to. Omitted = applies to every category.",
"nullable": true
}
},
"required": [
"stage",
"driver"
],
"description": "A product-level override of one judgement stage's driver (repo-first change config)"
},
"description": "Sparse override of the repository's change pipeline (CHG-50): the judgement stages (design, define, code, test, review, merge, push) whose driver this product sets differently from the repo default. Stage enablement, the CI/CD stages, and the git workflow are repo-level and cannot be overridden here; unset or empty = the repo default applies unchanged.",
"nullable": true
},
"brief": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Brief ID"
},
"productId": {
"type": "string",
"description": "Product ID"
},
"description": {
"type": "string",
"description": "Brief description"
},
"positioning": {
"type": "string",
"description": "Product positioning statement — market category, differentiation, competitive context"
},
"userId": {
"type": "string",
"description": "User ID"
},
"problem": {
"type": "object",
"properties": {
"summary": {
"type": "string"
},
"context": {
"type": "string"
},
"impact": {
"type": "string"
}
},
"required": [
"summary",
"context",
"impact"
],
"description": "Problem definition"
},
"users": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"goals": {
"type": "array",
"items": {
"type": "string"
}
},
"painPoints": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"title",
"description",
"goals",
"painPoints"
]
},
"description": "User personas"
},
"requirements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"must",
"should",
"could",
"wont"
]
}
},
"required": [
"id",
"title",
"description",
"priority"
]
},
"description": "Requirements"
},
"aesthetics": {
"type": "object",
"properties": {
"tone": {
"type": "string"
},
"visualStyle": {
"type": "string"
},
"interactionPrinciples": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"tone",
"visualStyle",
"interactionPrinciples"
],
"description": "Aesthetics"
},
"successCriteria": {
"type": "array",
"items": {
"type": "string"
},
"description": "Success criteria"
},
"outOfScope": {
"type": "array",
"items": {
"type": "string"
},
"description": "Out of scope items"
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"inspiration",
"competitor",
"other"
]
},
"url": {
"oneOf": [
{
"type": "string"
},
{
"type": "string"
},
{
"type": "string",
"enum": [
""
]
}
],
"description": "An absolute URL (https://example.com/doc), a repository-relative path to a project document (docs/onboarding.md), or \"\" when there is no link",
"nullable": true
},
"description": {
"type": "string"
}
},
"required": [
"type"
]
},
"description": "References"
},
"createdAt": {
"type": "string",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"description": "Last update timestamp"
}
},
"required": [
"_id",
"productId",
"description",
"positioning",
"userId",
"problem",
"users",
"requirements",
"aesthetics",
"successCriteria",
"outOfScope",
"references",
"createdAt",
"updatedAt"
],
"description": "Brief data"
}
},
"required": [
"_id",
"name",
"createdAt",
"updatedAt",
"teamId",
"createdBy"
],
"description": "Product view"
}
Example Output
{
"_id": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"name": "My Product",
"description": "A sample product",
"userId": "USER-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
getProductBySlug
Get a product definition by its globally-unique slug
Input Schema
{
"type": "object",
"properties": {
"slug": {
"type": "string",
"description": "Product slug"
}
},
"required": [
"slug"
],
"description": "Product slug selector"
}
Example Input
{
"slug": "my-product"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Product ID"
},
"name": {
"type": "string",
"description": "Product name"
},
"createdAt": {
"type": "string",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"description": "Last update timestamp"
},
"teamId": {
"type": "string",
"description": "Team ID"
},
"createdBy": {
"type": "string",
"description": "User ID of creator"
},
"slug": {
"type": "string",
"description": "Globally-unique, URL-safe slug derived from the name at creation (server-generated; not client-editable)",
"nullable": true
},
"description": {
"type": "string",
"description": "Product description"
},
"status": {
"type": "string",
"enum": [
"draft",
"rejected",
"building",
"released",
"retired"
],
"description": "Product status"
},
"onboardingStatus": {
"type": "string",
"enum": [
"idle",
"onboarding",
"onboarded"
],
"description": "Product onboarding status"
},
"lastActivityAt": {
"type": "string",
"description": "Last activity timestamp"
},
"userId": {
"type": "string",
"description": "User ID (deprecated, use teamId)"
},
"isTemplate": {
"type": "boolean",
"description": "True if this product is a template"
},
"createdFromTemplateId": {
"type": "string",
"description": "Non-functional provenance breadcrumb: the template this product was created from (null if created directly).",
"nullable": true
},
"repoId": {
"type": "string",
"description": "Associated repository ID",
"nullable": true
},
"repoPackagePath": {
"type": "string",
"description": "Path to package within the repository",
"nullable": true
},
"onboardingProgress": {
"type": "object",
"properties": {
"completedSteps": {
"type": "array",
"items": {
"type": "string",
"enum": [
"productCreated",
"briefPopulated",
"areasCreated",
"storiesCreated",
"storiesValidated",
"discrepanciesFixed",
"architectureDefined",
"architectureSkipped"
],
"description": "Product onboarding workflow step"
},
"description": "Completed onboarding workflow steps"
}
},
"description": "Onboarding workflow progress"
},
"implementationStatus": {
"type": "string",
"enum": [
"idle",
"implementing",
"implemented"
],
"description": "Product implementation status"
},
"implementationProgress": {
"type": "object",
"properties": {
"scaffolded": {
"type": "boolean",
"description": "Whether the project has been scaffolded"
},
"areas": {
"type": "array",
"items": {
"type": "object",
"properties": {
"areaId": {
"type": "string",
"description": "Area ID"
},
"key": {
"type": "string",
"description": "Area key"
},
"status": {
"type": "string",
"enum": [
"pending",
"implementing",
"implemented"
],
"description": "Area implementation status"
}
},
"required": [
"areaId",
"key",
"status"
]
},
"description": "Per-area implementation progress"
}
},
"description": "Implementation workflow progress"
},
"changePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The judgement stage this override targets"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "The overriding driver (human | agent; never cicd)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Risk category this override applies to. Omitted = applies to every category.",
"nullable": true
}
},
"required": [
"stage",
"driver"
],
"description": "A product-level override of one judgement stage's driver (repo-first change config)"
},
"description": "Sparse override of the repository's change pipeline (CHG-50): the judgement stages (design, define, code, test, review, merge, push) whose driver this product sets differently from the repo default. Stage enablement, the CI/CD stages, and the git workflow are repo-level and cannot be overridden here; unset or empty = the repo default applies unchanged.",
"nullable": true
},
"brief": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Brief ID"
},
"productId": {
"type": "string",
"description": "Product ID"
},
"description": {
"type": "string",
"description": "Brief description"
},
"positioning": {
"type": "string",
"description": "Product positioning statement — market category, differentiation, competitive context"
},
"userId": {
"type": "string",
"description": "User ID"
},
"problem": {
"type": "object",
"properties": {
"summary": {
"type": "string"
},
"context": {
"type": "string"
},
"impact": {
"type": "string"
}
},
"required": [
"summary",
"context",
"impact"
],
"description": "Problem definition"
},
"users": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"goals": {
"type": "array",
"items": {
"type": "string"
}
},
"painPoints": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"title",
"description",
"goals",
"painPoints"
]
},
"description": "User personas"
},
"requirements": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"title": {
"type": "string"
},
"description": {
"type": "string"
},
"priority": {
"type": "string",
"enum": [
"must",
"should",
"could",
"wont"
]
}
},
"required": [
"id",
"title",
"description",
"priority"
]
},
"description": "Requirements"
},
"aesthetics": {
"type": "object",
"properties": {
"tone": {
"type": "string"
},
"visualStyle": {
"type": "string"
},
"interactionPrinciples": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"tone",
"visualStyle",
"interactionPrinciples"
],
"description": "Aesthetics"
},
"successCriteria": {
"type": "array",
"items": {
"type": "string"
},
"description": "Success criteria"
},
"outOfScope": {
"type": "array",
"items": {
"type": "string"
},
"description": "Out of scope items"
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"type": {
"type": "string",
"enum": [
"inspiration",
"competitor",
"other"
]
},
"url": {
"oneOf": [
{
"type": "string"
},
{
"type": "string"
},
{
"type": "string",
"enum": [
""
]
}
],
"description": "An absolute URL (https://example.com/doc), a repository-relative path to a project document (docs/onboarding.md), or \"\" when there is no link",
"nullable": true
},
"description": {
"type": "string"
}
},
"required": [
"type"
]
},
"description": "References"
},
"createdAt": {
"type": "string",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"description": "Last update timestamp"
}
},
"required": [
"_id",
"productId",
"description",
"positioning",
"userId",
"problem",
"users",
"requirements",
"aesthetics",
"successCriteria",
"outOfScope",
"references",
"createdAt",
"updatedAt"
],
"description": "Brief data"
}
},
"required": [
"_id",
"name",
"createdAt",
"updatedAt",
"teamId",
"createdBy"
],
"description": "Product view"
}
Example Output
{
"_id": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"name": "My Product",
"slug": "my-product",
"description": "A sample product",
"userId": "USER-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
linkProductToRepo
Atomically link an existing product to an existing repo.products[] entry discovered by the scanner
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product to link"
},
"repoId": {
"type": "string",
"description": "Repo to link to"
},
"repoPackagePath": {
"type": "string",
"description": "Package path of the discovered repo.products[] entry to attach to"
}
},
"required": [
"productId",
"repoId",
"repoPackagePath"
],
"description": "Link an existing product to an existing repo.products[] entry"
}
Example Input
{
"productId": "PRODUCT-abcdef",
"repoId": "REPO-123456",
"repoPackagePath": "apps/defprod-front"
}
Output Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
}
},
"required": [
"productId"
],
"description": "Product selector"
}
Example Output
{
"productId": "PRODUCT-abcdef"
}
listProducts
List all product definitions
Input Schema
{
"type": "object",
"properties": {
"filter": {
"description": "Optional filter criteria for the list query"
},
"sort": {
"type": "object",
"additionalProperties": {
"oneOf": [
{
"type": "number",
"enum": [
1
]
},
{
"type": "number",
"enum": [
-1
]
}
]
},
"description": "Optional sort specification for the list"
},
"page": {
"type": "object",
"properties": {
"number": {
"type": "number",
"description": "The page number (1-indexed)"
},
"size": {
"type": "number",
"description": "The number of items per page"
}
},
"required": [
"number",
"size"
],
"description": "Optional pagination parameters for the list"
},
"teamId": {
"type": "string",
"description": "Optional team ID to list products for; user must have access"
},
"isTemplate": {
"type": "boolean",
"description": "If true list only templates; if false list only products; if omitted list all"
}
},
"description": "List products request"
}
Example Input
{
"page": 1,
"pageSize": 10
}
Output Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Product ID"
},
"name": {
"type": "string",
"description": "Product name"
},
"createdAt": {
"type": "string",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"description": "Last update timestamp"
},
"teamId": {
"type": "string",
"description": "Team ID"
},
"createdBy": {
"type": "string",
"description": "User ID of creator"
},
"slug": {
"type": "string",
"description": "Globally-unique, URL-safe slug derived from the name at creation (server-generated; not client-editable)",
"nullable": true
},
"description": {
"type": "string",
"description": "Product description"
},
"status": {
"type": "string",
"enum": [
"draft",
"rejected",
"building",
"released",
"retired"
],
"description": "Product status"
},
"onboardingStatus": {
"type": "string",
"enum": [
"idle",
"onboarding",
"onboarded"
],
"description": "Product onboarding status"
},
"lastActivityAt": {
"type": "string",
"description": "Last activity timestamp"
},
"userId": {
"type": "string",
"description": "User ID (deprecated, use teamId)"
},
"isTemplate": {
"type": "boolean",
"description": "True if this product is a template"
},
"createdFromTemplateId": {
"type": "string",
"description": "Non-functional provenance breadcrumb: the template this product was created from (null if created directly).",
"nullable": true
},
"repoId": {
"type": "string",
"description": "Associated repository ID",
"nullable": true
},
"repoPackagePath": {
"type": "string",
"description": "Path to package within the repository",
"nullable": true
},
"onboardingProgress": {
"type": "object",
"properties": {
"completedSteps": {
"type": "array",
"items": {
"type": "string",
"enum": [
"productCreated",
"briefPopulated",
"areasCreated",
"storiesCreated",
"storiesValidated",
"discrepanciesFixed",
"architectureDefined",
"architectureSkipped"
],
"description": "Product onboarding workflow step"
},
"description": "Completed onboarding workflow steps"
}
},
"description": "Onboarding workflow progress"
},
"implementationStatus": {
"type": "string",
"enum": [
"idle",
"implementing",
"implemented"
],
"description": "Product implementation status"
},
"implementationProgress": {
"type": "object",
"properties": {
"scaffolded": {
"type": "boolean",
"description": "Whether the project has been scaffolded"
},
"areas": {
"type": "array",
"items": {
"type": "object",
"properties": {
"areaId": {
"type": "string",
"description": "Area ID"
},
"key": {
"type": "string",
"description": "Area key"
},
"status": {
"type": "string",
"enum": [
"pending",
"implementing",
"implemented"
],
"description": "Area implementation status"
}
},
"required": [
"areaId",
"key",
"status"
]
},
"description": "Per-area implementation progress"
}
},
"description": "Implementation workflow progress"
},
"changePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The judgement stage this override targets"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "The overriding driver (human | agent; never cicd)"
},
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Risk category this override applies to. Omitted = applies to every category.",
"nullable": true
}
},
"required": [
"stage",
"driver"
],
"description": "A product-level override of one judgement stage's driver (repo-first change config)"
},
"description": "Sparse override of the repository's change pipeline (CHG-50): the judgement stages (design, define, code, test, review, merge, push) whose driver this product sets differently from the repo default. Stage enablement, the CI/CD stages, and the git workflow are repo-level and cannot be overridden here; unset or empty = the repo default applies unchanged.",
"nullable": true
}
},
"required": [
"_id",
"name",
"createdAt",
"updatedAt",
"teamId",
"createdBy"
],
"description": "Product"
}
}
Example Output
[
{
"_id": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"name": "My Product",
"description": "A sample product",
"userId": "USER-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:00:00Z"
}
]
patchProduct
Apply patch changes to a product definition
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"comment": {
"type": "string",
"description": "Patch comment"
}
},
"required": [
"productId",
"patch"
],
"description": "Parameters for patching a product"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/name",
"value": "Updated Product Name"
}
],
"comment": "Update product name"
}
Output Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"patchId": {
"type": "string",
"description": "Patch ID"
}
},
"required": [
"productId",
"patch",
"patchId"
],
"description": "Output for patching a product"
}
Example Output
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/name",
"value": "Updated Product Name"
}
],
"patchId": "PATCH-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
release(3 tools)
getRelease
Get a release (a per-product production-ship artifact) by id, including its version, the changes it delivered, and any release notes.
Input Schema
{
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "Release ID"
}
},
"required": [
"releaseId"
],
"description": "Get-release selector"
}
Example Input
{
"releaseId": "RELEASE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"version": {
"type": "string"
},
"changeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"shippedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"sourceRunId": {
"type": "string",
"nullable": true
},
"notes": {
"type": "string",
"nullable": true
}
},
"required": [
"_id",
"productId",
"version",
"changeIds",
"shippedAt",
"createdAt",
"updatedAt"
]
}
Example Output
{
"_id": "RELEASE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"version": "v1.2.3",
"changeIds": [
"CHANGE-1",
"CHANGE-2"
],
"sourceRunId": "CDRUN-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"notes": "## v1.2.3\n- Bulk CSV export",
"shippedAt": "2026-07-20T00:00:00.000Z",
"createdAt": "2026-07-20T00:00:00.000Z",
"updatedAt": "2026-07-20T00:00:00.000Z"
}
listReleases
List a product's releases, newest first — the version each shipped, the changes it delivered, and any release notes. This is the data behind the per-product Releases view.
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
}
},
"required": [
"productId"
],
"description": "Parameters for listing releases"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"productId": {
"type": "string"
},
"version": {
"type": "string"
},
"changeIds": {
"type": "array",
"items": {
"type": "string"
}
},
"shippedAt": {
"type": "string",
"format": "date-time"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"sourceRunId": {
"type": "string",
"nullable": true
},
"notes": {
"type": "string",
"nullable": true
}
},
"required": [
"_id",
"productId",
"version",
"changeIds",
"shippedAt",
"createdAt",
"updatedAt"
]
}
}
Example Output
[
{
"_id": "RELEASE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"version": "v1.2.3",
"changeIds": [
"CHANGE-1"
],
"sourceRunId": "CDRUN-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"shippedAt": "2026-07-20T00:00:00.000Z",
"createdAt": "2026-07-20T00:00:00.000Z",
"updatedAt": "2026-07-20T00:00:00.000Z"
}
]
patchRelease
Edit a release. Only the human-authored notes changelog (/notes) is editable; version, delivered changes, source run and shipped date are immutable records of what actually shipped.
Input Schema
{
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "Release ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations (release notes are the near-term editable field)"
},
"comment": {
"type": "string",
"description": "Patch comment"
}
},
"required": [
"releaseId",
"patch"
],
"description": "Parameters for patching a release (content only — version, changeIds and provenance are immutable)"
}
Example Input
{
"releaseId": "RELEASE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/notes",
"value": "## v1.2.3\n- Bulk CSV export\n- Bug fixes"
}
],
"comment": "Add changelog"
}
Output Schema
{
"type": "object",
"properties": {
"releaseId": {
"type": "string",
"description": "Release ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"patchId": {
"type": "string",
"description": "Patch ID"
}
},
"required": [
"releaseId",
"patch",
"patchId"
],
"description": "Output for patching a release"
}
Example Output
{
"releaseId": "RELEASE-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/notes",
"value": "## v1.2.3\n- Bulk CSV export\n- Bug fixes"
}
],
"patchId": "PATCH-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
repo(5 tools)
createRepo
Create a new repository connection
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Repository name"
},
"teamId": {
"type": "string",
"description": "Team ID"
},
"url": {
"type": "string",
"description": "Git clone URL"
},
"provider": {
"type": "string",
"enum": [
"github",
"gitlab",
"bitbucket",
"other"
],
"description": "Repository hosting provider"
}
},
"required": [
"name",
"teamId"
],
"description": "Create repo request"
}
Example Input
{
"name": "My Repo",
"teamId": "TEAM-example"
}
Output Schema
{
"type": "object",
"properties": {
"repoId": {
"type": "string",
"description": "Repo ID"
}
},
"required": [
"repoId"
],
"description": "Repo selector"
}
Example Output
{
"repoId": "REPO-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
deleteRepo
Delete a repository connection
Input Schema
{
"type": "object",
"properties": {
"repoId": {
"type": "string",
"description": "Repo ID"
}
},
"required": [
"repoId"
],
"description": "Repo selector"
}
Example Input
{
"repoId": "REPO-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {},
"description": "This operation returns no data; the response carries only the envelope meta."
}
getRepo
Get a repository by ID with discovered packages
Input Schema
{
"type": "object",
"properties": {
"repoId": {
"type": "string",
"description": "Repo ID"
}
},
"required": [
"repoId"
],
"description": "Repo selector"
}
Example Input
{
"repoId": "REPO-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Repo ID"
},
"teamId": {
"type": "string",
"description": "Team ID"
},
"name": {
"type": "string",
"description": "Repository name"
},
"onboardingStatus": {
"type": "string",
"enum": [
"initial",
"analysing",
"confirmed"
],
"description": "Onboarding status"
},
"discoveredPackages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Package name"
},
"path": {
"type": "string",
"description": "Package path within the repository"
},
"type": {
"type": "string",
"enum": [
"app",
"library"
],
"description": "Package type"
},
"productId": {
"type": "string",
"description": "Linked product ID, once mapped"
}
},
"required": [
"name",
"path",
"type"
],
"description": "Discovered package within a repository"
},
"description": "Discovered packages within the repository"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Human-readable product name"
},
"mappingType": {
"type": "string",
"enum": [
"single",
"partial",
"multiple"
],
"description": "How packages map to this product"
},
"packagePaths": {
"type": "array",
"items": {
"type": "string"
},
"description": "Package paths within the repository"
},
"productId": {
"type": "string",
"description": "Linked product ID, populated by backend when product is created"
}
},
"required": [
"name",
"mappingType",
"packagePaths"
],
"description": "User-confirmed product mapping within a repository"
},
"description": "User-confirmed product mappings"
},
"createdAt": {
"type": "string",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"description": "Last update timestamp"
},
"url": {
"type": "string",
"description": "Git clone URL"
},
"provider": {
"type": "string",
"enum": [
"github",
"gitlab",
"bitbucket",
"other"
],
"description": "Repository hosting provider"
},
"bootstrapCommand": {
"type": "string",
"description": "Templated command that scaffolds a new app from this starter repo, e.g. \"npx tsx scripts/generate-app.ts {{parentDir}} {{appName}}\". Read as a string when realizing a product from a template; DefProd never executes it."
},
"changePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Repo-level change pipeline: which stages are enabled and who drives each, applied to every product in this repo by default (CHG-50). Products may override only judgement-stage drivers; unset = built-in defaults.",
"nullable": true
},
"changePipelinePresets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "The risk category this pipeline applies to"
},
"pipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "The complete pipeline for that category"
}
},
"required": [
"category",
"pipeline"
],
"description": "A repo-level pipeline preset for one risk category"
},
"description": "Repo-level pipeline presets, one complete pipeline per risk category (low | medium | high). The assessed category selects one of these. Unset for a category = fall back to the single changePipeline above, then to the built-in preset for that category.",
"nullable": true
},
"changeTrackingScope": {
"type": "string",
"enum": [
"all",
"decisions"
],
"description": "Whether all change work in this repo is expected to carry a change record, or only work carrying a decision (all | decisions). Unset = all. A default posture, not an enforceable mandate.",
"nullable": true
},
"autoConfirmPipelineCategories": {
"type": "array",
"items": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"description": "Risk categories whose pipeline is confirmed automatically as part of recording the assessment, with no human step. Unset = low only; an explicit empty array means confirm nothing automatically.",
"nullable": true
},
"allowConfirmedPipelineOverride": {
"type": "boolean",
"description": "Whether a caller confirming a pipeline may deviate from the category's preset by overriding judgement-stage drivers. Unset = false: the preset is confirmed as resolved, and supplying overrides is rejected.",
"nullable": true
},
"applyConfirmedPipeline": {
"type": "boolean",
"description": "Whether the pipeline confirmed on a change GOVERNS how that change is driven, rather than only recording what its risk category selected (D58). Unset = false: changes in this repo are driven exactly as the configuration resolves, whether or not they carry a confirmation. Withdrawing it takes effect on changes already in flight.",
"nullable": true
},
"changeWalkthroughEnabled": {
"type": "boolean",
"description": "Whether change work in this repo produces a demonstration walkthrough for reviewers, read by the tooling that produces them. Unset = false: no walkthrough is produced.",
"nullable": true
},
"lastAnalysedAt": {
"type": "string",
"description": "Last analysis timestamp"
}
},
"required": [
"_id",
"teamId",
"name",
"onboardingStatus",
"discoveredPackages",
"products",
"createdAt",
"updatedAt"
],
"description": "Repository"
}
listRepos
List repositories for a team
Input Schema
{
"type": "object",
"properties": {
"teamId": {
"type": "string",
"description": "Team ID (required for team-scoped keys, optional for repo-scoped keys)"
}
},
"description": "List repos input"
}
Example Input
{
"teamId": "TEAM-example"
}
Output Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Repo ID"
},
"teamId": {
"type": "string",
"description": "Team ID"
},
"name": {
"type": "string",
"description": "Repository name"
},
"onboardingStatus": {
"type": "string",
"enum": [
"initial",
"analysing",
"confirmed"
],
"description": "Onboarding status"
},
"discoveredPackages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Package name"
},
"path": {
"type": "string",
"description": "Package path within the repository"
},
"type": {
"type": "string",
"enum": [
"app",
"library"
],
"description": "Package type"
},
"productId": {
"type": "string",
"description": "Linked product ID, once mapped"
}
},
"required": [
"name",
"path",
"type"
],
"description": "Discovered package within a repository"
},
"description": "Discovered packages within the repository"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Human-readable product name"
},
"mappingType": {
"type": "string",
"enum": [
"single",
"partial",
"multiple"
],
"description": "How packages map to this product"
},
"packagePaths": {
"type": "array",
"items": {
"type": "string"
},
"description": "Package paths within the repository"
},
"productId": {
"type": "string",
"description": "Linked product ID, populated by backend when product is created"
}
},
"required": [
"name",
"mappingType",
"packagePaths"
],
"description": "User-confirmed product mapping within a repository"
},
"description": "User-confirmed product mappings"
},
"createdAt": {
"type": "string",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"description": "Last update timestamp"
},
"url": {
"type": "string",
"description": "Git clone URL"
},
"provider": {
"type": "string",
"enum": [
"github",
"gitlab",
"bitbucket",
"other"
],
"description": "Repository hosting provider"
},
"bootstrapCommand": {
"type": "string",
"description": "Templated command that scaffolds a new app from this starter repo, e.g. \"npx tsx scripts/generate-app.ts {{parentDir}} {{appName}}\". Read as a string when realizing a product from a template; DefProd never executes it."
},
"changePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Repo-level change pipeline: which stages are enabled and who drives each, applied to every product in this repo by default (CHG-50). Products may override only judgement-stage drivers; unset = built-in defaults.",
"nullable": true
},
"changePipelinePresets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "The risk category this pipeline applies to"
},
"pipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "The complete pipeline for that category"
}
},
"required": [
"category",
"pipeline"
],
"description": "A repo-level pipeline preset for one risk category"
},
"description": "Repo-level pipeline presets, one complete pipeline per risk category (low | medium | high). The assessed category selects one of these. Unset for a category = fall back to the single changePipeline above, then to the built-in preset for that category.",
"nullable": true
},
"changeTrackingScope": {
"type": "string",
"enum": [
"all",
"decisions"
],
"description": "Whether all change work in this repo is expected to carry a change record, or only work carrying a decision (all | decisions). Unset = all. A default posture, not an enforceable mandate.",
"nullable": true
},
"autoConfirmPipelineCategories": {
"type": "array",
"items": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"description": "Risk categories whose pipeline is confirmed automatically as part of recording the assessment, with no human step. Unset = low only; an explicit empty array means confirm nothing automatically.",
"nullable": true
},
"allowConfirmedPipelineOverride": {
"type": "boolean",
"description": "Whether a caller confirming a pipeline may deviate from the category's preset by overriding judgement-stage drivers. Unset = false: the preset is confirmed as resolved, and supplying overrides is rejected.",
"nullable": true
},
"applyConfirmedPipeline": {
"type": "boolean",
"description": "Whether the pipeline confirmed on a change GOVERNS how that change is driven, rather than only recording what its risk category selected (D58). Unset = false: changes in this repo are driven exactly as the configuration resolves, whether or not they carry a confirmation. Withdrawing it takes effect on changes already in flight.",
"nullable": true
},
"changeWalkthroughEnabled": {
"type": "boolean",
"description": "Whether change work in this repo produces a demonstration walkthrough for reviewers, read by the tooling that produces them. Unset = false: no walkthrough is produced.",
"nullable": true
},
"lastAnalysedAt": {
"type": "string",
"description": "Last analysis timestamp"
}
},
"required": [
"_id",
"teamId",
"name",
"onboardingStatus",
"discoveredPackages",
"products",
"createdAt",
"updatedAt"
],
"description": "Repository"
}
}
patchRepo
Apply patch changes to a repository (e.g. update discovered packages, link packages to products)
Input Schema
{
"type": "object",
"properties": {
"repoId": {
"type": "string",
"description": "Repo ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"comment": {
"type": "string",
"description": "Patch comment"
}
},
"required": [
"repoId",
"patch"
],
"description": "Parameters for patching a repo"
}
Example Input
{
"repoId": "REPO-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/discoveredPackages",
"value": [
{
"name": "web-app",
"path": "apps/web",
"type": "app"
}
]
}
]
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Repo ID"
},
"teamId": {
"type": "string",
"description": "Team ID"
},
"name": {
"type": "string",
"description": "Repository name"
},
"onboardingStatus": {
"type": "string",
"enum": [
"initial",
"analysing",
"confirmed"
],
"description": "Onboarding status"
},
"discoveredPackages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Package name"
},
"path": {
"type": "string",
"description": "Package path within the repository"
},
"type": {
"type": "string",
"enum": [
"app",
"library"
],
"description": "Package type"
},
"productId": {
"type": "string",
"description": "Linked product ID, once mapped"
}
},
"required": [
"name",
"path",
"type"
],
"description": "Discovered package within a repository"
},
"description": "Discovered packages within the repository"
},
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Human-readable product name"
},
"mappingType": {
"type": "string",
"enum": [
"single",
"partial",
"multiple"
],
"description": "How packages map to this product"
},
"packagePaths": {
"type": "array",
"items": {
"type": "string"
},
"description": "Package paths within the repository"
},
"productId": {
"type": "string",
"description": "Linked product ID, populated by backend when product is created"
}
},
"required": [
"name",
"mappingType",
"packagePaths"
],
"description": "User-confirmed product mapping within a repository"
},
"description": "User-confirmed product mappings"
},
"createdAt": {
"type": "string",
"description": "Creation timestamp"
},
"updatedAt": {
"type": "string",
"description": "Last update timestamp"
},
"url": {
"type": "string",
"description": "Git clone URL"
},
"provider": {
"type": "string",
"enum": [
"github",
"gitlab",
"bitbucket",
"other"
],
"description": "Repository hosting provider"
},
"bootstrapCommand": {
"type": "string",
"description": "Templated command that scaffolds a new app from this starter repo, e.g. \"npx tsx scripts/generate-app.ts {{parentDir}} {{appName}}\". Read as a string when realizing a product from a template; DefProd never executes it."
},
"changePipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "Repo-level change pipeline: which stages are enabled and who drives each, applied to every product in this repo by default (CHG-50). Products may override only judgement-stage drivers; unset = built-in defaults.",
"nullable": true
},
"changePipelinePresets": {
"type": "array",
"items": {
"type": "object",
"properties": {
"category": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "The risk category this pipeline applies to"
},
"pipeline": {
"type": "array",
"items": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"enum": [
"accept",
"design",
"define",
"code",
"test",
"review",
"merge",
"push",
"build",
"verify",
"package",
"staging",
"smoke",
"ship"
],
"description": "The pipeline stage this entry configures"
},
"enabled": {
"type": "boolean",
"description": "Whether this stage exists in the product's pipeline (accept/ship cannot be disabled)"
},
"driver": {
"type": "string",
"enum": [
"human",
"agent",
"cicd"
],
"description": "Who drives this stage (human | agent | cicd)"
},
"approvalsRequired": {
"type": "number",
"description": "Human approvals required for this stage (1 or 2; inert unless the driver is human). Defaults to 1.",
"nullable": true
}
},
"required": [
"stage",
"enabled",
"driver"
],
"description": "Configuration of one pipeline stage for a product"
},
"description": "The complete pipeline for that category"
}
},
"required": [
"category",
"pipeline"
],
"description": "A repo-level pipeline preset for one risk category"
},
"description": "Repo-level pipeline presets, one complete pipeline per risk category (low | medium | high). The assessed category selects one of these. Unset for a category = fall back to the single changePipeline above, then to the built-in preset for that category.",
"nullable": true
},
"changeTrackingScope": {
"type": "string",
"enum": [
"all",
"decisions"
],
"description": "Whether all change work in this repo is expected to carry a change record, or only work carrying a decision (all | decisions). Unset = all. A default posture, not an enforceable mandate.",
"nullable": true
},
"autoConfirmPipelineCategories": {
"type": "array",
"items": {
"type": "string",
"enum": [
"low",
"medium",
"high"
],
"description": "Assessed risk category (low | medium | high) — derived from the S/O/D vector, never supplied by the caller"
},
"description": "Risk categories whose pipeline is confirmed automatically as part of recording the assessment, with no human step. Unset = low only; an explicit empty array means confirm nothing automatically.",
"nullable": true
},
"allowConfirmedPipelineOverride": {
"type": "boolean",
"description": "Whether a caller confirming a pipeline may deviate from the category's preset by overriding judgement-stage drivers. Unset = false: the preset is confirmed as resolved, and supplying overrides is rejected.",
"nullable": true
},
"applyConfirmedPipeline": {
"type": "boolean",
"description": "Whether the pipeline confirmed on a change GOVERNS how that change is driven, rather than only recording what its risk category selected (D58). Unset = false: changes in this repo are driven exactly as the configuration resolves, whether or not they carry a confirmation. Withdrawing it takes effect on changes already in flight.",
"nullable": true
},
"changeWalkthroughEnabled": {
"type": "boolean",
"description": "Whether change work in this repo produces a demonstration walkthrough for reviewers, read by the tooling that produces them. Unset = false: no walkthrough is produced.",
"nullable": true
},
"lastAnalysedAt": {
"type": "string",
"description": "Last analysis timestamp"
}
},
"required": [
"_id",
"teamId",
"name",
"onboardingStatus",
"discoveredPackages",
"products",
"createdAt",
"updatedAt"
],
"description": "Repository"
}
userStory(5 tools)
createUserStory
Create a new user story
Input Schema
{
"type": "object",
"properties": {
"title": {
"type": "string",
"description": "User story title"
},
"key": {
"type": "string",
"description": "User story key — must start with the area key followed by \"-\" (e.g. \"NETWORK-01\" for area NETWORK)"
},
"productId": {
"type": "string",
"description": "Product ID"
},
"status": {
"type": "string",
"enum": [
"backlog",
"ready",
"inProgress",
"review",
"testing",
"completed"
],
"description": "User story status"
},
"priority": {
"type": "string",
"enum": [
"high",
"medium",
"low"
],
"description": "User story priority"
},
"acceptanceCriteria": {
"type": "array",
"items": {
"type": "string"
},
"description": "User story acceptance criteria"
},
"description": {
"type": "string",
"description": "User story description"
},
"areaId": {
"type": "string",
"description": "Area ID. Supply areaId or areaKey; if both are supplied they must refer to the same area."
},
"areaKey": {
"type": "string",
"description": "Area key (e.g. \"NETWORK\"). Supply areaId or areaKey; if both are supplied they must refer to the same area. Prefer areaKey over areaId to avoid carrying opaque UUIDs."
},
"surface": {
"type": "string",
"enum": [
"ui",
"api",
"mcp",
"cli",
"system",
"other"
],
"description": "Test surface that covers this story. Optional."
},
"testExemptReason": {
"type": "string",
"description": "Reason this story has no automatable test surface (e.g. LLM behaviour, agent-run skill). When set, the story is exempt from coverage expectations. Human-authored only. Optional."
}
},
"required": [
"title",
"key",
"productId",
"status",
"priority",
"acceptanceCriteria"
],
"description": "Create user story request"
}
Example Input
{
"title": "User Story Title",
"description": "User story description",
"key": "US-001",
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"status": "todo",
"priority": "medium",
"acceptanceCriteria": [
"Criterion 1",
"Criterion 2"
]
}
Output Schema
{
"type": "object",
"properties": {
"userStoryId": {
"type": "string",
"description": "User story ID"
}
},
"required": [
"userStoryId"
],
"description": "User story selector"
}
Example Output
{
"userStoryId": "USER_STORY-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
deleteUserStory
Delete a user story
Input Schema
{
"type": "object",
"properties": {
"userStoryId": {
"type": "string",
"description": "User story ID"
}
},
"required": [
"userStoryId"
],
"description": "User story selector"
}
Example Input
{
"userStoryId": "USERSTORY-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {},
"description": "This operation returns no data; the response carries only the envelope meta."
}
getUserStory
Get a user story
Input Schema
{
"type": "object",
"properties": {
"userStoryId": {
"type": "string",
"description": "User story ID"
}
},
"required": [
"userStoryId"
],
"description": "User story selector"
}
Example Input
{
"userStoryId": "USERSTORY-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"title": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"key": {
"type": "string"
},
"description": {
"type": "string",
"description": "Format: As a [role], I want [action] so that [benefit]"
},
"acceptanceCriteria": {
"type": "array",
"items": {
"type": "string"
}
},
"priority": {
"type": "string",
"enum": [
"high",
"medium",
"low"
]
},
"status": {
"type": "string",
"enum": [
"backlog",
"ready",
"inProgress",
"review",
"testing",
"completed"
]
},
"surface": {
"type": "string",
"enum": [
"ui",
"api",
"mcp",
"cli",
"system",
"other"
],
"nullable": true
},
"testExemptReason": {
"type": "string",
"nullable": true
},
"storyPoints": {
"type": "number"
},
"assigneeId": {
"type": "string"
},
"areaId": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"order": {
"type": "number"
}
},
"required": [
"_id",
"title",
"createdAt",
"updatedAt",
"key"
]
}
Example Output
{
"_id": "USERSTORY-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"title": "User can log in",
"description": "As a user, I want to log in so that I can access my account",
"priority": "high",
"status": "todo",
"storyPoints": 5,
"key": "US-001",
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
listUserStories
List user stories for a product
Input Schema
{
"type": "object",
"properties": {
"productId": {
"type": "string",
"description": "Product ID"
},
"areaId": {
"type": "string",
"description": "Optional area ID to filter user stories by area"
}
},
"required": [
"productId"
],
"description": "Parameters for fetching user stories by product ID"
}
Example Input
{
"productId": "PRODUCT-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}
Output Schema
{
"type": "array",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string"
},
"title": {
"type": "string"
},
"createdAt": {
"type": "string",
"format": "date-time"
},
"updatedAt": {
"type": "string",
"format": "date-time"
},
"key": {
"type": "string"
},
"description": {
"type": "string",
"description": "Format: As a [role], I want [action] so that [benefit]"
},
"acceptanceCriteria": {
"type": "array",
"items": {
"type": "string"
}
},
"priority": {
"type": "string",
"enum": [
"high",
"medium",
"low"
]
},
"status": {
"type": "string",
"enum": [
"backlog",
"ready",
"inProgress",
"review",
"testing",
"completed"
]
},
"surface": {
"type": "string",
"enum": [
"ui",
"api",
"mcp",
"cli",
"system",
"other"
],
"nullable": true
},
"testExemptReason": {
"type": "string",
"nullable": true
},
"storyPoints": {
"type": "number"
},
"assigneeId": {
"type": "string"
},
"areaId": {
"type": "string"
},
"tags": {
"type": "array",
"items": {
"type": "string"
}
},
"metadata": {
"type": "object",
"additionalProperties": {}
},
"order": {
"type": "number"
}
},
"required": [
"_id",
"title",
"createdAt",
"updatedAt",
"key"
]
}
}
Example Output
[
{
"_id": "USERSTORY-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"title": "User can log in",
"description": "As a user, I want to log in so that I can access my account",
"priority": "high",
"status": "todo",
"storyPoints": 5,
"key": "US-001",
"createdAt": "2024-01-01T00:00:00.000Z",
"updatedAt": "2024-01-01T00:00:00.000Z"
}
]
patchUserStory
Apply patch changes to a user story
Input Schema
{
"type": "object",
"properties": {
"userStoryId": {
"type": "string",
"description": "User story ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"comment": {
"type": "string",
"description": "Patch comment"
}
},
"required": [
"userStoryId",
"patch"
],
"description": "Parameters for patching a user story"
}
Example Input
{
"userStoryId": "USER_STORY-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/name",
"value": "Updated Story Name"
}
],
"comment": "Update story name"
}
Output Schema
{
"type": "object",
"properties": {
"userStoryId": {
"type": "string",
"description": "User story ID"
},
"patch": {
"type": "array",
"items": {
"type": "object",
"properties": {
"op": {
"type": "string",
"enum": [
"add",
"remove",
"replace",
"move",
"copy",
"test"
],
"description": "The operation type"
},
"path": {
"type": "string",
"description": "JSON pointer format path (e.g., \"/requirements/0/title\")"
},
"value": {
"description": "Value for add/replace operations"
},
"from": {
"type": "string",
"description": "Source path for move/copy operations"
}
},
"required": [
"op",
"path"
],
"description": "A single JSON Patch operation (RFC 6902)"
},
"description": "JSON Patch operations"
},
"patchId": {
"type": "string",
"description": "Patch ID"
}
},
"required": [
"userStoryId",
"patch",
"patchId"
],
"description": "Output for patching a user story"
}
Example Output
{
"userStoryId": "USER_STORY-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb",
"patch": [
{
"op": "replace",
"path": "/name",
"value": "Updated Story Name"
}
],
"patchId": "PATCH-f97658ab-4af4-420a-a1a3-2f2b3ae70bdb"
}