feat(evolve-lite): unify sharing into scoped repos list (#217) (#218)

* feat(evolve-lite): unify sharing into scoped repos list (#217)

Collapse public_repo and subscriptions into a single repos: list where
each entry has scope: read (subscribe only) or scope: write (publish
target, also synced) — closes #217.

Update publish / subscribe / sync / unsubscribe / recall skills for both
Claude and Codex plugins to operate on the unified model. Write-scope
repos double as publish targets and sync sources, so co-writers see
each other's publishes through normal sync.

Add helpers in lib/config.py (normalize_repos, read_repos, write_repos,
set_repos, get_repo, is_valid_repo_name) and broaden tests across
tests/platform_integrations/.

Sync becomes scope-aware: read = fetch + reset --hard (clobber local),
write = fetch + rebase (preserve local unpushed publishes). Symlink
filtering moves from sync to retrieve, since sync no longer mirrors and
just maintains the clone. Publish requires the write-scope clone to
already exist (subscribe/sync own that step) and writes into the
clone's working tree; the SKILL.md drives the commit/push flow,
including conflict-recovery via rebase + push-with-retry. Unsubscribe
warns when removing a write-scope repo (in SKILL.md).

Co-authored-by: Punleuk Oum <5661986+illeatmyhat@users.noreply.github.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: illeatmyhat

platform-integrations/bob/evolve-lite/README.md

@@ -8,7 +8,7 @@ A Bob integration that helps you learn from conversations by automatically extra
 
 - **Manual Learning**: Use `evolve-lite:learn` to extract and save guidelines from conversations
 - **Manual Retrieval**: Use `evolve-lite:recall` to retrieve and apply stored guidelines
-- **Guideline Sharing**: Publish your guidelines and subscribe to others' via Git repositories
+- **Guideline Sharing**: Subscribe to read-scope repos and publish to write-scope repos via Git
 
 ## Installation
 
@@ -27,17 +27,21 @@ This installs:
 
 ### Guideline Storage
 
-Guidelines are stored as individual markdown files in `.evolve/entities/`, organized by source:
+Guidelines are stored as individual markdown files in `.evolve/entities/`,
+organized by source. Both read-scope subscriptions and write-scope publish
+targets live under `entities/subscribed/{name}/`:
 
 ```text
 .evolve/entities/
-  guideline/                    # Private guidelines
+  guideline/                            # Private guidelines
     use-context-managers.md
-  public/                       # Your published guidelines
-    best-practice.md
   subscribed/
-    alice/                      # Guidelines from alice
-      her-guideline.md
+    memory/                             # write-scope clone (publishes land here)
+      guideline/
+        my-published-guideline.md
+    alice/                              # read-scope clone
+      guideline/
+        her-guideline.md
 ```
 
 Each file uses markdown with YAML frontmatter:
@@ -58,79 +62,111 @@ Context managers ensure proper resource cleanup
 
 ## Sharing Guidelines
 
-Evolve Lite supports sharing guidelines between users via public Git repositories. You can publish your own guidelines so others can subscribe to them, and subscribe to guidelines published by others.
+Evolve Lite treats shared guidelines as multi-reader / multi-writer git
+databases. A single unified `repos:` list in `evolve.config.yaml`
+describes every external guideline repo; each entry has a `scope` of
+`read` (subscribe only) or `write` (publish target that is also pulled
+on sync).
 
 ### Setup
 
-Sharing requires an `evolve.config.yaml` at the project root. If it doesn't exist, the subscribe or publish skills will prompt you to create one. Minimal structure:
+Sharing requires `evolve.config.yaml` at the project root. If it doesn't
+exist, the subscribe or publish skills will prompt you to create one.
+Minimal structure:
 
 ```yaml
 identity:
   user: yourname          # used to stamp ownership on published guidelines
-public_repo:
-  remote: git@github.com:yourname/evolve-guidelines.git
-  branch: main
-subscriptions: []
-```
-
-The `.evolve/` directory is kept out of version control — the skills automatically add it to `.gitignore`.
-
-### Publishing Guidelines
 
-Use `evolve-lite:publish` to share one or more of your local guidelines with others:
-
-1. The skill lists files in `.evolve/entities/guideline/`
-2. You pick which ones to publish
-3. Each selected file is moved to `.evolve/public/guideline/`, stamped with your username as the owner, committed, and pushed to your `public_repo.remote`
+repos:
+  - name: memory
+    scope: write
+    remote: git@github.com:yourname/evolve-memory.git
+    branch: main
+    notes: public memory for my open-source projects
+  - name: team
+    scope: read
+    remote: git@github.com:myorg/evolve-guidelines.git
+    branch: main
+
+sync:
+  on_session_start: false
+```
 
-Others can then subscribe using that remote URL.
+The `.evolve/` directory is kept out of version control — the skills
+automatically add it to `.gitignore`.
 
-### Subscribing to Guidelines
+### Subscribing to a Repo
 
-Use `evolve-lite:subscribe` to pull in guidelines from another user's public repo:
+Use `evolve-lite:subscribe` to add either a read-scope subscription or a
+write-scope publish target:
 
 ```text
 evolve-lite:subscribe
 > Remote URL: git@github.com:alice/evolve-guidelines.git
 > Short name: alice
+> Scope: read
 ```
 
-The repo is cloned directly into `.evolve/entities/subscribed/alice/` (this directory serves as both the git clone and the recall mirror).
+The repo is cloned directly into `.evolve/entities/subscribed/{name}/`
+(this directory serves as both the git clone and the recall mirror).
 
-### Syncing Subscriptions
+### Publishing Guidelines
 
-Use `evolve-lite:sync` to pull the latest changes from all subscribed repos:
+Use `evolve-lite:publish` to share local guidelines via a **write-scope** repo:
+
+1. The skill picks (or asks about) the write-scope target repo
+2. Lists files in `.evolve/entities/guideline/`
+3. You pick which ones to publish
+4. Each selected file is moved into the write-scope clone at
+   `.evolve/entities/subscribed/{repo}/guideline/`, stamped with your
+   username, committed, and pushed to the remote
+
+Because the publish target is also a subscribed repo, your next sync
+pulls in anything other writers have pushed to the same remote.
+
+### Syncing Repos
+
+Use `evolve-lite:sync` to pull the latest changes from every configured
+repo:
 
 ```text
 evolve-lite:sync
-> Synced 2 repo(s): alice (+2 added, 0 updated, 0 removed), bob (+0 added, 1 updated, 0 removed)
+> Synced 2 repo(s): memory [write] (+0 added, 1 updated, 0 removed), alice [read] (+2 added, 0 updated, 0 removed)
 ```
 
+Read-scope repos use `git fetch` + `git reset --hard`. Write-scope repos
+use `git fetch` + `git rebase` so any unpushed local publish commits are
+preserved.
+
 ### Unsubscribing
 
-Use `evolve-lite:unsubscribe` to remove a subscription and delete its locally cloned files:
+Use `evolve-lite:unsubscribe` to remove a configured repo and delete
+its locally cloned files:
 
 ```text
 evolve-lite:unsubscribe
-> Which subscription would you like to remove?
-> 1. alice
-> 2. bob
+> Which repo would you like to remove?
+> 1. memory [write]
+> 2. alice [read]
 ```
 
 The skill confirms before deleting `.evolve/entities/subscribed/{name}/`.
+Removing a write-scope repo will also discard any unpushed local
+publish commits, so the skill warns first.
 
 ### Sharing Storage Layout
 
 ```text
 .evolve/
-  public/                     # git repo pushed to your public remote
-    guideline/
-      guideline-name.md       # owner-stamped guideline
   entities/
-    guideline/                # your private guidelines
+    guideline/                      # your private guidelines
       my-guideline.md
     subscribed/
-      alice/                  # git clone (also serves as recall mirror)
+      memory/                       # write-scope clone (publishes land here)
+        guideline/
+          my-published-guideline.md
+      alice/                        # read-scope clone (also serves as recall mirror)
         guideline/
           her-guideline.md
 ```
@@ -147,43 +183,43 @@ Manually invoke to extract guidelines from the current conversation:
 ### `evolve-lite:recall`
 
 Manually invoke to retrieve and display stored guidelines:
-- Loads guidelines from private, public, and subscribed sources
+- Loads guidelines from private and subscribed sources
 - Formats and displays them for your review
 - Annotates subscribed guidelines with their source
 
 ### `evolve-lite:publish`
 
-Publish private guidelines to your public repository:
+Publish private guidelines to a write-scope repo:
 - Lists available private guidelines
-- Moves selected guidelines to `.evolve/public/`
-- Stamps with owner and published_at metadata
-- Commits and pushes to your public remote
+- Moves selected guidelines into the write-scope clone at
+  `.evolve/entities/subscribed/{repo}/guideline/`
+- Stamps with `owner`, `published_at`, and `source` metadata
+- Commits and pushes to the configured remote
 
 ### `evolve-lite:subscribe`
 
-Subscribe to another user's public guidelines:
-- Clones their public repository
-- Mirrors guidelines to `.evolve/entities/subscribed/`
-- Adds subscription to config
+Add a configured repo to the unified `repos:` list:
+- Clones the remote into `.evolve/entities/subscribed/{name}/`
+- Adds an entry with `scope: read` or `scope: write` to config
 
 ### `evolve-lite:sync`
 
-Sync all subscribed repositories:
-- Pulls latest changes from each subscription
-- Updates mirrored guidelines
+Sync every configured repo:
+- Read-scope: fetch + reset --hard (clobbers any local edits)
+- Write-scope: fetch + rebase (preserves unpushed local publishes)
 - Reports changes (added, updated, removed)
 
 ### `evolve-lite:unsubscribe`
 
-Remove a subscription:
-- Lists current subscriptions
-- Deletes selected subscription's local files
-- Removes from config
+Remove a configured repo:
+- Lists current repos with their scope and notes
+- Deletes the local clone at `.evolve/entities/subscribed/{name}/`
+- Removes the entry from config
 
 ## Environment Variables
 
 - `EVOLVE_DIR`: Override the default `.evolve` directory location (guidelines, config, etc. are stored here)
 
 ## Verification
 
-After installation, the skills should be available in Bob's skill list.
+After installation, the skills should be available in Bob's skill list.

platform-integrations/bob/evolve-lite/commands/evolve-lite:publish.md

@@ -1,5 +1,5 @@
 ---
 name: evolve-lite:publish
-description: Publish a private guideline to your public repo
+description: Publish a private guideline to a configured write-scope repo
 ---
-Use the publish skill to share your private guidelines with others. Follow the skill's instructions exactly.
+Use the publish skill to share your private guidelines via a configured write-scope repo. Follow the skill's instructions exactly.

platform-integrations/bob/evolve-lite/commands/evolve-lite:subscribe.md

@@ -1,5 +1,5 @@
 ---
 name: evolve-lite:subscribe
-description: Subscribe to another user's public guidelines repo
+description: Add a shared guidelines repo (read- or write-scope) to the unified repos list
 ---
-Use the subscribe skill to learn from others' guidelines. Follow the skill's instructions exactly.
+Use the subscribe skill to add a shared guidelines repo — either a read-scope subscription or a write-scope publish target. Follow the skill's instructions exactly.

platform-integrations/bob/evolve-lite/commands/evolve-lite:sync.md

@@ -1,5 +1,5 @@
 ---
 name: evolve-lite:sync
-description: Pull the latest guidelines from all subscribed repos
+description: Pull the latest guidelines from every configured repo (read- and write-scope)
 ---
-Use the sync skill to update your subscribed guidelines. Follow the skill's instructions exactly.
+Use the sync skill to update your configured guidelines repos. Follow the skill's instructions exactly.

platform-integrations/bob/evolve-lite/commands/evolve-lite:unsubscribe.md

@@ -1,5 +1,5 @@
 ---
 name: evolve-lite:unsubscribe
-description: Remove a subscription and delete locally synced guidelines
+description: Remove a repo from the unified repos list and delete its local clone
 ---
-Use the unsubscribe skill to remove a subscription. Follow the skill's instructions exactly.
+Use the unsubscribe skill to remove a configured repo and delete its local clone. Follow the skill's instructions exactly.