@softspark/ai-toolkit 3.3.0 → 3.4.1

package/CHANGELOG.md

@@ -7,6 +7,40 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v3.4.1 — URL-tracked sources protected from path-write demotion (2026-05-06)
+
+Patch release. Fixes a regression introduced in v3.4.0 where `ai-toolkit update` could rewrite a URL-tracked hook entry into a local-path entry.
+
+### Fixed
+
+- **`register_path_source` no longer overwrites URL entries** in `scripts/hook_sources.py` and `scripts/rule_sources.py`. The function now returns early when an existing entry has a `url` field. Previously, `scripts/install_steps/markers.py:refresh_url_hooks` re-injected URL hooks from their cached file, and `inject_hook_cli.py` would call `register_path_source` with that cached path — silently demoting the URL record to a local one on every update.
+- **Regression test** in `tests/test_inject_hook.bats` that pre-seeds a URL entry, runs the local-path inject path, and asserts the URL entry survives untouched.
+
+### Recovery
+
+- If your `~/.softspark/ai-toolkit/hooks/external/sources.json` has a `path` instead of a `url` for a hook that was originally URL-installed, run `ai-toolkit remove-hook <name>` followed by `ai-toolkit inject-hook <original-url>` to re-register from the URL.
+
+---
+
+## v3.4.0 — Local-path source tracking & orphan detection (2026-05-06)
+
+Minor release. Closes the visibility gap for rules and hooks installed from local files: `add-rule` and `inject-hook` now record the origin path in `sources.json`, and `status` flags any rule files on disk that have no source recorded.
+
+### Added
+
+- **`register_path_source()` in `scripts/rule_sources.py` and `scripts/hook_sources.py`** — records `{"path": <abs_path>, "fetched_at": ..., "sha256": ...}` for local-file injections. Schema-compatible with existing URL entries (mutually exclusive `url` vs `path` field, `schema_version` unchanged at 1).
+- **`add-rule` registers local paths** — `scripts/add_rule.py` now calls `register_path_source` after copying a local file, and prints the origin path with a hint to re-run `add-rule` to refresh.
+- **`inject-hook` registers local paths** — `scripts/inject_hook_cli.py` writes a `path`-tracked entry into `~/.softspark/ai-toolkit/hooks/external/sources.json` for file-sourced hooks. URL behavior unchanged. Registration failures are non-fatal — injection always proceeds.
+- **`ai-toolkit status` distinguishes URL vs local sources** — local-path entries display the absolute path with a `[local]` tag; URL entries display the URL. Format: `rule  <name>  <- <origin>[ [local]] (<fetched_at>)`.
+- **Orphan rule detection in `status`** — files in `~/.softspark/ai-toolkit/rules/` that have no entry in `sources.json` are listed as `(orphan, no source recorded — re-run add-rule)`. Surfaces rules registered before the registry existed (pre-v3.3.0).
+
+### Migration
+
+- Existing URL-tracked sources continue to work unchanged.
+- To upgrade an orphan local rule into the registry, re-run `ai-toolkit add-rule <path>` from the rule's source directory. The new run records the path.
+
+---
+
 ## v3.3.0 — External-source visibility & skill-listing budget default (2026-05-06)
 
 Minor release. Two coordinated install-time additions: `ai-toolkit status` now surfaces every registered external rule and hook, and fresh installs / updates set a sane `skillListingBudgetFraction` so all 112 skill descriptions stay loadable in Claude Code.

package/README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-112-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1042%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1047%20passing-success)](tests/)
 
 <p align="center">
   <img src="assets/ai-toolkit-readme-hero.png" alt="ai-toolkit 3 README hero showing one toolkit for 12 AI editors" width="900">
@@ -14,13 +14,14 @@
 
 ---
 
-## What's New in v3.3.0
+## What's New in v3.4.1
 
-Minor release. Two install-time additions: visibility for external rules/hooks and a sane default for Claude Code's skill listing budget.
+Patch release. Fixes a v3.4.0 regression where `ai-toolkit update` could demote URL-tracked hook entries to local-path entries on every refresh. `register_path_source` now never overwrites a URL-tracked entry. Also adds a regression test.
 
-- **`ai-toolkit status` lists external sources** — every rule and hook registered via `add-rule` / `inject-hook` is now visible in `status` output with its source URL and last-fetched timestamp. No more grepping `~/.softspark/ai-toolkit/*/sources.json` by hand.
-- **`skillListingBudgetFraction = 0.02` set by default** — install/update writes the key into `~/.claude/settings.json` only when missing, so all 112 skill descriptions stay loadable in Claude Code without truncation. User-set values are preserved.
-- **Updated `status` help text** — `bin/ai-toolkit.js` now mentions external rules/hooks alongside modules, version, and profile.
+- **URL-tracked hooks and rules are protected** — `register_path_source` returns early when the existing entry has a `url` field.
+- **`add-rule` and `inject-hook` still track local paths** — file-sourced rules and hooks record `{"path": ..., "sha256": ...}` in `sources.json`, alongside URL entries.
+- **`status` distinguishes URL vs local sources** — local entries show the absolute origin path with a `[local]` tag.
+- **Orphan rule detection** — rule files on disk with no source recorded are listed with `(orphan, no source recorded — re-run add-rule)`.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -153,7 +154,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1042 tests)
+├── tests/               # Bats test suite (1047 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.3.0",
+  "version": "3.4.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "3.3.0",
+  "version": "3.4.1",
   "description": "AI coding toolkit: 112 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/add_rule.py

@@ -87,7 +87,11 @@ def main() -> None:
         dest = rules_dir / f"{rule_name}.md"
         shutil.copy2(rule_file, dest)
 
+        from rule_sources import register_path_source
+        register_path_source(rules_dir, rule_name, rule_file, content=dest.read_bytes())
+
         print(f"Registered: '{rule_name}' -> {dest}")
+        print(f"Source path: {rule_file.resolve()} (re-run add-rule to refresh)")
 
     print()
     print("Apply now:")

package/scripts/hook_sources.py

@@ -119,6 +119,38 @@ def register_url_source(
     save_sources(hooks_dir, sources)
 
 
+def register_path_source(
+    hooks_dir: Path | None,
+    hook_name: str,
+    path: Path,
+    content: bytes | None = None,
+) -> None:
+    """Add or update a local-file source entry for a hook.
+
+    Stores the absolute origin path so subsequent ``ai-toolkit update`` runs
+    can detect drift, plus a sha256 of the injected content.
+    """
+    import re
+    if not hook_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", hook_name):
+        raise ValueError(f"Invalid hook name: {hook_name!r}")
+    hooks_dir = hooks_dir or EXTERNAL_HOOKS_DIR
+    sources = load_sources(hooks_dir)
+    existing = sources.get(hook_name) or {}
+    # Never demote a URL-tracked entry to a local-path entry. update() flows
+    # call inject() with the cached file path after URL fetch, which would
+    # otherwise overwrite the URL.
+    if "url" in existing:
+        return
+    entry: dict[str, Any] = {
+        "path": str(Path(path).resolve()),
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    if content is not None:
+        entry["sha256"] = hashlib.sha256(content).hexdigest()
+    sources[hook_name] = entry
+    save_sources(hooks_dir, sources)
+
+
 def unregister_source(hooks_dir: Path | None, hook_name: str) -> bool:
     """Remove a source entry. Returns True if found and removed."""
     hooks_dir = hooks_dir or EXTERNAL_HOOKS_DIR

package/scripts/inject_hook_cli.py

@@ -377,6 +377,18 @@ def inject(hooks_file: str, target_dir: str, source_override: str = "") -> None:
     save_json(str(settings_path), settings)
     print(f"Injected hooks from '{source}' into {settings_path}")
 
+    # Register local-file source so `status` and future updates can see it.
+    # URL sources are already registered earlier inside _fetch_and_cache().
+    if not is_url:
+        try:
+            from hook_sources import register_path_source
+            register_path_source(
+                None, source, Path(hooks_file),
+                content=Path(hooks_file).read_bytes(),
+            )
+        except Exception as exc:  # registration failure must not block injection
+            print(f"Warning: could not register local source: {exc}", file=sys.stderr)
+
     # Propagate Codex-compatible events to ~/.codex/hooks.json
     _inject_codex(tagged, source, target_dir)
 

package/scripts/install_steps/install_state.py

@@ -10,8 +10,13 @@ sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 from paths import TOOLKIT_DATA_DIR, STATE_FILE, RULES_DIR, EXTERNAL_HOOKS_DIR
 
 
-def _load_sources(sources_file: Path, key: str) -> list[tuple[str, str, str]]:
-    """Read a sources.json registry and return (name, url, fetched_at) tuples."""
+def _load_sources(sources_file: Path, key: str) -> list[tuple[str, str, str, str]]:
+    """Read a sources.json registry.
+
+    Returns a list of ``(name, origin, fetched_at, kind)`` tuples where
+    ``kind`` is ``"url"`` for remote sources, ``"local"`` for path-tracked
+    sources, and ``"unknown"`` if neither field is present.
+    """
     if not sources_file.is_file():
         return []
     try:
@@ -22,14 +27,30 @@ def _load_sources(sources_file: Path, key: str) -> list[tuple[str, str, str]]:
     entries = data.get(key, {}) if isinstance(data, dict) else {}
     if not isinstance(entries, dict):
         return []
-    out: list[tuple[str, str, str]] = []
+    out: list[tuple[str, str, str, str]] = []
     for name, meta in sorted(entries.items()):
         if not isinstance(meta, dict):
             continue
-        out.append((name, str(meta.get("url", "")), str(meta.get("fetched_at", ""))))
+        if "url" in meta:
+            origin, kind = str(meta["url"]), "url"
+        elif "path" in meta:
+            origin, kind = str(meta["path"]), "local"
+        else:
+            origin, kind = "", "unknown"
+        out.append((name, origin, str(meta.get("fetched_at", "")), kind))
     return out
 
 
+def _orphan_rule_files(rules_dir: Path, registered: set[str]) -> list[str]:
+    """Return rule names present on disk but missing from sources.json."""
+    if not rules_dir.is_dir():
+        return []
+    return sorted(
+        f.stem for f in rules_dir.glob("*.md")
+        if f.stem not in registered
+    )
+
+
 def _state_path() -> Path:
     """Return the canonical path to state.json."""
     return STATE_FILE
@@ -226,15 +247,20 @@ def print_status() -> None:
 
     ext_rules = _load_sources(RULES_DIR / "sources.json", "rules")
     ext_hooks = _load_sources(EXTERNAL_HOOKS_DIR / "sources.json", "hooks")
-    if ext_rules or ext_hooks:
+    rule_orphans = _orphan_rule_files(RULES_DIR, {n for n, _, _, _ in ext_rules})
+    if ext_rules or ext_hooks or rule_orphans:
         print()
         print("  External sources:")
-        for name, url, fetched_at in ext_rules:
+        for name, origin, fetched_at, kind in ext_rules:
+            tag = " [local]" if kind == "local" else ""
             stamp = f" ({fetched_at})" if fetched_at else ""
-            print(f"    rule  {name}  <- {url}{stamp}")
-        for name, url, fetched_at in ext_hooks:
+            print(f"    rule  {name}  <- {origin}{tag}{stamp}")
+        for name in rule_orphans:
+            print(f"    rule  {name}  <- (orphan, no source recorded — re-run add-rule)")
+        for name, origin, fetched_at, kind in ext_hooks:
+            tag = " [local]" if kind == "local" else ""
             stamp = f" ({fetched_at})" if fetched_at else ""
-            print(f"    hook  {name}  <- {url}{stamp}")
+            print(f"    hook  {name}  <- {origin}{tag}{stamp}")
 
     extends = state.get("extends")
     if extends:

package/scripts/rule_sources.py

@@ -120,6 +120,37 @@ def register_url_source(
     save_sources(rules_dir, sources)
 
 
+def register_path_source(
+    rules_dir: Path | None,
+    rule_name: str,
+    path: Path,
+    content: bytes | None = None,
+) -> None:
+    """Add or update a local-file source entry.
+
+    Stores the absolute origin path (so future ``add-rule`` re-runs from the
+    same project register cleanly) plus a sha256 of the current content.
+    """
+    import re
+    if not rule_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", rule_name):
+        raise ValueError(f"Invalid rule name: {rule_name!r}")
+    rules_dir = rules_dir or RULES_DIR
+    sources = load_sources(rules_dir)
+    existing = sources.get(rule_name) or {}
+    # Never demote a URL-tracked entry to a local-path entry. Symmetric with
+    # register_path_source() in hook_sources.py.
+    if "url" in existing:
+        return
+    entry: dict[str, Any] = {
+        "path": str(Path(path).resolve()),
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    if content is not None:
+        entry["sha256"] = hashlib.sha256(content).hexdigest()
+    sources[rule_name] = entry
+    save_sources(rules_dir, sources)
+
+
 def unregister_source(rules_dir: Path | None, rule_name: str) -> bool:
     """Remove a source entry. Returns True if found and removed."""
     rules_dir = rules_dir or RULES_DIR