The Yanzi v2.9.1 Deterministic Release Cycle

Context

The v2.9.1 release of the Yanzi CLI introduced deterministic release engineering as a first-class operational capability. Prior to v2.9.1, Yanzi releases followed a standard development cycle: code was written, tests were run, and promotion to the release channel was triggered when the CI pipeline passed.

That process was correct. It was not governed in the operational sense: there was no formal record of the operational context that governed the release’s development, no systematic validation that the implementation converged to the governed intent, and no certification trace that could be independently reproduced.

The v2.9.1 cycle was the first to apply Yanzi’s own governance infrastructure to its own release process. This document records what that looked like operationally, what was found, and what it produced.

Release Scope

The v2.9.1 release included the following operational changes:

• Introduction of the yanzi release certify command and certification trace format
• Convergence validation tooling for comparing implementation against operational lineage
• Governed promotion gate requiring human approval with a documented authority record
• Release trace document format for preserving canonical lineage per release
• Distribution packaging updates for Homebrew and APT channels

The scope was intentionally bounded. The release was primarily infrastructure — governance infrastructure — rather than new end-user features. This made it appropriate as the reference implementation of the certification process: the scope was auditable, the lineage was manageable, and the governance requirements were clearly defined.

Lineage Construction

Initial Capture

Development on v2.9.1 began with an explicit governance initialization step. The active project in Yanzi was set to yanzi-cli. A seed document was authored and committed that recorded the operational intent for the release:

v2.9.1 introduces certification tooling. The certification process must itself be certifiable: every governance mechanism introduced in this release must be demonstrably operational by the time the release is promoted. The release cannot be promoted if the certification tooling cannot certify its own lineage.

This seed established the principal governance constraint for the entire release cycle: self-certification. The tooling being shipped had to work on the release that shipped it.

Development Captures

Over the course of the development cycle, intent captures were recorded at each significant decision point. Key captures included:

Certification format decision: The certification trace format was chosen to be human-readable markdown rather than a structured data format. The rationale: certification traces are governance artifacts consumed by engineers, not by systems. Optimizing for human readability over machine parseability was the correct operational tradeoff for this initial implementation.

Convergence validation scope: The convergence validation for v2.9.1 was scoped to three checks: intent alignment (implementation consistent with captured intent artifacts), rule compliance (no active rule constraints violated), and role authority (all actions within the bounded scope of the active role). A fourth check — dependency lineage validation — was deferred to a future release after review of the implementation cost.

Distribution channel strategy: The Homebrew formula update was treated as a separate governance unit from the core CLI release. It has its own lineage path (the homebrew-yanzi repository) and its own promotion gate. The v2.9.1 CLI certification does not certify the Homebrew formula — it certifies that the source artifact is ready for distribution channel packaging.

Checkpoint Record

Twelve governance checkpoints were recorded across the development cycle:

At checkpoint 12, the corpus contained 38 artifacts: the initial seed, 23 intent captures, 12 checkpoint records, and 2 governance gate approvals.

Lineage Validation Findings

First Certification Run: Partial Pass

The first run of yanzi release certify against the v2.9.1 candidate produced a partial pass with two findings:

Finding 1 — Lineage gap at checkpoint 03: The convergence validation scope decision (deferred dependency lineage validation) was documented in a capture, but the capture was not linked to the relevant checkpoint in the lineage chain. The certification tooling correctly identified the gap: a governance decision was recorded, but its relationship to the corresponding checkpoint was not established.

Resolution: A new capture was authored that explicitly linked the deferred-scope decision to checkpoint 03 and documented the rationale for deferral. The lineage chain was updated. This is not a retroactive modification — the original capture remains in the corpus, and the new capture references it. The chain is append-only.

Finding 2 — Role authority boundary not recorded: Two of the implementation commits were made in sessions that did not have an active Yanzi Role applied. The actions taken were within what would have been the bounded scope of an implementation role, but the role was not formally active at the time. The certification tooling flagged this as an unverified authority boundary.

Resolution: A governance exception record was authored documenting: the specific commits, the actions taken, the assertion that the actions were within the scope of the standard implementation role, and the human approval of the exception. This exception record became part of the canonical lineage.

Second Certification Run: Full Pass

With both findings resolved, the second certification run produced a full pass across all three validation checks:

• Intent alignment: All 23 intent captures reviewed; implementation consistent with captured decisions.
• Rule compliance: No active rule constraints were violated. The active rules for the project did not include a dependency lineage validation rule (consistent with the deferred-scope decision).
• Role authority: All actions within bounded scope, including the exception record for the two pre-role sessions.

The corpus hash at certification was recorded as 8e3b1f42a. This hash anchors the certification claim: the certification is valid relative to the corpus state at that hash. Any engineer with access to that corpus state can reproduce the certification result.

Distribution Mismatch Detection

During packaging verification for the Homebrew and APT distribution channels, a mismatch was detected between the release binary checksum in the Homebrew formula draft and the certified release artifact.

The checksum in the formula draft referenced a pre-certification build artifact rather than the certified artifact. This was a packaging process error, not a code change. The formula was updated to reference the certified artifact’s checksum, and the update was recorded as an append-only capture in the release lineage.

This detection is operationally significant. Without the certification trace anchored to a specific artifact checksum, the distribution mismatch would have been undetectable by governance process — it would have required a manual checksum audit that may or may not have been performed.

The certified artifact checksum in the release trace is not a documentation artifact. It is a governance anchor. Distribution packages that reference a different checksum are, by definition, not distributing the certified artifact.

Governance Gate and Governed Promotion

At checkpoint 10, the release was declared a certified candidate: the lineage was validated, convergence was confirmed, and the certification trace was complete.

Promotion was not automatic. A formal governance gate review was conducted:

The reviewer (csailer@yanzi.sh) reviewed:

• The complete certification trace
• Both convergence validation runs and the findings from the first run
• The exception record for the pre-role sessions
• The distribution mismatch detection and remediation

The review produced two observations:

1. The pre-role session exception was accepted. The actions were within scope; the exception was properly documented. The governance process handled the finding correctly.

2. The deferred dependency lineage validation was noted as a technical debt item. A future release should address this. The deferral for v2.9.1 was accepted given the self-certification constraint (implementing dependency lineage validation in the same release that introduces certification would have significantly expanded scope).

Following review, the promotion was approved. The approval record was appended to the corpus as an append-only governance artifact. The release was tagged, and the canonical lineage was finalized.

Provenance Preservation

The complete operational lineage for v2.9.1 is preserved in the Yanzi corpus under project yanzi-cli. The corpus state at certification (8e3b1f42a) is recoverable.

This means the certification is independently reproducible. Any engineer with access to the corpus at that hash state can run yanzi release certify and receive the same result: full pass, same validation outputs, same exception record, same approval artifact.

This is the operational definition of deterministic release convergence: the certification result is reproducible from the preserved corpus state. It is not a snapshot. It is an auditable governance record.

What This Established

The v2.9.1 release cycle established several operational precedents:

Self-certification is achievable: governance infrastructure can certify its own release. The self-certification constraint proved to be a valuable quality check — it surfaced the pre-role session gap that would otherwise have been undocumented.

Partial passes are informative, not failures: the first certification run did not fail the release. It surfaced two specific findings that required governance action. The governance action produced a stronger lineage record than a clean first-pass would have.

Append-only remediation works: both findings were resolved through append-only corpus operations. No existing records were modified. The resolution process is itself part of the auditable lineage.

Distribution governance requires artifact anchoring: the checksum mismatch detection demonstrated that governance of distribution channels requires explicit artifact anchoring in the certification trace, not just process documentation.

Operational Notes

This case study documents the first complete implementation of a certification cycle. The process was designed, executed, and refined during this cycle. Future releases will benefit from the procedural refinements that emerged from this experience.

The deferred dependency lineage validation (Finding 2 from the first certification run scope review) remains an open item. It is tracked in the project corpus as an explicit governance decision with documented rationale — not as undocumented technical debt.

The certification tooling introduced in v2.9.1 is available for use on any Yanzi project. The yanzi release certify command, convergence validation, and canonical lineage format are operational for any project that maintains a Yanzi corpus with sufficient checkpoint coverage.