Concept Docs
PCD Workflow Contracts
A Workflow Contract is a PCD-governed operating contract for a critical process. It declares inputs, states, transitions, gates, fail-closed conditions, external observation boundaries, generated checks, evidence schema, and optional registry publication.
Why this exists
Markdown runbooks are useful for explanation, but they can be skipped, executed out of order, or closed with stale evidence. Workflow Contracts make the operating path explicit enough for a person or agent to run while keeping completion tied to declared evidence.
Use Cases
State Model
draftdry_run_passedpublishingpublicfailedsupersededA release train example can move from draft to dry_run_passed to publishing to public only when the contract has the required manifest, generated artifact hashes, live verification result, and public copy boundary checks. Partial mutation, missing evidence, or contradictory observations move the run to failed or superseded.
Modeled Invariants
State transitions are explicit
A workflow can move only through declared states such as draft, dry_run_passed, publishing, public, failed, or superseded.
Evidence is required before closure
Commands, versions, checksums, verifier decisions, operator boundary, and external observations stay attached to the workflow run.
Invalid closure fails closed
Missing evidence, stale manifests, partial publication, or unsupported public copy keeps the workflow from being marked public.
External systems remain boundaries
GitHub, Cloudflare, GCP, package registries, DNS, credentials, and network paths remain observed external trust boundaries.
Generated Targets
A contract can generate operational surfaces without changing the meaning of the contract itself:
- GitHub Actions fragments
- Node or shell gate scripts
- Dispatch validators
- Live verification scripts
- Evidence schemas
- Rollback checklists
- Dashboard status views
- Agent instruction blocks
Evidence Pack
Each run should preserve enough structured evidence to explain what happened, who or what operated it, and which external observations were used.
- contract id and contract hash
- workflow version
- input manifest hash
- generated artifact hashes
- gate decisions
- external observations
- failure states
- operator or account boundary
- timestamp and final decision
Agent Boundary
Agents may inspect the contract, compute the next legal action, run declared gates, collect evidence, propose a transition, and generate a report. They must not:
- skip declared gates
- mark public without live verification evidence
- mutate an undeclared release channel
- reuse stale evidence as current closure
- weaken public copy to hide a failed state
- treat external provider success as a contract proof
Claim Boundary
Workflow Contracts make critical workflows auditable, hash-bound, and fail-closed against the invariants modeled in the contract. They do not prove that external providers cannot fail, and they do not create a formal certification claim by themselves.
GitHub, Cloudflare, GCP, npm, PyPI, crates.io, DNS, credentials, network paths, marketplace propagation, and similar services remain external systems. A contract can observe them, record them, and block invalid closure when the observations do not satisfy the contract.