Artifact Path Changes Are Contract Migrations
Jun 17, 2026
Some cleanup work looks small from the outside. A workflow has an artifact in the wrong format or folder. The fix appears to be: move it, rename it, and update the reference.
In a governed workflow, that is rarely enough.
If an artifact is written by automation, read by another step, validated by tests, cited by documentation, and used as evidence in a review gate, its path is part of the contract.
Moving it is not a file move. It is a contract migration.
Problem
Governed artifacts tend to accumulate meaning around their location.
A folder can imply ownership. A filename can imply lifecycle role. A format can imply whether the artifact is for machines, humans, or both. A hash or provenance record can point downstream systems to the thing they are supposed to trust.
When one artifact breaks the pattern, the visible inconsistency may look cosmetic. Maybe most item-run artifacts live as root Markdown files, while one recommendation still sits as a JSON role output under a separate artifacts folder.
That mismatch creates real operational costs:
- documentation starts to disagree with runtime behavior
- manual and automated modes describe different sources of truth
- writer maps keep treating a governed artifact like a generic role output
- parsers and validators encode old assumptions
- tests preserve the retired behavior
- provenance points to the old contract
The issue is not JSON versus Markdown. The issue is whether the artifact's durable shape matches the governance role it plays.
Story / example
Imagine a triage recommendation in a workflow.
It is not just any role output. It tells the workflow which route to take, records the reasoning for a human gate, and becomes part of the item's governance history.
If the rest of the governed item artifacts are Markdown files at the item-folder root, but this recommendation remains a generic JSON artifact, the system has two competing ideas of what the artifact is.
The migration has to answer more than "Where should the file live?"
It has to answer:
- Which writer owns this artifact?
- Which reader parses it?
- Which validator enforces its required sections and allowed values?
- Which provenance path and hash should be recorded?
- Which prompts, protocol docs, skills, and tests name the canonical location?
- Which old references must disappear so the retired contract does not survive?
Only then can the artifact move without weakening the workflow.
Lesson
Human-readable Markdown can still be a strict machine contract.
That matters because a governed artifact often has two audiences. Humans need to read it during review. Automation needs to parse it without guessing.
The safer pattern is to define the Markdown artifact precisely:
- exact headings
- required fields
- allowed route values
- required gate names
- duplicate handling
- fail-closed parser behavior
- provenance path and hash semantics
- tests for positive behavior and retired behavior absence
This lets the artifact become more readable without becoming loose prose.
Broader implication
Artifact migrations need both positive and negative proof.
Positive proof shows the new contract works: the new writer writes the right file, the new parser reads it, the validator enforces it, and downstream routing still behaves correctly.
Negative proof shows the old contract is gone: no production writer still emits the retired path, no live refusal string points to it, no fixture preserves it as current behavior, and no generic helper still claims ownership.
Without the negative proof, a migration can appear complete while the system still has two contracts.
Closing
A governed artifact is not just content on disk. It is an agreement between the system parts that create, read, trust, explain, and verify it.
When that artifact moves, migrate the contract around it.
Artifact path changes are contract migrations.
Related concepts
- Artifact Lifecycle
- Output Contracts
- Governed Workflows
- Prompt Guardrails Need Artifact Contracts
- Human Verdict Labels Need Durable Tokens
