Versioning and Comparing Changes

Reusable AI capabilities change over time.

Instructions improve. Supporting files change. New tools are introduced. Provider requirements evolve. A capability that was safe for one audience may become broader in scope.

Commonset uses versioning so those changes remain visible instead of silently replacing previously trusted content.

A Capability Is Not a Version

The capability is the durable organizational identity.

A version is a particular revision of that capability.

For example:

• Contract Review is the capability.
• v1.0 is one version.
• v1.1 is a later version.

Ownership, purpose, and provider relationships can remain attached to the capability while content evolves through versions.

Approved Versions Are Immutable

In the current Commonset model, approved versions cannot have their content hash, metadata, or files changed in place.

If an approved capability needs to change, create a new version.

This is a governance requirement, not just a technical preference.

When a reviewer approves v1.0, the organization should be able to prove later that the content of v1.0 still matches what was reviewed.

What a Version Records

A version can include or reference:

• a version label
• instructions
• structured metadata or frontmatter
• supporting files
• scripts or executable resources
• release notes
• a content hash
• creator and creation time
• provenance
• review state
• security/trust state
• availability state

These fields let Commonset answer both technical and governance questions about the revision.

Choosing Version Labels

Use a versioning convention that your team can apply consistently.

Semantic versioning is a useful option:

• 1.0.0 for an initial stable release
• 1.1.0 for meaningful backwards-compatible behavior additions
• 1.1.1 for smaller corrections

Commonset's key requirement is reliable version identity within the capability. Your organization can define the semantic meaning that best fits its workflow.

Write Useful Release Notes

Release notes are the first human explanation a reviewer sees.

Good release notes describe the behavior change, not just the file operation.

Prefer:

Add a required policy check before generating the final contract-risk summary.

Over:

Updated SKILL.md.

Useful release notes help reviewers decide where to spend attention in the diff.

Compare Against the Previous Version

When a prior version exists, Commonset can present a reviewer-oriented change summary.

The summary can highlight:

• added content
• modified instructions
• removed content
• supporting-file changes
• changes in declared tooling or access
• new or resolved security findings

This is designed to answer What changed for the capability? before the reviewer dives into individual file lines.

Use the Technical Diff When Needed

The technical diff remains the authoritative view of raw file-level changes.

Use it when:

• wording changes are security-sensitive
• scripts changed
• a summary appears incomplete
• you need exact before-and-after evidence
• a reviewer is investigating a finding tied to a particular path

Human-readable summaries should make review faster, not hide the underlying technical evidence.

Security Changes Matter as Much as Text Changes

A small text diff can create a large behavior change.

For example, a version might:

• add permission to use a new tool
• instruct the model to transmit information externally
• add an executable script
• broaden the intended task
• remove a safety constraint

Commonset therefore compares security findings and capability footprint alongside ordinary content differences.

A reviewer should ask not only How many lines changed? but What new behavior became possible?

AI-Assisted Change Explanations

When an appropriate LLM connection is configured, Commonset can provide an advisory explanation of behavioral changes and reviewer attention areas.

That explanation can help non-specialists understand a dense diff, but it is not authoritative.

Always retain access to:

• the deterministic diff
• security findings
• provenance
• human review

Creating a New Version

A safe update workflow is:

1. Start from the latest intended base version.
2. Create a new draft version.
3. Change only the instructions and files needed.
4. Add release notes.
5. Run validation and security analysis.
6. Compare the new version to the previous version.
7. Request review when ready.
8. Publish only after the new version is approved and provider checks pass.

For API or MCP workflows, stale-write protection can help ensure you are not accidentally creating a new version from an outdated base.

Provider Versions Are Mappings, Not Commonset Identity

Providers may use their own version identifiers.

Commonset keeps those identifiers separate from its internal version identity.

A linked provider record can therefore track:

• the latest approved Commonset version
• the last Commonset version pushed
• the last provider version pushed
• the last provider version pulled
• the provider's currently reported version

This is essential for detecting drift.

Understanding Sync States

In sync

The latest approved Commonset version and known provider state match the last successful publication relationship.

Local ahead

Commonset has a newer approved version that has not been pushed to the provider.

Remote changed

The provider reports a different newer state since the last known publication.

Conflict

Both Commonset and the provider changed since the last shared state.

Imported

A provider version has been brought into Commonset without a subsequent publication back to the provider.

Linked

The records are related, but there is not yet enough push/pull history to describe a stronger synchronization state.

These are synchronization states, not approval states.

Handling Remote Changes

If a provider copy changes outside Commonset, do not automatically overwrite the local approved version.

Instead:

1. Refresh provider inventory.
2. Determine whether source can be imported.
3. Import the remote change as a draft when supported.
4. Compare it with the current Commonset version.
5. Review and approve deliberately.

This protects the organizational source of truth while still allowing provider-side changes to re-enter the governed workflow.

Versioning Principle

A useful test is:

Can we reconstruct what users were allowed to use, what reviewers approved, and what providers received at a particular point in time?

Good versioning makes the answer yes.