docs: define capability versions, consumer pins and rollback - #8
Conversation
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Reviewer's GuideThis documentation-only PR establishes a manual, Git-revision-based contract for releasing capabilities, pinning exact consumer installations, reviewing dependencies and evidence, and safely upgrading or rolling back. README links to the contract while clearly scoping out installer, resolver, and lockfile automation. Entity relationship diagram for capability consumer pinserDiagram
CONSUMER_REPOSITORY ||--o{ CAPABILITY_PIN : records
CAPABILITY_PIN }o--|| CAPABILITY_RELEASE : resolves
CAPABILITY_RELEASE }o--o{ CAPABILITY_RELEASE : depends_on
CONSUMER_REPOSITORY {
string repository
string consumer_commit
}
CAPABILITY_PIN {
string capability_id
string declared_version
string git_revision
string installed_file_hashes
string validation_evidence
}
CAPABILITY_RELEASE {
string capability_id
string semver
string managed_file_paths
}
Flow diagram for manual capability release and rollbackflowchart TD
A["Candidate capability release"] --> B["Record SemVer contract and managed files"]
B --> C["Review source, dependencies and validation"]
C --> D["Pin exact Git revision in docs/capabilities.md"]
D --> E["Update declared files in consumer repo"]
E --> F["Run baseline, candidate and recovery cases"]
F --> G["Submit files, inventory and evidence"]
F --> H["Rollback previous file set and inventory"]
H --> I["Run environment recovery and repeat checks"]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
| ## Update and rollback | ||
|
|
||
| 1. Review candidate release notes, source diff and changed dependencies. | ||
| 2. In a lab worktree, compare installed hashes with the inventory. Stop if local |
There was a problem hiding this comment.
Step 2 ("compare installed hashes with the inventory") and the required "Installed files: exact destination paths and file hashes" row (L79) contradict L65-67, which says plugin-loaded capabilities record version + commit "instead of hashes of copied files".
Every capability in this repo ships through the plugin, so under L65-67 no consumer inventory has hashes. Step 2 has nothing to compare, and the "required" table field can't be filled. A reviewer following the doc either blocks the update or skips the local-changes check the step exists for. Either make hashes optional for plugin-delivered capabilities and define the plugin equivalent of step 2 (for example, diff the cache dir against the recorded commit), or require hashes of the cache dir.
Automated review (Claude Code, AI-generated). Validate before acting.
There was a problem hiding this comment.
Fixed in 0894c8d: the table row and step 2 now separate copied capabilities (hashes) from plugin-loaded ones (version + commit). The 0.x bump rule is now a one-level shift. (Claude Opus 5.5, on behalf of Rody)
| The host installs it into a cache directory named after the `version` field of | ||
| `.claude-plugin/plugin.json` (for example | ||
| `~/.claude/plugins/cache/project-kit-local/project-kit/0.1.0/`) and records the | ||
| commit it installed. Changing files without changing that field can leave |
There was a problem hiding this comment.
The host's recorded install commit is taken as the immutable revision. With a directory marketplace (this repo's install method) it's the checkout's HEAD, while the cache is copied from the working tree.
If the main checkout has uncommitted edits at install time (PR #5 notes one, in .beads/issues.jsonl), the cache holds files that match no commit, yet the inventory records gitCommitSha as the "full immutable" revision. Rollback to that SHA doesn't reproduce what was loaded. Require a clean tree before install/bump, or record cache file hashes as well.
Automated review (Claude Code, AI-generated). Validate before acting.
There was a problem hiding this comment.
Addressed in 0894c8d: "install from a clean checkout", with the reason. (Claude Opus 5.5, on behalf of Rody)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 participant
Why
Capabilities need reproducible revisions and a clear boundary between shared instructions and consumer-specific configuration.
Changes
docs/capability-versioning.md: manual release contract (SemVer rules, explicit managed files), exact consumer pins in a revieweddocs/capabilities.mdinventory, compatibility rules, dependency review, evidence and rollback, and a promotion criterion before automating packaging.docs/capability-versioning.mdalso ties capability releases to theversionin.claude-plugin/plugin.json: the host keys its install cache on that field, so a release that ships through the plugin bumps it in the same PR.README.md: short pointer section.No installer or lockfile generator is implemented or claimed. Companion to #7; either merge order works.
Validation
git diff --checkpasses.main(b9818bf) and merges with docs: add an agent workflow laboratory and experiment playbook #7 without conflicts.Limits
The pilot has not run. This documents the versioning contract only.
🤖 Generated with Claude Code
Summary by Sourcery
Establish a manual, reproducible versioning and consumer-pinning contract for capabilities distributed through the plugin.
Enhancements:
Documentation: