Pin linked skills in a .secondshift.lock file

Open
#329 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
12/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
git, python
Domain
cli, devtools

Research direction

This is design work across sync, a new secondshift lock command, and the dashboard. Start with how skill_source.ref is read from .secondshift.yaml and with folder_digest in commit 4299e4e6 on the skill-source-digest branch, which can be reused. Done means the four listed tests pass: branch pinning, missing-entry error, digest mismatch error, and lock add/remove/update behaviour. Resolve the open questions on approval and private-repository auth first.

Written by the indexing model from the issue text.

Description

A job that links a skill from another repository must pin skill_source.ref to a full commit SHA. That keeps unreviewed code from running, but it is hard to use:

  • People think in tags and branches, not SHAs.
  • Moving to a newer version means finding and pasting a new SHA by hand.
  • A reviewer of that change cannot tell whether anything in the skill changed, or only something elsewhere in its repository.

#328 tried a hand-written digest next to ref. It was closed because nobody can fill that field in without tooling. A generated lock file solves both problems.

Proposal

People write a tag, a branch or a SHA in .secondshift.yaml. secondshift lock resolves each one and writes .secondshift.lock next to it. Both files are committed. Sync runs only what the lock file names.

# .secondshift.yaml
jobs:
  triage:
    name: Triage new bugs
    skill: skills/triage/SKILL.md
    skill_source:
      repository: acme/agent-skills
      ref: main
# .secondshift.lock
# Written by `secondshift lock`. Do not edit it by hand.
version: 1
skills:
  - repository: acme/agent-skills
    path: skills/triage/SKILL.md
    ref: main
    commit: 4f2c1d0e8b7a6c5d4e3f2a1b0c9d8e7f6a5b4c3d
    digest: sha256:9b1c7e0f3a2d5c4b6e8f0a1d3c5b7e9f2a4c6e8b0d1f3a5c7e9b2d4f6a8c0e1d
A branch is pinned, not followed

A job may name a branch. The lock file pins the commit the branch pointed to when someone ran secondshift lock. The job keeps running that commit after the branch moves. It moves only when someone updates the lock file and commits it. Nothing follows a branch on its own.

Sync
  • Sync never resolves a tag or a branch. It looks up each linked skill in the committed lock file by repository, path and ref. It fetches that commit and checks the digest.
  • A tag or branch with no lock entry is a sync error: "acme/agent-skills@main is not in .secondshift.lock. Run secondshift lock and commit it."
  • A digest that does not match the files at the commit is a sync error. It names both digests.
  • A full SHA in ref needs no lock entry, so existing configurations keep working. With an entry, the commit must equal ref, and the digest is checked.
  • Sync ignores entries that no job uses. secondshift lock removes them.
secondshift lock
  • secondshift lock adds entries for refs that have none and removes unused ones. It never moves an existing entry. Running it again is safe and changes nothing that is already pinned.
  • secondshift lock --update resolves every ref again. secondshift lock --update triage does it for one job.
  • The output says, for each moved entry, whether the skill's files changed: "triage: 4f2c1d0e -> 8a91c3f2, files unchanged" or "files changed".
  • Public repositories are read without credentials. Private ones need a way to authenticate from the command line. See open questions.
Digest

The digest is a SHA-256 of the sha256sum line (<hex> <relative path>) of every regular file in the skill's folder, sorted by path. File modes do not count, and links are refused. Anyone can check it with the shell one-liner from #328. folder_digest in commit 4299e4e6 on the skill-source-digest branch implements it, with tests. It can be reused as-is.

The digest stays the same when a newer commit leaves the skill's folder alone. So the lock file diff shows whether the skill itself changed.

Dashboard and docs
  • Schedule this skill shows the .secondshift.yaml entry with the ref the task used, and tells people to run secondshift lock. A task that named a SHA needs no lock file.
  • The skill picker shows the digest next to the commit.
  • The docs explain the two files, the branch rule and the update flow.

Out of scope

  • SecondShift opening pull requests that update the lock file. The format allows it later, but nothing updates on its own for now.
  • Locking anything other than linked skills.

Open questions

  • Approval. A job's config hash would include its lock entry. Should moving the commit while the digest stays the same keep the job's approval? Requirements come from .secondshift.yaml either way.
  • Private repositories from the command line. Should secondshift lock call the server, which can read through the workspace's GitHub connection, or use the local Git credentials or gh auth token?
  • A lock file without any linked skills. Do we write an empty file or no file? (Proposed: no file.)

Tests

  • A branch ref syncs from its lock entry and keeps running that commit after the branch moves.
  • A tag or branch with no lock entry is a sync error, and nothing runs.
  • A digest mismatch is a sync error that names both digests.
  • A full SHA without a lock file syncs as today, and job config hashes do not change.
  • secondshift lock adds missing entries, removes unused ones and never moves existing ones. --update moves them and reports whether the files changed.
Dominant language
Python
Stars
1
Forks
1
Avg merge
1h 9m
Merged PRs (30d)
322

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from piotrekno1/second-shift

All issues in piotrekno1/second-shift

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.