spawn-cli 0.1.15__tar.gz → 0.1.16__tar.gz

{spawn_cli-0.1.15/src/spawn_cli.egg-info → spawn_cli-0.1.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawn-cli
-Version: 0.1.15
+Version: 0.1.16
 Summary: A minimal installable Python CLI package.
 License: MIT
 Classifier: License :: OSI Approved :: MIT License
@@ -217,9 +217,11 @@ That rescans **`spawn/rules/`**, attaches missing rule files under a **`rules`**
 
 ### 2. Hints in `spawn/navigation.yaml`
 
-For **short, always-visible reminders** (tone, language, repo-specific habits), add an optional **`hint`** field on rows under **`read-required` → `rules`**—alongside **`path`** and **`description`**.
+For **short, always-visible reminders** (tone, language, repo-specific habits), add **hint-only** rows under **`read-required` → `rules`** (a **`hint`** entry **without** a **`path`**). Mandatory rule files use rows with **`path`** and **`description`** only—do **not** add **`hint`** on the same row as **`path`**; if refresh finds legacy pairs, it splits them into a file row and a following hint-only row.
 
-Spawn merges those strings into the **Hints** section of **rendered skills** and into the **Hints** rollup in managed IDE entry points (for example **`AGENTS.md`**), using the same ordering and deduping rules as extension **`hints.global`**.
+Hints from **`read-required` → `rules`** (hint-only rows) appear in skills’ **Hints** section and in the managed **`AGENTS.md`** rollup together with extension **`hints.global`**, using YAML row order within maintainer hints before dedupe (**`hint`** on **`read-contextual` → `rules`** is still **not** included there).
+
+If a **`path`** names a **`spawn/rules/…`** file that **does not** exist when navigation is refreshed, that row is **removed entirely** — fix or drop **`path`** first; **`hint`** on that same removed row is **not** downgraded to a hint-only row.
 
 Example:
 
@@ -228,7 +230,8 @@ read-required:
   - rules:
       - path: spawn/rules/team.md
         description: Team conventions.
-        hint: Prefer British spelling in user-facing copy.
+      - hint: Prefer British spelling in user-facing copy.
+      - hint: Short standalone reminder with no rule file.
 ```
 
 Then run **`spawn refresh`** so skills and entry points pick up the hint.

{spawn_cli-0.1.15 → spawn_cli-0.1.16}/README.md

@@ -200,9 +200,11 @@ That rescans **`spawn/rules/`**, attaches missing rule files under a **`rules`**
 
 ### 2. Hints in `spawn/navigation.yaml`
 
-For **short, always-visible reminders** (tone, language, repo-specific habits), add an optional **`hint`** field on rows under **`read-required` → `rules`**—alongside **`path`** and **`description`**.
+For **short, always-visible reminders** (tone, language, repo-specific habits), add **hint-only** rows under **`read-required` → `rules`** (a **`hint`** entry **without** a **`path`**). Mandatory rule files use rows with **`path`** and **`description`** only—do **not** add **`hint`** on the same row as **`path`**; if refresh finds legacy pairs, it splits them into a file row and a following hint-only row.
 
-Spawn merges those strings into the **Hints** section of **rendered skills** and into the **Hints** rollup in managed IDE entry points (for example **`AGENTS.md`**), using the same ordering and deduping rules as extension **`hints.global`**.
+Hints from **`read-required` → `rules`** (hint-only rows) appear in skills’ **Hints** section and in the managed **`AGENTS.md`** rollup together with extension **`hints.global`**, using YAML row order within maintainer hints before dedupe (**`hint`** on **`read-contextual` → `rules`** is still **not** included there).
+
+If a **`path`** names a **`spawn/rules/…`** file that **does not** exist when navigation is refreshed, that row is **removed entirely** — fix or drop **`path`** first; **`hint`** on that same removed row is **not** downgraded to a hint-only row.
 
 Example:
 
@@ -211,7 +213,8 @@ read-required:
   - rules:
       - path: spawn/rules/team.md
         description: Team conventions.
-        hint: Prefer British spelling in user-facing copy.
+      - hint: Prefer British spelling in user-facing copy.
+      - hint: Short standalone reminder with no rule file.
 ```
 
 Then run **`spawn refresh`** so skills and entry points pick up the hint.

{spawn_cli-0.1.15 → spawn_cli-0.1.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spawn-cli"
-version = "0.1.15"
+version = "0.1.16"
 description = "A minimal installable Python CLI package."
 readme = "README.md"
 requires-python = ">=3.10"

{spawn_cli-0.1.15 → spawn_cli-0.1.16}/src/spawn_cli/core/low_level.py

@@ -194,9 +194,12 @@ def _merge_hint_streams_ordered(streams: list[list[str]]) -> list[str]:
 
 
 def _navigation_read_required_rule_hints_ordered(target_root: Path) -> list[str]:
-    """Plain-text hints from maintainer-authored read-required ``rules`` rows only (YAML order).
+    """Plain-text hints from maintainer-authored ``read-required`` ``rules`` rows (YAML order).
 
+    Only **hint-only** rows (no non-empty stripped ``path``) contribute; ``hint`` on file-backed
+    rows is ignored here (and dropped on navigation refresh).
     Hint fields on ``read-contextual`` rules are ignored here.
+    Strips each hint; whitespace-only hints are omitted.
     """
     path = _spawn(target_root) / "navigation.yaml"
     raw = load_yaml(path)
@@ -215,9 +218,14 @@ def _navigation_read_required_rule_hints_ordered(target_root: Path) -> list[str]
         for entry in rules_raw:
             if not isinstance(entry, dict):
                 continue
+            path_val = entry.get("path")
+            if isinstance(path_val, str) and path_val.strip():
+                continue
             hint_val = entry.get("hint")
             if isinstance(hint_val, str):
-                out.append(hint_val)
+                stripped = hint_val.strip()
+                if stripped:
+                    out.append(stripped)
     return out
 
 
@@ -1202,7 +1210,64 @@ def save_rules_navigation(target_root: Path) -> None:
     def posix_norm(p: str) -> str:
         return Path(p).as_posix().replace('\\', '/')
 
-    def prune(lst: list[Any]) -> None:
+    def prune_read_required_rules(lst: list[Any]) -> None:
+        """Keep file-backed rows with existing paths (no ``hint`` on those rows); keep hint-only rows."""
+
+        out: list[Any] = []
+        for entry in lst:
+            if not isinstance(entry, dict):
+                continue
+            hint_raw = entry.get('hint')
+            hint_is_str = isinstance(hint_raw, str)
+            hint_stripped = hint_raw.strip() if hint_is_str else ''
+            path_in_entry = 'path' in entry
+            path_raw = entry.get('path')
+
+            if path_in_entry:
+                if isinstance(path_raw, str) and path_raw.strip():
+                    rk = posix_norm(path_raw.strip())
+                    exists = rk in paths_on_disk and (Path(target_root) / Path(rk)).is_file()
+                    if exists:
+                        row: dict[str, Any] = {
+                            'path': rk,
+                            'description': str(entry.get('description') or 'Local rule file.'),
+                        }
+                        out.append(row)
+                        if hint_stripped:
+                            warnings.warn(
+                                f'Moved maintainer hint from file-backed rule row to standalone '
+                                f'hint row: {rk}',
+                                SpawnWarning,
+                            )
+                            out.append({'hint': hint_stripped})
+                    else:
+                        warnings.warn(
+                            f"Removed missing rule path from navigation: {rk}",
+                            SpawnWarning,
+                        )
+                else:
+                    warnings.warn(
+                        'Removed invalid rule row from navigation (empty path field).',
+                        SpawnWarning,
+                    )
+                continue
+
+            if hint_stripped:
+                row_h: dict[str, Any] = {'hint': hint_stripped}
+                desc_raw = entry.get('description')
+                if isinstance(desc_raw, str) and desc_raw.strip():
+                    row_h['description'] = desc_raw.strip()
+                out.append(row_h)
+                continue
+
+            warnings.warn(
+                'Removed invalid rule row from navigation (no path and no hint).',
+                SpawnWarning,
+            )
+
+        lst[:] = out
+
+    def prune_contextual_rules(lst: list[Any]) -> None:
         out: list[Any] = []
         for entry in lst:
             if not isinstance(entry, dict) or 'path' not in entry:
@@ -1225,9 +1290,9 @@ def save_rules_navigation(target_root: Path) -> None:
                 )
         lst[:] = out
 
-    prune(rq_rules_list)
+    prune_read_required_rules(rq_rules_list)
     if cq_rules_list is not None:
-        prune(cq_rules_list)
+        prune_contextual_rules(cq_rules_list)
 
     raw["read-required"] = rr
     raw["read-contextual"] = rc

{spawn_cli-0.1.15 → spawn_cli-0.1.16}/src/spawn_cli/models/__init__.py

@@ -27,6 +27,7 @@ from spawn_cli.models.metadata import (
 from spawn_cli.models.navigation import (
     NavExtGroup,
     NavFile,
+    NavRuleRow,
     NavRulesGroup,
     NavigationFile,
 )
@@ -55,6 +56,7 @@ __all__ = [
     "RenderedSkillsMeta",
     "NavExtGroup",
     "NavFile",
+    "NavRuleRow",
     "NavRulesGroup",
     "NavigationFile",
     "SkillFileRef",

spawn_cli-0.1.16/src/spawn_cli/models/navigation.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class NavFile(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    path: str
+    description: str
+
+
+class NavExtGroup(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    ext: str
+    files: list[NavFile] = Field(default_factory=list)
+
+
+class NavRuleRow(BaseModel):
+    """Maintainer ``read-required`` ``rules`` row: file-backed (``path``) or hint-only (``hint``), never both."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    path: str | None = None
+    description: str | None = None
+    hint: str | None = None
+
+    @model_validator(mode='after')
+    def path_xor_hint(self) -> NavRuleRow:
+        path_ok = bool(self.path and str(self.path).strip())
+        hint_ok = bool(self.hint and str(self.hint).strip())
+        if not path_ok and not hint_ok:
+            raise ValueError('navigation rule row needs a non-empty path or a non-empty hint')
+        if path_ok and hint_ok:
+            raise ValueError(
+                'navigation rule row cannot combine path and hint; use a standalone hint-only row'
+            )
+        return self
+
+
+class NavRulesGroup(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    rules: list[NavRuleRow] = Field(default_factory=list)
+
+
+class NavigationFile(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    read_required: list[dict] = Field(default_factory=list, alias="read-required")
+    read_contextual: list[dict] = Field(default_factory=list, alias="read-contextual")

{spawn_cli-0.1.15 → spawn_cli-0.1.16/src/spawn_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spawn-cli
-Version: 0.1.15
+Version: 0.1.16
 Summary: A minimal installable Python CLI package.
 License: MIT
 Classifier: License :: OSI Approved :: MIT License
@@ -217,9 +217,11 @@ That rescans **`spawn/rules/`**, attaches missing rule files under a **`rules`**
 
 ### 2. Hints in `spawn/navigation.yaml`
 
-For **short, always-visible reminders** (tone, language, repo-specific habits), add an optional **`hint`** field on rows under **`read-required` → `rules`**—alongside **`path`** and **`description`**.
+For **short, always-visible reminders** (tone, language, repo-specific habits), add **hint-only** rows under **`read-required` → `rules`** (a **`hint`** entry **without** a **`path`**). Mandatory rule files use rows with **`path`** and **`description`** only—do **not** add **`hint`** on the same row as **`path`**; if refresh finds legacy pairs, it splits them into a file row and a following hint-only row.
 
-Spawn merges those strings into the **Hints** section of **rendered skills** and into the **Hints** rollup in managed IDE entry points (for example **`AGENTS.md`**), using the same ordering and deduping rules as extension **`hints.global`**.
+Hints from **`read-required` → `rules`** (hint-only rows) appear in skills’ **Hints** section and in the managed **`AGENTS.md`** rollup together with extension **`hints.global`**, using YAML row order within maintainer hints before dedupe (**`hint`** on **`read-contextual` → `rules`** is still **not** included there).
+
+If a **`path`** names a **`spawn/rules/…`** file that **does not** exist when navigation is refreshed, that row is **removed entirely** — fix or drop **`path`** first; **`hint`** on that same removed row is **not** downgraded to a hint-only row.
 
 Example:
 
@@ -228,7 +230,8 @@ read-required:
   - rules:
       - path: spawn/rules/team.md
         description: Team conventions.
-        hint: Prefer British spelling in user-facing copy.
+      - hint: Prefer British spelling in user-facing copy.
+      - hint: Short standalone reminder with no rule file.
 ```
 
 Then run **`spawn refresh`** so skills and entry points pick up the hint.

spawn_cli-0.1.15/src/spawn_cli/models/navigation.py

@@ -1,30 +0,0 @@
-from __future__ import annotations
-
-from pydantic import BaseModel, ConfigDict, Field
-
-
-class NavFile(BaseModel):
-    model_config = ConfigDict(populate_by_name=True)
-
-    path: str
-    description: str
-
-
-class NavExtGroup(BaseModel):
-    model_config = ConfigDict(populate_by_name=True)
-
-    ext: str
-    files: list[NavFile] = Field(default_factory=list)
-
-
-class NavRulesGroup(BaseModel):
-    model_config = ConfigDict(populate_by_name=True)
-
-    rules: list[NavFile] = Field(default_factory=list)
-
-
-class NavigationFile(BaseModel):
-    model_config = ConfigDict(populate_by_name=True)
-
-    read_required: list[dict] = Field(default_factory=list, alias="read-required")
-    read_contextual: list[dict] = Field(default_factory=list, alias="read-contextual")