05Model · Upstream refresh

Refresh source, never targets.

Pinned upstream providers are a source refresh lane for the catalog. Upstream-to-catalog refresh and catalog-to-target installation are separate decisions, and the upstream lane never writes a live agent home.

The lane

upstream check -> isolated temp fetch/diff -> catalog import -> Git review -> pack/apply

upstream check and upstream fetch --dry-run are read-only. upstream import --apply writes only the selected catalog skill directory and the upstream lock, leaves ordinary repository diffs, and does not auto-commit. Normal target sync (pack, apply, receipts) picks up from there.

# validate pinned declarations and lineage, read-only
skill-suitcase upstream check --source "$SRC" --json

# fetch one named skill into an isolated temp workspace/home and diff it
skill-suitcase upstream fetch --source "$SRC" --skill <skill-name> --dry-run --json

After approval for the catalog-only source import:

skill-suitcase upstream import --source "$SRC" --skill <skill-name> --apply --json

The upstream lock

.skill-suitcase/upstream-lock.json uses schema calvinnwq.skills.upstream-lock.v0 to declare pinned skills-sh or Git sources and their last imported provenance:

providerthe declared upstream provider, skills-sh or Git

package/versionthe exact pinned upstream package and version

repo/skillthe upstream repository and skill the declaration references

imported hashthe content hash recorded at the last import

imported sourcethe source provenance recorded at the last import

validate --strict validates the upstream lock when the catalog has one, and upstream import refuses malformed lock metadata before fetching.

Lifecycle policy

Keep upstream-to-catalog drift separate from catalog-to-target drift:

upstream unchangedupstream check reports declaration and lineage metadata only, with no target action implied

upstream changedreview the fetch dry-run, import only the selected skill after approval, commit the catalog diff, then use normal target sync

local catalog edittreat it as catalog-hash drift from the last imported upstream hash; commit, revert, or fork/adopt deliberately

upstream removed or renamedkeep the reviewed catalog source and lock until an operator chooses keep, fork/adopt, rename, or delete

target driftuse status and receipt-aware target workflows; do not call npx skills against live homes

Trust boundary

Boundary

The trust boundary is the declared provider fetched in isolation. Git declarations pin a version tag or full commit SHA. skills.sh declarations pin the installer package version, but the referenced upstream repository content is not pinned to a source revision or content hash, so review every fetched diff. Do not trust upstream tooling to select live roots, write receipts, or prove rollback.

New-machine setup remains a catalog checkout followed by ordinary Suitcase planning and apply. The decision record behind this design is skills-sh-delegation.md.

Lineage reporting

For an upstream-managed skill, upstream check reports the upstream package/version, upstream repo/skill, imported hash, and current catalog hash. status carries the same lineage and adds target status, receipt hash, and receipt commit when the target skill is upstream-managed. Target-scoped status loads lineage only for reported skills.