From 9dab0ca3f4550c98902df0a9c931e8d81d07a10e Mon Sep 17 00:00:00 2001
From: AIOSAI <aipass.system@gmail.com>
Date: Fri, 10 Jul 2026 15:21:14 -0700
Subject: [PATCH] =?UTF-8?q?#665=20item=204=20(spawn):=20sync=5Fregistry=5F?=
 =?UTF-8?q?ops=20derives=20branch=20description=20from=20passport=20purpos?=
 =?UTF-8?q?e/role/README,=20not=20the=20hardcoded=20'Auto-registered=20bra?=
 =?UTF-8?q?nch'=20placeholder=20=E2=80=94=20wired=20into=20new-registratio?=
 =?UTF-8?q?n=20AND=20--fix=20backfill=20of=20existing=20placeholders.=20Ro?=
 =?UTF-8?q?ot=20fix=20that=20ships=20+=20survives=20regen=20(the=20gitigno?=
 =?UTF-8?q?red=20registry=20data=20edit=20didn't).=200=20placeholders=20in?=
 =?UTF-8?q?=20drone=20systems.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../spawn/apps/handlers/sync_registry_ops.py  | 52 +++++++++++++++++--
 1 file changed, 49 insertions(+), 3 deletions(-)

diff --git a/src/aipass/spawn/apps/handlers/sync_registry_ops.py b/src/aipass/spawn/apps/handlers/sync_registry_ops.py
index 7c35a9d4..b148fd87 100644
--- a/src/aipass/spawn/apps/handlers/sync_registry_ops.py
+++ b/src/aipass/spawn/apps/handlers/sync_registry_ops.py
@@ -39,6 +39,33 @@ from aipass.spawn.apps.handlers.class_registry import get_template_dir
 from aipass.spawn.apps.handlers.json import json_handler
 
 
+def _derive_description(branch_path: Path) -> str:
+    """Derive a one-line description from the branch's passport or README."""
+    passport_path = branch_path / ".trinity" / "passport.json"
+    if passport_path.exists():
+        try:
+            passport = json.loads(passport_path.read_text(encoding="utf-8"))
+            identity = passport.get("identity", {})
+            for field in ("purpose", "role"):
+                value = identity.get(field, "").strip()
+                if value:
+                    return value
+        except (json.JSONDecodeError, IOError) as e:
+            logger.warning("[sync-registry] Failed to read passport for description (%s): %s", branch_path.name, e)
+
+    readme_path = branch_path / "README.md"
+    if readme_path.exists():
+        try:
+            for line in readme_path.read_text(encoding="utf-8").splitlines():
+                stripped = line.strip()
+                if stripped and not stripped.startswith(("#", "[", "---", "*", ">")):
+                    return stripped
+        except IOError as e:
+            logger.warning("[sync-registry] Failed to read README for description (%s): %s", branch_path.name, e)
+
+    return "Auto-registered branch"
+
+
 def _scan_for_branches(project_root: Path) -> dict[str, Path]:
     """Scan a project directory tree for branches with .trinity/passport.json.
 
@@ -161,6 +188,7 @@ def sync_registry(fix: bool = False) -> dict:
 
     # 4/5. Fix if requested
     fixed = False
+    needs_save = False
     if fix and (stale or unregistered_list):
         # Remove stale entries
         raw_branches = registry.get("branches", [])
@@ -190,7 +218,7 @@ def sync_registry(fix: bool = False) -> dict:
                 "name": name.upper(),
                 "path": rel_path,
                 "profile": "library",
-                "description": "Auto-registered branch",
+                "description": _derive_description(branch_path),
                 "email": f"@{name}",
                 "status": "active",
                 "created": today,
@@ -203,11 +231,28 @@ def sync_registry(fix: bool = False) -> dict:
                 raw_branches.append(entry)
             logger.info(f"[sync-registry] Added unregistered branch: {name}")
 
-        # Update total and save
         registry["metadata"]["total_branches"] = len(branches_as_list(registry["branches"]))
+        needs_save = True
+
+    # Backfill placeholder descriptions on existing entries
+    descriptions_backfilled = []
+    if fix:
+        for entry in branches_as_list(registry.get("branches", [])):
+            if entry.get("description") == "Auto-registered branch":
+                name_lower = entry.get("name", "").lower()
+                branch_path = filesystem_branches.get(name_lower)
+                if branch_path:
+                    derived = _derive_description(branch_path)
+                    if derived != "Auto-registered branch":
+                        entry["description"] = derived
+                        descriptions_backfilled.append(name_lower)
+                        logger.info("[sync-registry] Backfilled description for %s: %s", name_lower, derived)
+        if descriptions_backfilled:
+            needs_save = True
+
+    if fix and needs_save:
         save_result = save_registry(registry_path, registry)
         fixed = save_result
-
         if fixed:
             logger.info("[sync-registry] Registry updated successfully")
         else:
@@ -276,4 +321,5 @@ def sync_registry(fix: bool = False) -> dict:
         "fixed": fixed,
         "spawn_rebuilt": spawn_rebuilt,
         "ids_fixed": ids_fixed,
+        "descriptions_backfilled": descriptions_backfilled,
     }