diff --git a/docs/implementation-status.md b/docs/implementation-status.md index fc3567d..e3feb12 100644 --- a/docs/implementation-status.md +++ b/docs/implementation-status.md @@ -22,6 +22,12 @@ - Implemented a first CLI surface for the planned commands. - Added a Tauri + React desktop shell with scan and path bridge commands. - Implemented Rust/Tauri user-skills Git sync for the shared `~/.skillbox/user-skills` repository, including Settings-managed remote configuration, per-skill dirty status, desktop commit review with diff preview, generated Conventional Commit messages, and selected-file commits. +- Implemented explicit inbound user-skills Git synchronization on `main` through + Check remote -> Review incoming changes -> Apply fast-forward, with separate + worktree/relation state, stale-preview rejection, untrusted-tree validation, + deployed deletion/rename blockers, backup refs, and independent Git/SQLite + recovery auditing. This implementation is newer than the shipped `v0.6.1` + release and remains unreleased. - Implemented Rust/Tauri/CLI remote skill update status checks, Dashboard status refresh, last-checked timestamps, and configurable 5-minute auto refresh. - Implemented GitHub-only remote source search/binding, immutable remote version listing, all-file diff preview, update/rollback apply, and permanent operation logging in Rust core, Rust CLI, Tauri commands, and desktop review dialogs. - Implemented network-backed GitHub install preview/apply in Rust core, Rust CLI, and desktop UI, including first-install diff review, preview identity checks, version snapshots, `current` symlink updates, source metadata, optional CLI deploy, and legacy CLI aliases. @@ -49,8 +55,8 @@ next milestones follow [the versioned evolution path](roadmap.md#versioned-evolu ### 0.7 — Safe Sync, Deployment, And Recovery -- Reviewed inbound user-skills Git is implemented on the active Draft change - set pending qualification. It separates clean/dirty worktree state from +- Reviewed inbound user-skills Git is implemented on `main` but remains + unreleased after `v0.6.1`. It separates clean/dirty worktree state from unknown/synced/ahead/behind/diverged/remote-only/no-remote-branch relation, then uses Check remote -> Review incoming changes -> Apply fast-forward. - The inbound implementation validates the complete remote skill tree, binds a @@ -69,6 +75,18 @@ next milestones follow [the versioned evolution path](roadmap.md#versioned-evolu ### Later Milestones +- Plan [Git-backed Skill Collections](https://github.com/santosli/SkillBox/issues/46) + for `v0.8.0`, after the v0.7.0 inbound-sync release. A collection is a + canonical Git repository/worktree source plus reviewed ref/HEAD; child + `SKILL.md` directories remain independently selectable and deployable. The + planned phases are local repository grouping, persistence and child + relationships, one-fetch GitHub multi-skill preview/apply, and + commit-consistent collection update/rollback. +- Collection scans must remain read-only. Apply must revalidate repository + identity, HEAD/ref, and tree snapshot; execute no hooks, submodules, filters, + scripts, or arbitrary shell; and preserve existing path, overwrite, + duplicate-name, backup, and recovery protections. No collection phase is + currently implemented. - Add FTS-backed search across skills, operations, and usage history. - Add remote source provenance and trust classification without treating popularity as verification. diff --git a/docs/roadmap.md b/docs/roadmap.md index 26868c2..91a7e7e 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -19,19 +19,24 @@ The runtime-profile and evidence-aware usage work passed release qualification through the signed and notarized `v0.6.1` distribution. The current release identity and distribution invariants remain documented in `docs/release.md`. -The active 0.7 implementation adds reviewed inbound synchronization for the -shared user-skills Git repository. It is under Draft PR qualification and is -not part of the shipped `v0.6.1` release. Copy-snapshot deployment and the -broader recovery work remain planned. +Reviewed inbound synchronization for the shared user-skills Git repository is +implemented on `main`, but it is not part of the shipped `v0.6.1` release. +Copy-snapshot deployment and broader recovery work remain planned for the 0.7 +line. Git-backed Skill Collections are the next milestone, targeted for +`v0.8.0`. ## Near-Term Priorities These are the next areas where focused contributions are most useful: -- **Reviewed inbound sync (implementation in progress).** Report worktree state +- **Reviewed inbound sync (implemented, unreleased).** Report worktree state separately from synced/ahead/behind/diverged/remote-only relation, then allow repository-wide, preview-confirmed `origin/main` fast-forwards without automatically merging conflicts. +- **Git-backed Skill Collections (planned for v0.8.0).** Treat one canonical Git + repository/worktree and reviewed SHA as a collection source while keeping + child `SKILL.md` directories independently selectable and deployable. Track + delivery in [GitHub issue #46](https://github.com/santosli/SkillBox/issues/46). - **Deployment portability.** Add copy-snapshot deployment as an explicit alternative to the current compatibility-checked symlink path. - **Recovery workflows.** Strengthen restore previews, backup inspection, and @@ -60,8 +65,8 @@ verified; completing a feature list alone does not qualify a release. | **0.4 — Reliability foundation** | Versioned database migrations, persisted user metadata, Doctor diagnostics, and durable mutation auditing. | Upgrade and backup tests pass; Doctor is available through core, CLI, Tauri, and desktop; audited workflows record both success and failure; release automation passes. | | **0.5 — Local usage discovery and release awareness** | Evidence-aware local skill rankings with time-range, skill-type, agent, and workspace filters; separate Calls and history references; auditable multi-provider history sync; daily signed app-update awareness without automatic downloads. | CLI and desktop reconcile confirmed/inferred/reference evidence consistently; Calls never include low-signal references or claim provider-native totals; history providers resolve real local skills, deduplicate and upgrade stable identities, and preserve successful imports when another provider fails; schema upgrades and representative ranking queries are tested; update checks are rate-limited and every install is revalidated after an explicit click. | | **0.6 — Runtime profiles and portability** | Rust-owned runtime profiles model roots, precedence, frontmatter capabilities, and compatibility without hard-coding agent behavior in React. | Each supported profile has fixtures and compatibility tests; unsupported fields are reported before deployment; runtime-specific behavior remains behind an adapter boundary. | -| **0.7 — Safe sync, deployment, and recovery** | Reviewed inbound user-skills Git updates, copy-snapshot deployment, and stronger restore/audit workflows complement the existing symlink path. Inbound fast-forward is implemented pending qualification; the rest remains planned. | Worktree and branch-relation states are explicit; conflicts are never auto-merged; incoming trees, stale previews, deployed deletion/rename blockers, backup refs, index reconciliation, overwrite protection, and recovery paths have automated coverage. | -| **0.8 — Product hardening** | Large-library performance, actionable diagnostics, accessibility, onboarding, and recovery behavior are ready for sustained daily use. | Performance budgets and critical UI workflows are verified; no known data-loss path remains; supported upgrade and recovery procedures are documented and exercised. | +| **0.7 — Safe sync, deployment, and recovery** | Reviewed inbound user-skills Git updates, copy-snapshot deployment, and stronger restore/audit workflows complement the existing symlink path. Inbound fast-forward is implemented but unreleased; the rest remains planned. | Worktree and branch-relation states are explicit; conflicts are never auto-merged; incoming trees, stale previews, deployed deletion/rename blockers, backup refs, index reconciliation, overwrite protection, and recovery paths have automated coverage. | +| **0.8 — Skill Collections and product hardening** | Git-backed Skill Collections add repository-level discovery, reviewed multi-skill sources, and commit-consistent update/rollback while large-library performance, diagnostics, accessibility, onboarding, and recovery mature for sustained daily use. | Collections use one canonical repository/worktree identity and reviewed SHA, perform one bounded fetch/check per remote repository, require explicit child selection, preserve per-skill deploy/Calls independence, and pass rollback/recovery and untrusted-tree tests with CLI/Tauri parity. Performance budgets and critical UI workflows are verified; supported upgrade and recovery procedures are documented and exercised. | | **0.9 — Release candidate** | Feature scope is frozen while security, migration compatibility, packaging, updater, Homebrew, and real-world beta feedback are closed out. | Threat-model review is complete; upgrades from every supported prior release are tested; blocker defects are closed; signed and notarized distribution rehearsals pass. | | **1.0 — Stable local skill management** | SkillBox offers a documented, supportable contract for discovering, importing, managing, deploying, updating, synchronizing, diagnosing, and recovering supported skills. | Core workflows meet their definitions of done; supported runtimes and limitations are explicit; migrations and recovery are proven; release artifacts and docs match; no open blocker or known data-loss issue remains. | @@ -126,6 +131,55 @@ targets, and unsupported deployment modes block deployment. SkillBox does not rewrite frontmatter, translate formats, select a target automatically, or write to a runtime before a fresh preview is explicitly confirmed. +### 0.8 Git-backed Skill Collections + +[Git-backed Skill Collections](https://github.com/santosli/SkillBox/issues/46) +are planned for `v0.8.0`; they are not implemented. A collection is a +repository/source entity identified by its canonical Git repository or +worktree plus ref/HEAD. A GitHub remote is optional. Child `SKILL.md` +directories remain independent skills for selection, deployment, Calls, and +history, while the collection follows one reviewed commit SHA so children do +not silently drift across unrelated revisions. + +Local Import Review will resolve candidate real paths and their nearest safe +Git root, group normal repositories and Git worktrees by canonical repository +identity, treat nested repositories as separate collections, and map runtime +symlinks back to the same collection. Similar copies outside Git metadata stay +standalone or unlinked because content similarity alone cannot establish +collection membership. The collection card will show repository path, +optional remote, branch/HEAD, skill count, and a searchable expandable child +list with individual and select-all controls; it will never deploy children +automatically. + +A remote repository URL will use one bounded fetch/check to preview all valid +children. Preview will report added, changed, removed, and invalid children, +plus path/name conflicts. Apply will install only explicitly selected child +snapshots while retaining collection provenance. Update and rollback remain +reviewed and commit-consistent at collection level; runtime deployment remains +an independent per-skill action. + +Delivery is phased within the `v0.8.0` target: + +1. Repository detection and local Import Review grouping. +2. Collection/source persistence and child relationships. +3. GitHub multi-skill install preview/apply with one repository fetch. +4. Collection-level update/rollback and UI detail. + +All scans are read-only. Apply must recheck canonical Git root, HEAD/ref, and +tree snapshot and reject stale previews. Collection operations must never run +hooks, submodules, filters, repository scripts, or arbitrary shell strings. +Existing traversal, symlink escape, size/count, non-symlink overwrite, +backup/revert, and duplicate-name protections remain mandatory. Duplicate +child names and managed-skill conflicts require explicit resolution; invalid +children are blocked rather than silently imported. + +The `v0.8.0` acceptance gates include a many-skill local repository appearing +as one collection with N children, runtime symlinks avoiding duplicates, +standalone copies remaining standalone, one fetch/check per remote repository, +one-SHA consistency, explicit child selection, independent per-skill deploy and +Calls behavior, rollback/recovery and untrusted-tree coverage, and CLI/Tauri +parity for core collection operations. + Minor-version scope may change with evidence from real usage. When the scope, ordering, status, or promotion gate of a milestone changes, the same change set must update this roadmap and `docs/implementation-status.md`.