Skill content-only changes are not re-uploaded from git

[vanducng]

Problem

gcplane apply -f shtp --force did not publish a SKILL.md body-only change for shtp/skills/design-shtp.

Observed on 2026-05-29:

• goclaw-config had a committed change to shtp/skills/design-shtp/SKILL.md adding reference-image preflight/post-validation rules.
• gcplane validate -f shtp passed.
• gcplane apply -f shtp --endpoint https://goclaw.dataplanelabs.com --force --auto-approve ran, but the remote skill stayed on v11.
• The plan showed only an overlay/metadata diff for Skill/design-shtp (visibility: internal -> tenant), not a package/content diff.
• Live server verification still showed /app/data/tenants/shtp/skills-store/design-shtp/11 as current and no v12 until the skill ZIP was manually uploaded to /v1/skills/upload.

Root Cause Hypothesis

KindSkill.spec.sourceDir is write-only and excluded from diffing. KindSkill is also not in SupportsWriteOnlyHash, so the reconciler cannot detect local package drift when only the body/assets change and observable fields such as name/description/visibility/status/grants do not change.

Relevant code:

• internal/manifest/field_config.go: KindSkill write-only fields include sourceDir, version; KindSkill is not in kindsSupportingWriteOnlyHash.
• internal/provider/goclaw/skills.go: updateSkill would re-upload if called with sourceDir, but the reconciler never schedules an update when the only drift is the local skill package.
• internal/skillpkg/skillpkg.go: already computes a package ContentHash that includes bundled assets, but it is not used as an observable desired-vs-actual signal for KindSkill.

There is a related server-side caveat: GoClaw upload currently hashes only SKILL.md content for idempotency, not the full uploaded ZIP, so asset-only changes may not create a new version even if uploaded.

Expected Behavior

Any committed change under a managed skill directory should be reconciled from git to GoClaw:

• SKILL.md body-only changes should create a new skill version.
• Asset-only changes should create a new skill version.
• Agent grants should be repinned to the newly uploaded current version when the manifest declares those grants.

Suggested Fix

Prefer a package-hash design:

1. Have gcplane compute skillpkg.PackDir(sourceDir).ContentHash for KindSkill and include it as a desired package hash.
2. Have GoClaw persist and echo a managed skill package/content hash, or at least expose enough hash/version metadata for reconciliation.
3. Add KindSkill to SupportsWriteOnlyHash only after GoClaw persists and echoes the hash.
4. On skill package drift, call the existing upload path (POST /v1/skills/upload with source=gcplane) and then reconcile overlays/grants.
5. Ensure grant reconciliation pins agents to the uploaded current version, not stale pinned versions.

Manual Workaround Used

Uploaded the skill ZIP directly to /v1/skills/upload with source=gcplane, which created design-shtp v12, then explicitly repinned lan-runner and thu-ha grants to v12.

[vanducng]

Follow-up design improvement from the incident: consider supporting track latest skill grants.

Current behavior appears to require every skill_agent_grants row to carry a concrete pinned_version, so after a managed skill upload creates v12, existing grants can remain pinned to v11 unless the reconcile path explicitly repins them. That made the new design-shtp content available on the server but not actually used by lan-runner / thu-ha until I manually updated grants.

Suggested model:

• pinned_version = NULL means the agent always uses the latest active skill version.
• pinned_version = N keeps today’s frozen behavior for production-sensitive skills.
• Manifest/grant config should support something like version: latest or omit version to mean latest.
• UI should expose a clear toggle: Use latest vs Pin to version.
• gcplane apply for managed skills should default managed tenant agents to latest unless explicitly pinned.

This fits managed skills better: git is the source of truth, so most tenant agents should consume the latest reconciled version automatically. Pinning should be an explicit compatibility/safety choice, not the default footgun.