feat(personal-kits): immutable lineage, structured overlays and conflict-safe foundation rebase

Start by reading packages/contracts, the schema and migration conventions, and the linked SkillX issues #31, #34, and #35 plus AgentKit #2275. The issue proposes beginning with manifest and lineage validation and a deterministic resolver and three-way merge backed by golden fixtures, then adding persistence and APIs in phases. Done means the acceptance criteria pass, including conflict blocking, reproducible locked sync, privacy and license enforcement, and backward compatibility.

Parent / dependencies

Child of SkillX #35; tracked by #31. Depends on immutable full-tree releases from #34 / #54, and cross-repo AgentKit #2275. AK local store/composer is owned in AgentKit #2274; avoid a duplicated Go installer.

Objective

Support cloud-hosted personal kits that inherit immutable foundation packages (especially AgentKit) while allowing user-specific overlays, reproducible locked sync, controlled upstream rebase, semantic collision reporting and privacy/license-aware derivative publishing.

Data/semantics to specify

• Stable @publisher/kit-name personal kit identity; exact extends reference to upstream @agentkit/... release and base digest, not mutable latest; immutable kit revisions with optimistic concurrency (generation/ETag).
• Explicit modes extend (non-invasive extension points), override (intentional replacement with ownership), and fork (standalone derivative with lineage, no surprise auto-rebase). Preserve ancestry graph and reject cycles/multi-parent ambiguous resolution.
• Structured overlays for known configurable metadata/recipes/references; deterministic include/exclude/exposure order. Free-form SKILL.md text uses three-way merge only when appropriate. NEVER blindly append Markdown from different origins or treat semantically conflicting instructions as clean.
• Three-way algorithm: B0 = old upstream, U0 = user's delta, B1 = new upstream, output candidate U1 on B1. Classify: clean disjoint, text overlap, deleted/renamed entrypoint, missing deps, permission/capability escalation, licensing change, modified user-local path, ambiguous precedence. Any security/semantic conflict fails closed; keep old effective revision usable until accepted.
• Concrete conflict presentation with hunks, provenance, base/new digest, a human-reviewed resolution record and re-eval marker. No LLM auto-accept. Deterministic algorithm first, optional agent-generated suggestion second.
• Canonical package/alias conflict: multiple packages can have same display name; runtime exposure must resolve to exactly one provider or reject before activation; no last-writer-wins.
• Versioned lockfile with exact package, release, digest, overlay revision, profile, runtime constraints, resolver/schema version. Machine B locked sync identical or explicit incompatibility. No absolute machine paths/secrets in cloud state.
• Private visibility by default; publisher, license and entitlement provenance inherited. Private or paid foundation derivatives may not be public exports merely because overlay is public; define permitted user-authored patch disclosure and source redistribution.
• Design API endpoints for preview update, propose rebase, resolve conflict, publish revision, sync --locked, read-only diff. Preserve existing skillx use behavior; generic SkillX installer planned in #35 may serve non-AK users and must not write AgentKit-owned paths.

Implementation and tests

1. First implement manifest/lineage validators, migration and in-memory deterministic resolver/3-way merge with golden fixtures.
2. Then persist immutable revisions/optimistic concurrency and conflict records; finally expose preview/apply APIs and CLI test helpers. Coordinate Go/TS schema fixture interop with AK #2275.
3. Golden cases: disjoint patch, same hunk, rename/delete, dependency removed, new script permissions, two foundations share alias, cyclic kit, missing entitlement, yanked base, offline locked version, parallel edits, rollback after rebase fails; migration from existing registry records.
4. Replay of lock produces same digests across machines; no session/user secrets in payload, no unauthorized public derivatives.

Agent implementation prompt

Read repo instructions, SkillX #31/#34/#35, packages/contracts, schema/migration conventions and AgentKit #2275. Prefer contracts and deterministic functions over AI-driven merging. Write migration and backward compatibility policy before modifying persistent storage. Implement test-first, phase-scoped PRs: (a) schema/golden fixtures (b) lineage/merge resolver (c) persistence/update preview/sync. Human approval is necessary before activating changes to remote scripts/capabilities or resolving conflicting author intent. Include a traceable conflict report and evidence-driven no-data-loss rollback test. Document privacy, license and entitlements as hard invariants.

Acceptance

• Foundation update preserves unmodified user overlays and exact old revision rollback.
• Conflicting changes block effective revision activation; users can inspect/resolve.
• Exact lockfile deterministically restores on second machine or fails with reason.
• Public derivation respects private/paid source license and entitlement.
• Concurrent kit edits detected, no silent overwrite, old skillx use remains compatible.