Skip to content

COMPATIBILITY_POLICY.md

Latest commit

 

History

History
112 lines (75 loc) · 3.21 KB

COMPATIBILITY_POLICY.md

File metadata and controls

112 lines (75 loc) · 3.21 KB
Raw

Compatibility Policy

Purpose

This policy explains how the Agentic Enterprise Readiness Profile should evolve without breaking adopters unnecessarily.

The project is still pre-1.0. Until 1.0.0, maintainers should expect some shape changes. Even before 1.0.0, changes should be documented and conservative because the profile is meant to help other repositories expose evidence.

Versioning

The project uses semantic versioning intent:

  • MAJOR: incompatible profile or schema changes
  • MINOR: new profile capabilities, required evidence categories, templates, or guide changes
  • PATCH: clarifications, examples, typo fixes, and non-breaking validator improvements

Current status:

  • 0.x: early profile evolution
  • 0.3.x: compatibility policy and adoption registry
  • 1.0.0: stable profile candidate only after external feedback and adoption evidence

Compatibility Scope

The compatibility surface includes:

  • PROFILE.md
  • schema/agentic-readiness.schema.json
  • templates/AGENTIC_BOUNDARY_MODEL.md
  • docs/SCORING_GUIDE.md
  • docs/ADOPTER_GUIDE.md
  • scripts/validate-readiness.mjs
  • example *.agentic-readiness.json files

Non-Breaking Changes

Examples:

  • adding optional fields to the JSON schema
  • adding optional evidence categories
  • improving documentation
  • adding examples
  • strengthening anti-claim language
  • improving validator error messages without rejecting previously valid examples

Breaking Changes

Examples:

  • removing a schema field
  • changing a field type
  • making an optional field required
  • changing profile level meaning
  • renaming required files
  • changing validator behavior so existing valid examples fail

Breaking changes before 1.0.0 are allowed only when they materially improve clarity, safety, or interoperability. They must be called out in release notes.

Deprecation Rule

When possible:

  1. Mark the old field, file, or convention as deprecated.
  2. Keep the validator permissive for at least one minor release.
  3. Document the replacement.
  4. Remove or enforce only in a later minor or major release.

Schema Stability

The schema should stay permissive while the profile is seeking external feedback.

Preferred approach:

  • require only the core fields needed for basic review
  • allow additional properties
  • add stronger checks through examples and documentation first
  • make stricter validation opt-in until there is external adoption

Release Requirements

Every release should include:

  • summary of changed artifacts
  • validation result
  • whether the change is breaking
  • whether adopters need to update examples
  • anti-claim reminder if public positioning changed

Spec-affecting changes should also follow:

  • docs/SPEC_CHANGE_PROCESS.md

Adoption Compatibility

External adopters should not be forced to copy the full project. The minimal adoption path remains:

  1. AGENTS.md
  2. docs/AGENTIC_BOUNDARY_MODEL.md
  3. agentic-readiness.json

Any future profile evolution should preserve that minimal path unless there is strong external feedback to change it.

Anti-Claims

Compatibility with this profile does not mean:

  • production readiness
  • certification
  • AAIF project status
  • Linux Foundation project status
  • endorsement
  • external adoption without public proof