Coming soon · Contract draft

Risks, Dependencies & Blockers

Planned

A common issue and dependency contract across project risks, execution blockers, gaps, and resolution items.

Reviewable specification — not callable

Documentation-first contract draft. The proposed additions on this page are not callable or available yet. Paths, payloads, scopes, names, and examples are intentionally concrete so customers can review the intended contract before and during implementation.

Canonical owner

Risk, dependency, blocker, and resolution services

Contract posture

P1 · Documentation first · implementation follows approval

Contract metadata

Draft version

0.2 review draft

Review owner

Delivery/Execute + Developer Platform

Last reviewed

July 14, 2026

Target wave

Wave 2 · Project and Execute core

Contract dependencies

• Canonical domain service adapter
• Optimistic concurrency and idempotency policy
• Transactional event outbox

What this unlocks

Unify issue visibility

Read a stable domain model for risks, dependencies & blockers without depending on GUI routes or database shapes.

Link cross-project dependencies

Create a reviewable proposal and apply only the bounded commands the canonical owner permits.

Coordinate resolution safely

React to durable lifecycle facts and connect external systems with explicit direction and provenance.

Lifecycle and invariants

Risks, Dependencies & Blockers exposes a bounded lifecycle with explicit commands and named authority at every transition.

openmitigatingblockedresolvedaccepted

From	To	Command	Authority
open	mitigating	Start mitigation	Risk, dependency, and blocker services
mitigating	resolved	Resolve issue	Risk, dependency, and blocker services
open	accepted	Accept risk	Risk, dependency, and blocker services

Lifecycle invariants

• Every issue retains source provenance.
• Resolution requires evidence or an attributable acceptance decision.

Authority boundaries

The interfaces expose canonical capabilities; they do not become a second owner of domain rules or state.

DigitalStack owns

• Canonical issue identity and type
• Dependency linkage and status
• Resolution history and threshold state

Explicitly not building

• Merging distinct sources without provenance
• Agent-declared resolution without evidence
• Event emission for every transient score change

Surface decisions

Deliberate additions, retained boundaries, and removals from the proposed external contract.

add

Canonical CRUD, dependency linkage, resolution, and threshold history

Integrators need one issue vocabulary across risks, blockers, gaps, and dependencies.

keep

Aggregate risk read and source provenance

Existing agent reads are useful when drill-down remains bounded.

remove

Automatic resolution and events for every score fluctuation

Transient projections are not durable business facts.

add

Project/engagement-scoped filtering on every read and command

A workspace API key is not a licence to read every project. Access composes workspace membership with per-project visibility, so integrators receive exactly the engagements they are entitled to.

Interface plan

REST API

Planned

Versioned risks, dependencies & blockers resources, commands, idempotency, and operation status.

Reads + explicit commands

GraphQL

Planned

Composable DeliveryRisk reads with mutations delegated to the same canonical domain service.

Composable reads + bounded delegated mutations

MCP / Agent API

Planned

Bounded read, draft, and confirmed apply tools with evidence and audit attribution.

Read + proposal/confirmed commands only

Webhooks

Planned

Past-tense delivery risk lifecycle facts with minimal payloads.

Past-tense durable facts only

Connected Apps

Planned

Issue trackers / Slack / Teams plus consumer clients, with declared direction and authority.

Declared direction and field authority required

Cross-interface parity

Each surface delegates to the named canonical owner; a blank surface is an intentional denial of authority, not missing documentation.

Capability	REST	GraphQL	MCP	Webhook	Canonical owner
Primary read	GET /delivery/risks	deliveryRisk(id: ID!): DeliveryRisk	get_risks_dependencies	—	Risk, dependency, blocker, and resolution services
Primary command	POST /delivery/risks	draftDeliveryRiskChange(input: DraftDeliveryRiskChangeInput!): DeliveryRiskChangeProposal!	draft_risks_dependencies_change	delivery_risk.created	Risk, dependency, blocker, and resolution services

Proposed scopes

Proposed scopes are not grantable yet.

delivery-risks:readplanned scope

Read governed risks, dependencies & blockers resources.

delivery-risks:writeplanned scope

Create and edit bounded risks, dependencies & blockers fields.

delivery-risks:operateplanned scope

Run explicit risks, dependencies & blockers lifecycle commands.

Behavioral contract

Cross-cutting rules every implementation and interface must satisfy.

Project / engagement-scoped access

A project and its engagement are the same object here. Resources are scoped to the projects the principal can access: workspace membership plus project-level visibility — owners and admins see every project, other principals see only the projects they created, were role-assigned, or were added to as members. List endpoints return only visible projects’ resources; detail endpoints enforce that visibility before returning or changing anything.

Canonical delegation

Every interface delegates to Risk, dependency, blocker, and resolution services; no resolver, gateway, worker, or connector reimplements domain rules.

Least-privilege principals

Scopes are evaluated with tenant, role, field-visibility, and principal-type constraints before data is read or changed.

Safe writes

Mutations use explicit confirmation where required, optimistic concurrency, idempotency, and durable actor attribution.

Transactional facts

Webhook facts are emitted from the canonical commit path, versioned, minimal, and safe to redeliver.

Declared provider authority

Every Connected App declares direction, field authority, provenance, and conflict behavior before activation.

REST API

Proposed endpoints

Planned

GET/api/v1/delivery/risks

List risks, dependencies & blockers

Return an authorized, paginated collection with stable filters and provenance.

delivery-risks:read

POST/api/v1/delivery/risksconfirmation

Create DeliveryRisk

Create one canonical resource with idempotency and actor attribution.

delivery-risks:write

GET/api/v1/delivery/risks/{id}

Retrieve DeliveryRisk

Return canonical detail, lifecycle state, permissions, and allowed actions.

delivery-risks:read

PATCH/api/v1/delivery/risks/{id}confirmation

Update DeliveryRisk

Update bounded editable fields using optimistic versioning.

delivery-risks:write

POST/api/v1/delivery/risks/{id}/resolveconfirmation

resolve DeliveryRisk

Run one explicit domain command after validation and authorization.

delivery-risks:operate

resolve a DeliveryRisk

Planned request

curl --request POST \
+  --url https://www.digitalstack360.com/api/v1/delivery/risks/delivery_risk_123/resolve \
+  --header "Authorization: Bearer $DSTACK_API_KEY" \
+  --header "Content-Type: application/json" \
+  --header "Idempotency-Key: risks-dependencies-resolve-v2" \
+  --data '{
    "expected_version": 2,
    "reason": "Confirmed through the reviewed integration workflow"
  }'

Planned response

{
  "data": {
    "id": "delivery_risk_123",
    "status": "resolved",
    "version": 3,
    "operation_id": "op_01k4..."
  }
}

GraphQL

Proposed graph

Planned

Types

DeliveryRisk

DeliveryRiskConnection

DeliveryRiskChangeProposal

Operation

Queries

deliveryRisk(id: ID!): DeliveryRisk

deliveryRiskList(filter: DeliveryRiskFilter, pagination: PaginationInput): DeliveryRiskConnection!

Mutations

draftDeliveryRiskChange(input: DraftDeliveryRiskChangeInput!): DeliveryRiskChangeProposal!

applyDeliveryRiskChange(input: ApplyDeliveryRiskChangeInput!): DeliveryRiskPayload!

Planned GraphQL query

query DeliveryRiskDetail($id: ID!) {
  deliveryRisk(id: $id) {
    id
    status
    version
    updatedAt
    allowedActions { id label requiresConfirmation }
    source { kind externalId }
  }
}

MCP / Agent API

Proposed tools

Planned

Get Risks, Dependencies & Blockers

get_risks_dependencies

Planned

Read the authorized risks, dependencies & blockers state, provenance, and allowed actions.

Scope: delivery-risks:read
Input: Resource id or a bounded filter.
Output: Canonical detail with source provenance and allowed actions.
Write boundary: Read only.

Draft Risks, Dependencies & Blockers change

draft_risks_dependencies_change

Planned

Build a reviewable proposal from explicit user intent and DigitalStack evidence.

Scope: delivery-risks:write
Input: Target, requested outcome, expected version, and optional evidence references.
Output: A persisted proposal, validation results, and conflicts.
Write boundary: Creates a proposal; it does not mutate canonical state.

Apply Risks, Dependencies & Blockers change

apply_risks_dependencies_change

Planned

Apply a reviewed proposal through the canonical service.

Scope: delivery-risks:operate
Input: Proposal id, expected version, idempotency key, and explicit confirmation.
Output: Updated canonical resource and audit reference.
Write boundary: Confirmation, optimistic versioning, and idempotency required.

Planned agent workflow

User: Review the proposed risks, dependencies & blockers change and help me apply it.

1. Call get_risks_dependencies to inspect current state, provenance, and allowed actions.
2. Call draft_risks_dependencies_change to create a proposal without changing canonical state.
3. Show validation results, conflicts, and the exact command to the user.
4. After explicit confirmation, call apply_risks_dependencies_change with the proposal version.

Never infer authority from access to the MCP client.

Webhooks

Proposed event catalog

Planned

Event types

delivery_risk.createdplanned event

A canonical DeliveryRisk was created.

payload: delivery_risk_id, status, created_at

delivery_risk.updatedplanned event

Governed DeliveryRisk fields changed.

payload: delivery_risk_id, changed_fields, version, occurred_at

delivery_risk.resolvedplanned event

The resolve command completed.

payload: delivery_risk_id, prior_status, status, occurred_at

Planned event example

{
  "event_id": "evt_01k4...",
  "type": "delivery_risk.resolved",
  "event_version": 1,
  "occurred_at": "2026-07-16T14:22:04Z",
  "workspace_id": "ws_abc123",
  "resource": {
    "type": "delivery_risk",
    "id": "delivery_risk_123"
  },
  "actor": {
    "id": "user_123"
  },
  "payload": {
    "delivery_risk_id": "delivery_risk_123",
    "prior_status": "draft",
    "status": "resolved"
  },
  "source": null
}

Connected Apps

Proposed connection roles

Planned

Claude / ChatGPT / IDE clients

Consumer application

Read, explain, and submit bounded risks, dependencies & blockers proposals through MCP.

Authority: Client access never implies domain approval or unrestricted mutation authority.

Issue trackers / Slack / Teams

Source connector

Supply issue evidence and escalation context.

Authority: Source records map into canonical issues; they do not replace them.

Open contract decisions

Resolve before implementation approval

• Should accepted risk and resolved risk remain separate terminal states across every source type?

Proof obligations

Must remain true	Failure indicator
Risk, dependency, blocker, and resolution services remains the singular canonical owner.	An interface or connector persists a second authoritative lifecycle state.
Draft and apply remain separate actions.	An agent or integration silently converts inferred intent into a canonical mutation.
Every write is attributable, versioned, and idempotent.	A retry duplicates work or stale state overwrites a newer human decision.
Connected App direction and field authority are explicit.	Provider data silently becomes canonical or conflicts are resolved without policy.