Pin linked skills in a .secondshift.lock file
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 12/100
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 lockand 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
refneeds no lock entry, so existing configurations keep working. With an entry, the commit must equalref, and the digest is checked. - Sync ignores entries that no job uses.
secondshift lockremoves them.
secondshift lock
secondshift lockadds 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 --updateresolves every ref again.secondshift lock --update triagedoes 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.yamlentry with the ref the task used, and tells people to runsecondshift 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.yamleither way. - Private repositories from the command line. Should
secondshift lockcall the server, which can read through the workspace's GitHub connection, or use the local Git credentials orgh 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 lockadds missing entries, removes unused ones and never moves existing ones.--updatemoves 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
- Ships a Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from piotrekno1/second-shift
-
code-review secondshift
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
piotrekno1/second-shift#419 ·
Maintainers usually reply within 1 day
-
area: deployment
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
piotrekno1/second-shift#310 ·
Maintainers usually reply within 1 day
-
code-review secondshift
Difficulty 4/5 3-5 days Newbie friendliness 46/100
piotrekno1/second-shift#421 ·
Maintainers usually reply within 1 day
-
code-review secondshift
Difficulty 4/5 3-5 days Newbie friendliness 56/100
piotrekno1/second-shift#420 ·
Maintainers usually reply within 1 day
-
Fix failed-delivery retries on PostgreSQLPossibly taken @piotrekno1 claimed this today. Opencode-review fix-approved secondshift
Difficulty 3/5 1-2 days Newbie friendliness 35/100
piotrekno1/second-shift#418 ·
Maintainers usually reply within 1 day
All issues in piotrekno1/second-shift
Similar issues
-
needs-triage
Difficulty 1/5 Under an hour Newbie friendliness 88/100
flashinfer-ai/flashinfer#9803 ·
Maintainers usually reply within 1 day
-
bug frontend good first issue help wanted
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
oscarbol09/thesisforge#61 ·
-
api bug performance
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
oscarbol09/audiobard#159 ·
-
area:web p2 product:business triage:active type:bug
Difficulty 1/5 Under an hour Newbie friendliness 89/100
cuadrao-ai/argus#2328 ·
Maintainers usually reply within 1 day
-
bug frontend good first issue help wanted
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
nikhilb2/simple_invoicing#907 ·