Skip to content

Org skills: three-way reconcile with skills-manifest.json #293

Description

@sachiniSam

Summary

Replace the org-skills reconcile's two-way compare with a three-way baseline so platform updates flow to clean copies while org edits become tracked overrides — never clobbered.

Spec: docs/superpowers/specs/2026-07-21-skills-experience-design.md §3.

Scope (Workstream A — org-level syncing)

  • Content-hash rule + cross-language fixture test — define the canonical hash (whole skill dir bytes, LF-normalized); Go + TS implementations pinned by shared fixtures. (Lands here; Workstream B reuses it.)
  • skills-manifest.json — platform-managed sidecar at org repo root: { name: { kind, source?, baseHash } }. Read/write helpers; manifest + skill files always written in the same atomic commit.
  • Seeding (ensureSkillsRepo) writes each embedded skill's baseHash entry in the seed commit.
  • Three-way reconcileEmbedded: org clean + platform moved → refresh + update entry; org moved → skip (override); both moved → conflict, surface for review. Replaces the kind-based isUserKind skip.
  • Convergence auto-resolve: both sides moved but to IDENTICAL content (org manually adopted the new platform version) → not a conflict; stamp the baseline clean. Conflict resolution UX itself (diff view, accept/keep/merge actions) is Console: three-way skill update states + review-diff flow #298 — this issue only produces the states; sync never auto-resolves a genuine conflict (the decision is content-dependent and belongs to the org).
  • Purge rule: retired platform skill removed only if copy is clean; overridden copy stays, manifest entry drops (becomes org skill).
  • Migration/backfill: first reconcile under new logic backfills the manifest — copy matches a shipped version → stamp its hash; unrecognized content under a platform name → treat as override (never clobber during migration).
  • Import flow writes the manifest entry (kind: imported, source, baseHash) atomically with the imported files.
  • /updates reports three-way states (update-available / overridden / conflict) instead of raw drift.

Out of scope

Project skill copies (Workstream B), console UI for the new /updates states (separate issue), aep skills sync CLI.

Acceptance

  • An org-edited platform skill survives reconcile and is reported as an override.
  • A clean copy picks up a platform update with its manifest entry advanced.
  • Go and TS hash implementations agree on all shared fixtures.

Part of #292.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions