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).

CodeRabbit review pass:
- _coerce_repo strips and warns on unknown scope values
- publish.py uses tz-aware datetime.now(datetime.timezone.utc)
- claude sync.py: --quiet no longer doubles as a session-start gate;
  failure branches set any_changes = True so summaries surface
- publish SKILL.md hardens git clone with the -- separator
- publish SKILL.md stages only the published files (git add --
  {guideline_paths}), not the whole clone
- codex publish SKILL.md: fix bare git -C {repo} in the conflict-diff
  command to use the full clone path

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: illeatmyhat

platform-integrations/claude/plugins/evolve-lite/README.md

@@ -57,86 +57,108 @@ You can also manually invoke `/evolve-lite:learn` at any time.
 
 ## 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 you read from or publish to; each entry has a
+`scope` of `read` (subscribe only) or `write` (publish target, also synced).
 
 ### 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 an `evolve.config.yaml` at the project root. The subscribe
+and publish skills will help you create one if it is missing. 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: []
+repos:
+  - name: memory
+    scope: write
+    remote: git@github.com:yourname/evolve-memory.git
+    branch: main
+    notes: public memory for my open-source projects
+  - name: org-memory
+    scope: read
+    remote: git@github.com:acme/org-memory.git
+    branch: main
+    notes: private memory shared only within my org
 sync:
   on_session_start: true  # auto-sync on each session start
 ```
 
-The `.evolve/` directory is kept out of version control — the skills automatically add it to `.gitignore`.
+- `scope: read` — pulled on sync. Cannot be published to.
+- `scope: write` — publish target **and** pulled on sync (so you see
+  everything pushed to it, including by other writers).
 
-### 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 into `.evolve/public/guideline/`, stamped with `visibility: public`, `published_at`, and your username as the owner, committed, and pushed to your `public_repo.remote`
+The `.evolve/` directory is kept out of version control — the skills
+automatically add it to `.gitignore`.
 
-Others can then subscribe using that remote URL.
+### Subscribing to a Repo
 
-### Subscribing to Guidelines
-
-Use `/evolve-lite:subscribe` to pull in guidelines from another user's public repo:
+Use `/evolve-lite:subscribe` to add either a read-only 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 to `.evolve/subscribed/alice/` and mirrored into `.evolve/entities/subscribed/alice/` so recall picks them up immediately.
-The repo is cloned directly into `.evolve/entities/subscribed/alice/` so recall can pick it up immediately. Subscription names must use only letters, numbers, `.`, `_`, and `-`.
-
-### Syncing Subscriptions
+The repo is cloned into `.evolve/entities/subscribed/alice/` so recall can
+pick it up immediately. Repo names must use only letters, numbers, `.`,
+`_`, and `-`.
 
-Use `/evolve-lite:sync` to pull the latest changes from all subscribed repos:
+### Publishing Guidelines
 
-```text
-/evolve-lite:sync
-> Synced 2 repo(s): alice (+2 added, 0 updated, 0 removed), bob (+0 added, 1 updated, 0 removed)
-```
+Use `/evolve-lite:publish` to share one or more of your local guidelines
+via a **write-scope** repo:
 
-If `sync.on_session_start: true` is set in config, this runs automatically at the start of each session.
+1. The skill selects (or asks about) the write-scope target repo
+2. It lists files in `.evolve/entities/guideline/`
+3. You pick which ones to publish
+4. Each selected file is moved into `.evolve/entities/subscribed/{repo}/guideline/`,
+   stamped with `visibility: public`, `owner`, `published_at`, and
+   `source`, committed, and pushed to the remote
 
-> **Note:** Sync uses `git fetch` + `git reset --hard` on each cloned subscription repo, so local state always matches the remote exactly. Accidentally deleted or modified files are automatically restored on the next sync.
+Because the publish target is also a subscribed repo, your next sync will
+pull in anything other writers have pushed to the same repo.
 
-### Unsubscribing
+### Syncing Repos
 
-Use `/evolve-lite:unsubscribe` to remove a subscription and delete its locally cloned files:
+Use `/evolve-lite:sync` to pull the latest changes from every configured
+repo (both scopes):
 
 ```text
-/evolve-lite:unsubscribe
-> Which subscription would you like to remove?
-> 1. alice
-> 2. bob
+/evolve-lite:sync
+> Synced 2 repo(s): memory [write] (+2 added, 0 updated, 0 removed), bob [read] (+0 added, 1 updated, 0 removed)
 ```
 
-The skill confirms before deleting `.evolve/entities/subscribed/{name}/`.
+If `sync.on_session_start: true` is set in config, this runs automatically
+at the start of each session.
+
+> **Note:** Read-scope repos use `git fetch` + `git reset --hard`, so the
+> local clone always matches the remote exactly (deleted or modified files
+> are restored). Write-scope repos use `git fetch` + `git rebase` so any
+> unpushed local publish commits are preserved.
+
+### Removing a Repo
+
+Use `/evolve-lite:unsubscribe` to remove any repo and delete its local
+clone. The skill shows scope and notes for each configured repo and warns
+before removing a write-scope repo (unpushed publishes would be lost).
 
 ### Sharing Storage Layout
 
 ```text
 .evolve/
-  public/
-    guideline/
-      guideline-name.md       # owner-stamped published guideline
   entities/
     guideline/
       private-guideline.md
     subscribed/
-      alice/                  # git clone used directly by recall
+      memory/                 # write-scope clone — publishes land here
+        guideline/
+          my-published-guideline.md
+      alice/                  # read-scope clone
         guideline/
           her-guideline.md
 ```
@@ -232,6 +254,22 @@ evolve/
 │   │   ├── SKILL.md
 │   │   └── scripts/
 │   │       └── retrieve_entities.py
+│   ├── subscribe/
+│   │   ├── SKILL.md
+│   │   └── scripts/
+│   │       └── subscribe.py
+│   ├── publish/
+│   │   ├── SKILL.md
+│   │   └── scripts/
+│   │       └── publish.py
+│   ├── sync/
+│   │   ├── SKILL.md
+│   │   └── scripts/
+│   │       └── sync.py
+│   ├── unsubscribe/
+│   │   ├── SKILL.md
+│   │   └── scripts/
+│   │       └── unsubscribe.py
 │   ├── save/
 │   │   └── SKILL.md
 │   └── save-trajectory/

platform-integrations/claude/plugins/evolve-lite/lib/config.py

@@ -6,6 +6,12 @@
 """
 
 import pathlib
+import re
+import sys
+
+
+VALID_SCOPES = ("read", "write")
+_SAFE_NAME = re.compile(r"^[A-Za-z0-9._-]+$")
 
 
 # ---------------------------------------------------------------------------
@@ -316,21 +322,145 @@ def save_config(cfg, project_root="."):
     path.write_text(content + "\n", encoding="utf-8")
 
 
+# ---------------------------------------------------------------------------
+# Unified repo model (issue #217)
+# ---------------------------------------------------------------------------
+
+
+def _coerce_repo(entry):
+    """Normalize a single repo dict. Returns None if required fields are missing."""
+    if not isinstance(entry, dict):
+        return None
+    name = entry.get("name")
+    remote = entry.get("remote")
+    if not isinstance(name, str) or not name.strip():
+        return None
+    if not isinstance(remote, str) or not remote.strip():
+        return None
+    scope = entry.get("scope", "read")
+    if isinstance(scope, str):
+        scope = scope.strip()
+    if scope not in VALID_SCOPES:
+        print(
+            f"evolve-lite: ignoring repo entry {name!r} — unknown scope {entry.get('scope')!r} (expected one of {', '.join(VALID_SCOPES)})",
+            file=sys.stderr,
+        )
+        return None
+    branch = entry.get("branch", "main")
+    if not isinstance(branch, str) or not branch.strip():
+        branch = "main"
+    notes = entry.get("notes", "")
+    if not isinstance(notes, str):
+        notes = ""
+    return {
+        "name": name.strip(),
+        "scope": scope,
+        "remote": remote.strip(),
+        "branch": branch.strip(),
+        "notes": notes,
+    }
+
+
+def normalize_repos(cfg):
+    """Return the unified ``repos`` list from *cfg* with invalid entries dropped.
+
+    Invalid entries (missing ``name`` or ``remote``, duplicate names, unknown
+    scopes) are silently skipped so callers can trust every returned dict.
+    """
+    if not isinstance(cfg, dict):
+        return []
+    raw = cfg.get("repos")
+    if not isinstance(raw, list):
+        return []
+    result = []
+    seen = set()
+    for entry in raw:
+        repo = _coerce_repo(entry)
+        if repo is None or repo["name"] in seen:
+            continue
+        seen.add(repo["name"])
+        result.append(repo)
+    return result
+
+
+def get_repo(cfg, name):
+    """Return the repo with the given name, or None."""
+    for repo in normalize_repos(cfg):
+        if repo.get("name") == name:
+            return repo
+    return None
+
+
+def write_repos(cfg):
+    """Return only the write-scope repos."""
+    return [r for r in normalize_repos(cfg) if r.get("scope") == "write"]
+
+
+def read_repos(cfg):
+    """Return only the read-scope repos."""
+    return [r for r in normalize_repos(cfg) if r.get("scope") == "read"]
+
+
+def set_repos(cfg, repos):
+    """Replace the ``repos`` list in-place with sanitized entries."""
+    if not isinstance(cfg, dict):
+        return cfg
+    sanitized = []
+    seen = set()
+    for entry in repos or []:
+        repo = _coerce_repo(entry)
+        if repo is None or repo["name"] in seen:
+            continue
+        seen.add(repo["name"])
+        sanitized.append(repo)
+    cfg["repos"] = sanitized
+    return cfg
+
+
+def is_valid_repo_name(name):
+    """Return True if *name* is safe to use as a repo / directory name.
+
+    Rejects leading '-' so names can't be confused with git CLI flags when
+    interpolated into clone paths.
+    """
+    if not isinstance(name, str):
+        return False
+    if name in (".", "..") or name.startswith("-"):
+        return False
+    return bool(_SAFE_NAME.match(name))
+
+
 if __name__ == "__main__":
     # Quick self-test
     import tempfile
 
     with tempfile.TemporaryDirectory() as d:
         cfg = {
             "identity": {"user": "alice"},
-            "public_repo": {"remote": "git@github.com:alice/evolve.git", "branch": "main"},
-            "subscriptions": [{"name": "bob", "remote": "git@github.com:bob/evolve.git", "branch": "main"}],
+            "repos": [
+                {
+                    "name": "memory",
+                    "scope": "write",
+                    "remote": "git@github.com:alice/evolve.git",
+                    "branch": "main",
+                    "notes": "public memory for foobar project",
+                },
+                {
+                    "name": "bob",
+                    "scope": "read",
+                    "remote": "git@github.com:bob/evolve.git",
+                    "branch": "main",
+                    "notes": "",
+                },
+            ],
             "sync": {"on_session_start": True},
         }
         save_config(cfg, d)
         loaded = load_config(d)
         assert loaded["identity"]["user"] == "alice", loaded
         assert loaded["sync"]["on_session_start"] is True, loaded
-        assert isinstance(loaded["subscriptions"], list), loaded
-        assert loaded["subscriptions"][0]["name"] == "bob", loaded
+        repos = normalize_repos(loaded)
+        assert len(repos) == 2, repos
+        assert repos[0]["scope"] == "write", repos
+        assert repos[1]["name"] == "bob", repos
     print("config.py ok")

platform-integrations/claude/plugins/evolve-lite/lib/entity_io.py

@@ -78,12 +78,12 @@ def find_entities_dir():
 def find_recall_entity_dirs():
     """Locate all directories that should be searched during recall.
 
-    Returns the existing recall roots in priority order:
-    ``entities/`` first, then ``public/`` under the configured Evolve dir.
-    Missing directories are skipped.
+    Returns the existing recall roots. Only ``entities/`` is canonical —
+    private entities live in ``entities/guideline/`` and shared entities
+    live in ``entities/subscribed/{repo}/guideline/``.
     """
     evolve_dir = get_evolve_dir()
-    candidates = [evolve_dir / "entities", evolve_dir / "public"]
+    candidates = [evolve_dir / "entities"]
     return [path for path in candidates if path.is_dir()]