Dots Constellation Die
Docs

CLI IAGREED Stage Artifact Writing

Write a completed IAGREED stage artifact and its provenance edges atomically through one system-trust CLI command.

Overview

Description

IAGREED Stage Artifact Writing gives pipeline orchestrators a dedicated command for landing a stage result and its provenance without assembling several unrelated row and edge calls. dots stage-artifacts write validates the stage-completion payload, creates or updates the typed Artifacts record, and writes its produces and iagreed_stage_artifact provenance relationships through a system-trust service boundary.

The workflow is designed for operators and coding agents. It uses the same authenticated, company-scoped service contracts as the rest of Dots, so terminal or protocol convenience never creates a second source of truth. Inputs are validated before or at the route boundary, and outputs preserve identifiers and structured details needed for a reliable next step.

Selling Points

  • Keeps stage output and provenance synchronized as one intentional operation.
  • Prevents orchestrators from inventing artifact shapes or relationship vocabulary.
  • Produces a durable handoff object other stages can resolve by canonical id.
  • Reduces partial-state failures between an artifact row and its required edges.
  • Supports headless pipeline execution with structured confirmation output.

User Story

After a planning stage finishes, an orchestrator supplies the validated artifact body and source handles to one CLI command. The next stage can resolve the durable artifact and traverse its provenance without reconstructing which plan produced it. The result is a concrete, inspectable outcome that another person or automation can continue from without reconstructing hidden state.

Extension Surface

The command is automatable: packages/cli/src/commands/stage-artifacts.ts exposes one governed writer over packages/cli/src/stage-artifacts-client.roundtrip.test.ts-pinned contracts. New stage semantics require core governance changes. The rating reflects the most-open supported seam that is true for this capability, not a transitive implementation detail. The cited path is the operational proof: consumers can use the documented seam, while unsupported changes still require a core release.

Capabilities & Limits

  • Capability: Typed IAGREED artifact creation or update.
  • Capability: Coordinated produces and stage-artifact provenance edges.
  • Capability: System-trust execution with structured result handles.
  • Limit: The command records a completed stage result; it does not run the stage, judge its quality, or permit arbitrary edge verbs.

The limit is intentional product truth rather than missing documentation. Calls also remain subject to authentication, tenant selection, schema validation, and the permissions enforced by the authoritative service.

Implementation Map

  • packages/cli/src/commands/stage-artifacts.ts
  • packages/cli/src/stage-artifacts-client.roundtrip.test.ts
  • packages/cli/src/program.ts

Properties

Property
Value
product
dots-platform
extensibility
automatable
module
CLI, Artifacts
packages
cli
status
shipped
surface
cli
summary
Write a completed IAGREED stage artifact and its provenance edges atomically through one system-trust CLI command.

Connections

CLI IAGREED Stage Artifact Writing · Explore connections

  • implemented bytopackages/cli/src/commands/stage-artifacts.ts
  • implemented bytopackages/cli/src/program.ts
  • implemented bytopackages/cli/src/stage-artifacts-client.roundtrip.test.ts
  • complementstoCLI Task, Project, and Agent Workflows
  • requirestoCLI Knowledge Graph Edge Management
  • complementsfromCLI Task, Project, and Agent Workflows

Connected Records6

Complements
Implemented by
packages/cli/src/commands/stage-artifacts.ts
packages/cli/src/program.ts
packages/cli/src/stage-artifacts-client.roundtrip.test.ts
Requires
6 connections.