Operational Lineage

Definition

Operational lineage is the traceable chain of context decisions, captures, and checkpoints that produced a given operational state. It is the verifiable history of how a system reached its current state — what governed the decisions that were made, who approved the governance gates, and what constraints were in effect at each point in time.

Operational lineage is the record of operational provenance. It connects current system state back to the original governed intent that initiated the engineering work.

Why It Matters

Engineering systems accumulate decisions. Some of those decisions are visible in source control — code changes with commit messages. But many operationally significant decisions are not committed to version control: an architectural direction taken in a planning session, a dependency constraint accepted in an AI-assisted conversation, a scope decision made under time pressure.

These decisions are part of the operational lineage of the system. Without a mechanism to capture them as append-only records, they are lost. The system’s state becomes progressively harder to understand and govern as decisions accumulate without provenance.

Operational lineage provides the missing layer. It is the record of operational decisions that code commits cannot capture.

Lineage vs. Version History

Version history (git log) records what changed. Operational lineage records why it changed — and under what governed constraints.

These are complementary but distinct. Version history is a record of implementation. Operational lineage is a record of governance. Both are necessary for a complete engineering audit trail.

Types of Lineage Records

Operational lineage in Yanzi accumulates through three artifact types:

• Intent captures: direct records of prompts, responses, and decisions from AI-assisted sessions
• Checkpoints: human-approved snapshots of operational state at defined governance intervals
• Context Library artifacts: Seeds, Rules, and Roles that constrained the work at each session

Together, these produce a lineage record that is complete, append-only, and verifiable.

Canonical vs. Working Lineage

During active development, operational lineage accumulates as a working lineage — the running record of all decisions, including exploratory ones. When a release is certified, a subset of the working lineage becomes the canonical lineage — the governance-approved, authoritative record for that release.