docs(spec): semver 1.0 compatibility & stability policy (M4 freeze)#155
Merged
Conversation
Adds docs/spec/compatibility.md, the canonical statement of the semver contract basou commits to at 1.0 (the M4 API/format freeze deliverable): - Guaranteed surfaces: the basou CLI (commands/flags/exit codes + the documented --json output shapes), @basou/sdk, and the .basou/ on-disk format. Additive-only within a 1.x line. - Not guaranteed: @basou/core (published but internal; use the SDK) and the CLI's human-facing prose. - On-disk format major is decoupled from the product version and gated forward-compatibly (accept 0.x.y, gate 1.x.y+ with an upgrade error); migration machinery is deferred, caches are exempt. - Deprecation policy: obsolete flags become deprecated no-ops through 0.x and are removed at 1.0 (--repo-url is the live example). Wired into docs/README.md, the root README "Status & stability" section, and CHANGELOG Unreleased. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
takashi-matsuyama
added a commit
that referenced
this pull request
Jul 1, 2026
Bump packages/{basou,core,cli,sdk} to 0.31.0 and finalize the CHANGELOG
section. Bundles the M4 (API/format freeze) pass:
- Portfolio view live repo links (#152).
- .basou format version gate — forward-compatible format major (#153).
- Remove project.repository_url; --repo-url kept as a deprecated no-op (#154).
- semver 1.0 compatibility & stability policy doc (#155).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
takashi-matsuyama
added a commit
that referenced
this pull request
Jul 1, 2026
Bump packages/{basou,core,cli,sdk} to 0.31.0 and finalize the CHANGELOG
section. Bundles the M4 (API/format freeze) pass:
- Portfolio view live repo links (#152).
- .basou format version gate: forward-compatible format major (#153).
- Remove project.repository_url; --repo-url kept as a deprecated no-op (#154).
- semver 1.0 compatibility and stability policy doc (#155).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
takashi-matsuyama
added a commit
that referenced
this pull request
Jul 1, 2026
Bump packages/{basou,core,cli,sdk} to 0.31.0 and finalize the CHANGELOG
section. Bundles the M4 (API/format freeze) pass:
- Portfolio view live repo links (#152).
- .basou format version gate: forward-compatible format major (#153).
- Remove project.repository_url; --repo-url kept as a deprecated no-op (#154).
- semver 1.0 compatibility and stability policy doc (#155).
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
docs/spec/compatibility.md— the canonical statement of the semver contract basou commits to at1.0. This is the M4 (API/format freeze) done-criterion "publish the semver 1.0 compatibility policy".The policy
Guaranteed surfaces (semver applies; additive-only within a
1.xline):basouCLI — commands/subcommands, flags, exit codes, and the documented--jsonoutput shapes.@basou/sdk— the read-only provenance API..basou/on-disk format — durable schemas (manifest, session, event, approval, task) + published JSON Schemas.Not guaranteed:
@basou/core(published but CLI-internal; depend on the SDK), and the CLI's human-facing prose.On-disk format versioning: the format major is decoupled from the product version (shipping
1.0.0does not bump it) and gated forward-compatibly — accept0.x.y, gate1.x.y+ with an "upgrade basou" error. Migration machinery is deferred (only the gate contract is frozen now); caches are exempt.Deprecation policy: obsolete flags become deprecated no-ops through
0.x(accepted, warn) and are removed at1.0(--repo-urlis the live example).Also wired into
docs/README.md, the root README "Status & stability" section, andCHANGELOGUnreleased.Review
Went through a review-only, design-challenging adversarial review (codex). Disposition:
.basou/-only claim (integrations also write~/.claude/,~/.codex/), the uniform-loose-schema claim (some event variants are.strict()), the JSON-Schemapatternscope (caches useconst), and the dry-run-by-default scope (provenance views write by default).--jsonoutput shapes, since basou's own session-end capture depends on them) and B3 (clarify thatschema_version: 0.xon a1.0+ install is expected); the strict-event-variant tension is resolved by honest wording (variants encode real invariants);@basou/corepublic-surface reduction recorded as post-1.0 backlog; deferred migration and the 1.0 flag-removal timing held as settled.Docs-only change.
lint:langOK; no source touched.🤖 Generated with Claude Code