d770365753
* docs(#2999): document the capability / reviewer-lane / EoS takeover process The capability ecosystem documented a complete forward lifecycle — develop, publish, version, import, update, remove, turn off — but nothing covering a change of maintainer for an entry that already exists. Adds docs/how-to/take-over-a-capability-or-eos.md defining four takeover modes (consensual handoff, adoption fork, first-party absorption, retirement), the PR shape each takes, a per-surface snapshot of the inherited user-visible contract, and an install-continuity checklist. Also corrects .github/PULL_REQUEST_TEMPLATE/registry-entry.md, which directed contributors to a 'Registry' Discussions category that does not exist — the category is named 'EoS Registry' per docs/registries/README.md, and because 'discussion' is a required field the thread must exist before the PR is opened, so the wrong name stalled contributors at the first required step. Closes #2999 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(#2999): backfill changeset pr number to 3000 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: sim <sim@local> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
4.2 KiB
type, pr
| type | pr |
|---|---|
| Added | 3000 |
New how-to: Take over a capability, reviewer lane, or EoS integration. The capability ecosystem documented a complete forward lifecycle — develop, publish, version, import, update, remove, turn off — but nothing covering a change of maintainer for an entry that already exists. There is no gsd capability transfer command and no rename tooling, and docs/registries/README.md specifies submission and the narrow removal policy but never transfer, so a would-be adopter had no documented path and a reviewing maintainer had no stated bar.
The guide defines four takeover modes and the PR shape each one takes. T1 — consensual handoff keeps the id and the entry, changes only repo / author / install / uninstall, and requires a permalink to the outgoing author's public handoff comment in the entry's Discussion. That permalink is mandatory rather than advisory because entry-update authorship is not verified anywhere: scripts/registry-schema.cjs and npm run validate:registry check an entry's shape, not who is changing it, and the registry-entry PR template's "repo links to a repository I own" is a self-attestation — so a PR repointing repo and author at an unrelated account passes every automated gate, and the reviewing maintainer is the only control. T2 — adoption fork takes a new id, opens a new Discussion, and leaves the original entry untouched, because the narrow removal policy removes an entry only for illegal content, malware, spam, or a dead link and never for staleness or abandonment: an abandoned-but-working entry can never be reclaimed, so adoption is always additive and the original id stays taken. T3 — first-party absorption routes through approved-feature plus an ADR, lands under capabilities/<id>/capability.json per ADR-894, annotates rather than deletes the registry entry, and requires a migration note telling existing users to gsd capability remove <old-id> first — config keys are exclusive to one capability and skill/agent stems must be unique, so a first-party capability that collides with an installed overlay wins silently, leaving the user running code they did not think they were running. T4 — retirement is restricted to the four narrow grounds with evidence in the PR body.
Around the modes the guide adds an evidence pack, license and reserved-prefix and consent gates, a per-surface snapshot of the inherited user-visible contract (loopExtensionPoints / hookKinds / configKeys / requires / runtimeCompat for Feature Capabilities; slug / flags / reviewsSection uniqueness across the merged first-party and overlay set for reviewer lanes; protocolVersion, interfacePoints, profile and the eight ADR-1239 axes for EoS integrations), and an install-continuity checklist covering the failure modes that break existing consumers — id continuity, since consent is stored per (realpath(projectRoot), capability id) and an id change re-prompts every installed project and orphans the update path; re-stating integrity and provenance after a rebuild under new ownership; holding the executable-surface set steady so the handoff is not itself a consent event; and not narrowing engines.gsd without a matching compatVersions row. Post-takeover obligations note that a Release must be cut under the new repo, since there is no re-registration and both the shields badge and the releases/latest permalink render live from repo. The two enforcement gaps — unverified entry-update authorship, and the absence of any id migration path — are stated explicitly in the guide so the process is not mistaken for something CI verifies.
Fixed alongside: .github/PULL_REQUEST_TEMPLATE/registry-entry.md directed contributors to file their Discussion in a Registry category that does not exist. docs/registries/README.md names the category EoS Registry and explicitly notes the name is misleading because it carries threads for all three catalogs. Because discussion is a required field, the thread must exist before the entry's PR is opened — so a contributor following the template stalled at the first required step of the submission process. (#2999)