feat(capabilities): declare requires_system external-tool dependencies#413
Draft
aleskalfas wants to merge 4 commits into
Draft
feat(capabilities): declare requires_system external-tool dependencies#413aleskalfas wants to merge 4 commits into
aleskalfas wants to merge 4 commits into
Conversation
Capabilities may declare dependencies on external system tools via a `requires_system` manifest field (name + min version + per-OS install hint + probe). The kit warns at install (preserving author-anywhere neutrality, unlike COR-030's refuse-at-install for capability deps); the capability's operation hard-gates at use time (the real guarantee), fail-closed on an indeterminate probe; a preflight reports the declared set. The kit never installs the tool. Stands on COR-030 and COR-017; supersedes nothing. Tracked by #381. Status: proposed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Approved by Aleš Kalfas (approve-and-accept). Flips COR-039 proposed → accepted, unblocking the requires_system schema field + schema_version bump + migration work on #381 (gated behind acceptance). Status: accepted. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…039) Add `requires_system` — an optional list in a capability's package.yaml, beside requires_backbone and requires_capabilities — declaring external system tools (binary / daemon / runtime outside the kit). Each entry carries a name, a minimum version, a per-OS install hint, and a per-OS probe, mirroring COR-030's requires_capabilities shape. Scope is the declaration substrate only (Task #381 criteria 1 + 3): the field is parsed into SystemDependency tuples on CapabilityPackage and ignored by everything that doesn't consume it yet. Enforcement — warn-at-install, gate-at-use, preflight — is a separate concern (#382). The parser is additive and lenient like its sibling: an absent field yields an empty tuple; a nameless entry is skipped; a malformed per-OS map degrades to empty rather than failing the package read. No migration: the field is a pure addition (no rename/removal, schema_version bump, or breaking CLI signature) — `pkit migrations check-diff --include-working-tree` reports no triggers. Surface change (adopters can declare the field), so bump minor per PRJ-002. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Resume-here note capturing the state we paused at: the 25-issue adoption/OBS arc, #381's exact next steps (fix + tick criteria 1 & 3, then Review + PR), the pkit non-interactive routing gotcha, and the dependency spine. Retires when #381 lands. Co-Authored-By: Claude Opus 4.8 (1M context) <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.
Closes #381.
What's in this PR
package.yaml; warn at install, the capability hard-gates at use (fail-closed on an indeterminate probe), plus a preflight check; the kit never installs the tool. Reviewed bycritic+methodology-reviewer+convention-compliance-reviewer.requires_systemmanifest substrate — aSystemDependencydataclass + arequires_systemfield + a lenient per-OS parser incapabilities.py, mirroring the siblingrequires_capabilitiesparser. 5 new parse tests (117/117 capabilities tests pass).requires_backboneceiling broaden.No migration — the field is a pure additive addition (
pkit migrations check-diffreports no trigger).Scope
Task #381 is the declaration substrate only. The enforcement — warn-at-install / hard-gate-at-use / doctor preflight — is the follow-on #382.
Remaining before ready-for-review
package.yaml; criterion 3 is a pure-additive field → no migration) and tick criteria 1 & 3.architectreview (cross-cutting external-dependency concern) +convention-compliance-revieweron the full diff.main; resolve the one pyright symmetry judgment call.Resume-here
Full stopping-point handoff:
.pkit/scratchpad/active/2026-07-01-requires-system-381-handoff.md.🤖 Generated with Claude Code