Skip to content

feat(web): add suite-level version drift detection and bulk upgrade guard for GitHub-synced skill suites #1110

Closed

Description

@FenjuFu

User need and evidence

Enterprise users syncing public GitHub skill repositories into SkillHub face a silent version-drift problem when a suite is upgraded member-by-member. When a GitHub repository containing multiple skills is synced, the skills are designed as a suite with lockstep versioning semantics (bound to the same fixed commit). However, because the current review and installation workflows operate on individual skills, a user can inadvertently install or upgrade only a subset of a suite's members, leading to broken workflows.

Evidence (project feedback):

Proposed feature and tradeoffs

Proposal: Add a suite-level version consistency guard that detects and warns about version drift when a user installs, upgrades, or reviews individual members of a suite. This builds on the proposed suite records (#1103) by adding a client- and server-side validation layer that enforces lockstep semantics at the point of action.

Minimum viable scope:

  1. Drift detection on install/upgrade: When a user attempts to install or upgrade a single skill that belongs to a suite, check if the target version's commit hash matches the versions of already-installed suite members. If a mismatch is detected, surface a non-blocking warning: Version drift detected: this skill is part of suite @github/owner--repo (commit abc123), but installed members are on commit def456. Consider upgrading the entire suite.
  2. Bulk upgrade guard: On the suite detail page, if any installed member is on a different commit than the latest synced commit, show a prominent "Upgrade Suite" button with a diff summary (e.g., "3 of 5 members are on an older commit"). Clicking it upgrades all members to the pinned commit in one transaction.
  3. Review queue grouping (read-only): In the review center, group pending review items by their parent suite and commit. This does not change the per-item review logic (each member still gets an independent review record per [Feature] 审核中心支持批量审批与套件整体审批(可选:仅对 GitHub 同步来源的收窄免审) #1096), but it gives the reviewer visual context that these items are lockstep products.

Tradeoffs:

  • Non-blocking by default: The drift warning is non-blocking to preserve the existing individual-install path. Enterprises that want strict enforcement can configure a namespace-level policy to block individual installs of suite members.
  • Dependency on suite records: This feature depends on feat(github-sync): generate suite records for synced repositories to enable grouped browsing and one-command installation #1103 being merged first to establish the suite record data model. This issue only covers the drift detection and UX guard layer.
  • Performance: The drift check requires comparing commit hashes across installed suite members. This is a lightweight O(n) check where n is the number of suite members (typically < 100), acceptable for a synchronous API response.

Harness and evaluation plan

Harness setup:

  • Deploy a local SkillHub instance with the GitHub sync feature enabled.
  • Sync a public repository with multiple skills (e.g., obra/superpowers or mattpocock/skills) to generate a suite record.
  • Simulate the version-drift scenario: install 2 of 5 suite members at commit A, then sync the repository again to advance HEAD to commit B, then attempt to install a 3rd member at commit B.

Evaluation scenarios:

  1. Drift warning on individual install: Install suite member A at commit A, then attempt to install member B at commit B. Verify a warning is surfaced with the correct commit mismatch details.
  2. Bulk upgrade: With 2 of 5 members on commit A and the suite on commit B, click "Upgrade Suite" and verify all 5 members are upgraded to commit B in a single transaction.
  3. Review grouping: Sync a repo producing 10 pending review items. Verify they are visually grouped by suite in the review center.
  4. No false positives: Install all members of a suite at the same commit. Verify no drift warning is shown.

Note: This is an evaluation plan. No harness execution has been performed yet; the feature depends on #1103 being merged first.

Acceptance criteria

  • Installing a single suite member whose commit differs from already-installed members surfaces a clear, non-blocking drift warning with commit hashes.
  • The suite detail page shows a "Upgrade Suite" button when any installed member is on an older commit, and clicking it upgrades all members atomically.
  • The review center visually groups pending items by parent suite and commit hash.
  • No drift warning is shown when all installed suite members are on the same commit.
  • Namespace administrators can optionally enforce a strict mode that blocks individual installs of suite members.

References

Activity

  1. added
    triage/deferred暂留 backlog,由自动化定期重新评分 / Issue stays in backlog and is rescored by automation.
    priority/p2中优先级 / Medium priority triage bucket.
    effort/s小改动或边界明确 / Small or well-bounded change.
    on Nov 20, 2026
  2. github-actions commented on Nov 20, 2026

    @github-actions
    Contributor

    Issue Triage

    • Route: triage/deferred
    • Priority: priority/p2 (2.9/5)
    • Effort: effort/s (2/5)
    • Confidence: 3/5
    • Risk: low
    • Analysis Mode: rules-only

    Why

    • Touches core SkillHub workflows (review, namespace, api).
    • Contains urgency signals (broken).
    • Text suggests a bounded change (text).

    Next Action

    • Keep the issue in the deferred queue and let the 6-hour rescore keep lifting it; it is forced into an active lane by day 10. If it is still open on day 14, treat it as a P0 escalation target under the SLA and prioritize it in the next triage pass.

    问题分流结果

    • 路由: triage/deferred
    • 优先级: priority/p2 (2.9/5)
    • 修复投入: effort/s (2/5)
    • 信息完整度: 3/5
    • 风险: 低
    • 分析模式: rules-only

    原因

    • 涉及 SkillHub 核心流程(review, namespace, api)
    • 包含紧急信号(broken)
    • 文本显示改动范围较可控(text)

    下一步

    • 将 issue 保留在 deferred 队列,并由 6 小时一次的 rescore 持续抬升;最晚在第 10 天强制进入 active lane。若第 14 天仍未闭环,应按 SLA 视为 P0 升级目标,并在下一次 triage 中重点处理
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    effort/s小改动或边界明确 / Small or well-bounded change.priority/p2中优先级 / Medium priority triage bucket.triage/deferred暂留 backlog,由自动化定期重新评分 / Issue stays in backlog and is rescored by automation.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions