Stabilize public API, contracts, and compatibility policy for 1.0.0

[blindzero]

Goal

Declare stable, supported contracts for consumers starting with v1.0.0, so consumers can rely on IdLE across minor/patch updates.

Supported = exported + documented.
Only exported cmdlets and documented contracts/formats are supported and stable across minor/patch versions.
Anything not exported and/or not documented (including internal functions, object properties, or implicit behavior) is internal/unsupported and may change at any time.

Scope

Define “Public & Supported” surface (v1.0 baseline)

Freeze and document as stable from v1.0.0:

• Public Cmdlets (exported functions): names, parameters, and documented behavior
• Provider capability IDs for core capabilities (e.g., IdLE.Identity., IdLE.Entitlement.)
• Provider contracts for core capabilities: expected semantics, idempotency rules, and error/result expectations
• Step contracts for built-in steps: required capabilities + expected behavior/result status
• Canonical export formats (public interchange): exported plan/workflow JSON is stable (format + meaning)

Compatibility & breaking changes policy

• Adopt Semantic Versioning rules for the public API:
  • MAJOR for backward-incompatible changes
  • MINOR for backward-compatible features (also allowed for deprecations)
  • PATCH for backward-compatible fixes Semantic Versioning
• Define a deprecation policy (lightweight):
  • Mark as deprecated in a MINOR release, remove in the next MAJOR release (with notes).

Migration guidance

For any future breaking change, provide:

• a “Breaking Changes” section in release notes/changelog
• migration notes/patterns (before/after examples where helpful)

Enforcement (tests/docs)

Ensure existing/added tests verify:

• public cmdlet surface stability (exports)
• canonical export format stability (JSON)
• provider contract expectations for core capabilities

Acceptance Criteria

• Consumers can rely on documented public contracts across minor/patch versions.
• Documentation clearly defines what is public/stable vs internal/unsupported.
• SemVer-based breaking change rules are documented and used for releases. Semantic Versioning
• Canonical plan/workflow export format is documented as part of the public v1.0 baseline and covered by stability tests.