fix(codex): align sharing recall and publish behavior

Author: visahak

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

@@ -75,6 +75,18 @@ def find_entities_dir():
     return c if c.is_dir() else None
 
 
+def find_recall_entity_dirs():
+    """Locate all directories that should contribute to recall.
+
+    Recall should include both private/subscribed entities stored under
+    ``.evolve/entities`` and published guidelines stored under
+    ``.evolve/public`` when those directories exist.
+    """
+    evolve_dir = get_evolve_dir()
+    candidates = [evolve_dir / "entities", evolve_dir / "public"]
+    return [path for path in candidates if path.is_dir()]
+
+
 def get_default_entities_dir():
     """Return (and create) the default entities directory.
 

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

@@ -99,7 +99,80 @@ If you do not want to enable Codex hooks, you can still invoke the installed `ev
 
 The installed Codex hook does not require `git`. It walks upward from the current working directory until it finds the repo-local `plugins/evolve-lite/.../retrieve_entities.py` script.
 
-If `sync.on_session_start` is enabled in `evolve.config.yaml`, the installer also registers a `SessionStart` hook with matcher `startup|resume` so the sync helper runs quietly whenever a Codex session starts or resumes.
+The installer always registers a `SessionStart` hook with matcher `startup|resume`; it runs on every Codex session start or resume and exits quickly unless `sync.on_session_start` is enabled and subscriptions are configured in `evolve.config.yaml`.
+
+## 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.
+
+### Setup
+
+Sharing uses `evolve.config.yaml` at the project root. Minimal structure:
+
+```yaml
+identity:
+  user: yourname
+
+public_repo:
+  remote: git@github.com:yourname/evolve-guidelines.git
+  branch: main
+
+subscriptions: []
+
+sync:
+  on_session_start: true
+```
+
+The `.evolve/` directory is kept out of version control.
+
+### Publishing Guidelines
+
+Use `evolve-lite:publish` to share one or more of your local guidelines with others:
+
+1. Pick a file from `.evolve/entities/guideline/`
+2. Publish it into `.evolve/public/guideline/`
+3. The published file is stamped with `visibility: public`, `published_at`, and a `source` label derived from config when available
+4. The original private guideline is removed from `.evolve/entities/guideline/`
+
+Others can then subscribe using that public remote URL.
+
+### Subscribing to Guidelines
+
+Use `evolve-lite:subscribe` to pull in guidelines from another user's public repo.
+
+The repo is cloned to `.evolve/subscribed/{name}/` and mirrored into `.evolve/entities/subscribed/{name}/` so recall can pick them up immediately.
+
+### Syncing Subscriptions
+
+Use `evolve-lite:sync` to pull the latest changes from all subscribed repos.
+
+If `sync.on_session_start: true` is set in config, this runs automatically whenever a Codex session starts or resumes.
+
+### Unsubscribing
+
+Use `evolve-lite:unsubscribe` to remove a subscription and delete its locally cloned files.
+
+This removes both `.evolve/subscribed/{name}/` and its mirrored recall copy under `.evolve/entities/subscribed/{name}/`.
+
+### Sharing Storage Layout
+
+```text
+.evolve/
+  public/
+    guideline/
+      guideline-name.md         # published guideline, included in recall
+  subscribed/
+    alice/
+      guideline/
+        her-guideline.md        # git clone of alice's public repo
+  entities/
+    guideline/
+      private-guideline.md      # private local guideline
+    subscribed/
+      alice/
+        guideline/
+          her-guideline.md      # mirrored for recall, annotated [from: alice]
+```
 
 ## Included Skills
 
@@ -109,7 +182,7 @@ Analyze the current session and save proactive Evolve entities as markdown files
 
 ### `evolve-lite:recall`
 
-Show the entities already stored for the current workspace.
+Show the entities already stored for the current workspace, including published guidelines under `.evolve/public/`.
 
 ### `evolve-lite:publish`
 

platform-integrations/codex/plugins/evolve-lite/skills/publish/scripts/publish.py

@@ -4,6 +4,7 @@
 import argparse
 import datetime
 import os
+import re
 import sys
 from pathlib import Path
 
@@ -25,6 +26,24 @@
 sys.path.insert(0, str(_lib))
 from audit import append as audit_append  # noqa: E402
 from entity_io import entity_to_markdown, markdown_to_entity  # noqa: E402
+from config import load_config  # noqa: E402
+
+
+def _resolve_source(cfg, user_arg):
+    """Derive a source label from config or fallback to the provided user."""
+    remote = cfg.get("public_repo", {})
+    if isinstance(remote, dict):
+        remote = remote.get("remote", "")
+    if remote:
+        match = re.search(r"[:/]([^/:]+/[^/]+?)(?:\.git)?$", remote)
+        if match:
+            return match.group(1)
+
+    identity = cfg.get("identity", {})
+    if isinstance(identity, dict) and identity.get("user"):
+        return identity["user"]
+
+    return user_arg
 
 
 def main():
@@ -49,7 +68,11 @@ def main():
     entity["visibility"] = "public"
     if args.user:
         entity["owner"] = args.user
-    entity["published_at"] = datetime.datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")
+    entity["published_at"] = datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    config = load_config(str(evolve_dir.resolve().parent))
+    source = _resolve_source(config, args.user)
+    if source:
+        entity["source"] = source
 
     dest_dir = evolve_dir / "public" / "guideline"
     dest_dir.mkdir(parents=True, exist_ok=True)
@@ -62,7 +85,7 @@ def main():
     src_path.unlink()
 
     audit_append(
-        project_root=str(evolve_dir.parent) if evolve_dir.name != ".evolve" else ".",
+        project_root=str(evolve_dir.resolve()) if evolve_dir.name != ".evolve" else str(evolve_dir.resolve().parent),
         action="publish",
         actor=args.user or "unknown",
         entity=args.entity,

platform-integrations/codex/plugins/evolve-lite/skills/recall/SKILL.md

@@ -27,7 +27,7 @@ Before any non-trivial local work, you must complete the recall workflow below.
 
 Do not proceed to other analysis or tool use until all steps below are complete.
 
-1. Inspect `.evolve/entities/` for guidance relevant to the current task.
+1. Inspect `.evolve/entities/` and `.evolve/public/` for guidance relevant to the current task.
 2. Read each matching entity file that appears relevant.
 3. Summarize the applicable guidance in your own words before proceeding.
 4. If no relevant entities exist, state that explicitly before proceeding.
@@ -36,12 +36,12 @@ Do not proceed to other analysis or tool use until all steps below are complete.
 
 Before moving on, produce an explicit completion note in your reasoning or user update using one of these forms:
 
-- `Recall complete: searched .evolve/entities/, read <files>, applicable guidance: <summary>`
-- `Recall complete: searched .evolve/entities/, no relevant entities found`
+- `Recall complete: searched .evolve/entities/ and .evolve/public/, read <files>, applicable guidance: <summary>`
+- `Recall complete: searched .evolve/entities/ and .evolve/public/, no relevant entities found`
 
 ### Minimum Acceptable Procedure
 
-1. List or search files under `.evolve/entities/`.
+1. List or search files under `.evolve/entities/` and `.evolve/public/`.
 2. Identify candidate entities relevant to the task.
 3. Open and read those entity files.
 4. Summarize what applies, or state that nothing applies.
@@ -51,27 +51,34 @@ Before moving on, produce an explicit completion note in your reasoning or user
 The skill is not complete if any of the following are true:
 
 - You only read this `SKILL.md`
-- You did not inspect `.evolve/entities/`
+- You did not inspect `.evolve/entities/` and `.evolve/public/`
 - You did not read the relevant entity files
 - You proceeded without stating whether guidance was found
 
 ## How It Works
 
 1. If Codex hooks are enabled in `~/.codex/config.toml` with `[features] codex_hooks = true`, the Codex `UserPromptSubmit` hook runs before the prompt is sent.
 2. The helper script reads the prompt JSON from stdin.
-3. It loads stored entities from `.evolve/entities/`.
+3. It loads stored entities from `.evolve/entities/` and `.evolve/public/`.
 4. It prints formatted guidance to stdout.
 5. Codex adds that text as extra developer context for the turn.
 
 ## Entities Storage
 
-Entities are stored as markdown files in `.evolve/entities/`, nested by type:
+Entities are loaded from two locations:
 
 ```text
 .evolve/entities/
   guideline/
-    use-context-managers-for-file-operations.md
-    cache-api-responses-locally.md
+    use-context-managers-for-file-operations.md   <- private
+  subscribed/
+    alice/
+      guideline/
+        alice-tip.md                              <- annotated [from: alice]
+
+.evolve/public/
+  guideline/
+    published-tip.md                              <- your own public, no annotation
 ```
 
 Each file uses markdown with YAML frontmatter:

platform-integrations/codex/plugins/evolve-lite/skills/recall/scripts/retrieve_entities.py

@@ -22,7 +22,7 @@
 if _lib is None:
     raise ImportError(f"Cannot find plugin lib directory above {_script}")
 sys.path.insert(0, str(_lib))
-from entity_io import find_entities_dir, markdown_to_entity, log as _log  # noqa: E402
+from entity_io import find_recall_entity_dirs, markdown_to_entity, log as _log  # noqa: E402
 
 
 def log(message):
@@ -57,25 +57,26 @@ def format_entities(entities):
     return header + "\n".join(items)
 
 
-def load_entities_with_source(entities_dir):
-    """Load markdown entities and annotate mirrored subscribed content."""
+def load_entities_with_source(entities_dirs):
+    """Load markdown entities from recall roots and annotate subscribed content."""
     entities = []
-    entities_dir = Path(entities_dir)
-    for md in sorted(entities_dir.glob("**/*.md")):
-        try:
-            entity = markdown_to_entity(md)
-        except OSError:
-            continue
-        if not entity.get("content"):
-            continue
-
-        parts = md.parts
-        for index, part in enumerate(parts):
-            if part == "subscribed" and index + 1 < len(parts):
-                entity["_source"] = parts[index + 1]
-                break
-
-        entities.append(entity)
+    for entities_dir in entities_dirs:
+        entities_dir = Path(entities_dir)
+        for md in sorted(entities_dir.glob("**/*.md")):
+            try:
+                entity = markdown_to_entity(md)
+            except OSError:
+                continue
+            if not entity.get("content"):
+                continue
+
+            parts = md.relative_to(entities_dir).parts
+            for index, part in enumerate(parts):
+                if part == "subscribed" and index + 1 < len(parts):
+                    entity["_source"] = parts[index + 1]
+                    break
+
+            entities.append(entity)
 
     return entities
 
@@ -100,13 +101,13 @@ def main():
             log(f"  {key}={value}")
     log("=== End Environment Variables ===")
 
-    entities_dir = find_entities_dir()
-    log(f"Entities dir: {entities_dir}")
-    if not entities_dir:
-        log("No entities directory found")
+    entities_dirs = find_recall_entity_dirs()
+    log(f"Recall entity dirs: {entities_dirs}")
+    if not entities_dirs:
+        log("No recall entity directories found")
         return
 
-    entities = load_entities_with_source(entities_dir)
+    entities = load_entities_with_source(entities_dirs)
     if not entities:
         log("No entities found")
         return

platform-integrations/codex/plugins/evolve-lite/skills/subscribe/scripts/subscribe.py

@@ -34,8 +34,8 @@ def main():
     parser.add_argument("--branch", default="main", help="Branch to track")
     args = parser.parse_args()
 
-    project_root = "."
     evolve_dir = Path(os.environ.get("EVOLVE_DIR", ".evolve"))
+    project_root = str(evolve_dir.resolve()) if evolve_dir.name != ".evolve" else str(evolve_dir.resolve().parent)
     subscribed_base = (evolve_dir / "subscribed").resolve()
     dest = (evolve_dir / "subscribed" / args.name).resolve()
     if not dest.is_relative_to(subscribed_base):

platform-integrations/codex/plugins/evolve-lite/skills/sync/scripts/sync.py

@@ -80,8 +80,8 @@ def main():
     parser.add_argument("--config", default=None, help="Explicit config path")
     args = parser.parse_args()
 
-    project_root = "."
     evolve_dir = Path(os.environ.get("EVOLVE_DIR", ".evolve"))
+    project_root = str(evolve_dir.resolve()) if evolve_dir.name != ".evolve" else str(evolve_dir.resolve().parent)
 
     if args.config:
         cfg_path = Path(args.config)
@@ -114,13 +114,24 @@ def main():
             continue
         name = sub.get("name", "unknown")
         branch = sub.get("branch", "main")
-        repo_path = evolve_dir / "subscribed" / name
+        subscribed_base = (evolve_dir / "subscribed").resolve()
+        repo_path = (evolve_dir / "subscribed" / name).resolve()
+
+        if repo_path == subscribed_base or not repo_path.is_relative_to(subscribed_base):
+            summaries.append(f"{name} (invalid subscription name)")
+            continue
 
         if not repo_path.is_dir():
             summaries.append(f"{name} (not cloned)")
             continue
 
-        git_pull(repo_path, branch)
+        pull_result = git_pull(repo_path, branch)
+        if pull_result.returncode != 0:
+            error_lines = (pull_result.stderr or pull_result.stdout or "").strip().splitlines()
+            short_error = error_lines[-1] if error_lines else "unknown error"
+            summaries.append(f"{name} (git pull failed: {short_error})")
+            continue
+
         delta = count_delta(repo_path)
         total_delta[name] = delta
         if any(value > 0 for value in delta.values()):

platform-integrations/codex/plugins/evolve-lite/skills/unsubscribe/scripts/unsubscribe.py

@@ -35,8 +35,8 @@ def main():
     group.add_argument("--name", help="Name of subscription to remove")
     args = parser.parse_args()
 
-    project_root = "."
     evolve_dir = Path(os.environ.get("EVOLVE_DIR", ".evolve"))
+    project_root = str(evolve_dir.resolve()) if evolve_dir.name != ".evolve" else str(evolve_dir.resolve().parent)
 
     cfg = load_config(project_root)
     subscriptions = cfg.get("subscriptions", [])

tests/platform_integrations/test_audit.py

@@ -12,7 +12,7 @@
 )
 import audit
 
-pytestmark = pytest.mark.platform_integrations
+pytestmark = [pytest.mark.platform_integrations, pytest.mark.unit]
 
 
 class TestAuditAppend: