agent-skilltree 0.2.0__py3-none-any.whl

skilltree/registry.py

@@ -0,0 +1,120 @@
+"""P5.2 — the marketplace as a git repo: registry.json + a contribution gate.
+
+The registry is DATA (pointers), never code we run. A contribution is a PR that
+ADDS entries — and the gate enforces the locked policy:
+
+  - new entries must land `unverified` (promotion is maintainer-only)
+  - contributions may not change another entry's trust, remove others' entries,
+    or rename/re-parent the registry
+  - every entry carries provenance
+
+`promote()` is the separate, maintainer-only step that flips trust upward. This
+is "validate → queue → gated promote" — no auto-merge of agent-loadable content.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+import datetime as _dt
+import json
+from pathlib import Path
+from typing import Any
+
+KINDS = ("skill", "tree", "exchange", "mcp", "registry")   # `registry` = a federated child marketplace
+TRUST = ("unverified", "verified", "featured")
+_REQUIRED = ("name", "kind", "repo")
+
+
+@dataclass
+class Entry:
+    name: str
+    kind: str
+    repo: str
+    manifest: str = ""
+    version: str = "0.1.0"
+    trust: str = "unverified"
+    provenance: dict = field(default_factory=dict)
+
+
+def load_registry(path: str | Path) -> dict:
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+def _by_name(data: dict) -> dict[str, dict]:
+    return {e["name"]: e for e in data.get("entries", [])}
+
+
+def validate_registry(data: dict) -> list[str]:
+    """Schema check on a registry document."""
+    errs: list[str] = []
+    if not isinstance(data.get("name"), str):
+        errs.append("registry: missing string `name`")
+    if "parent" not in data:
+        errs.append("registry: missing `parent` (use null at the root)")
+    if not isinstance(data.get("entries"), list):
+        errs.append("registry: `entries` must be a list")
+        return errs
+    seen: set[str] = set()
+    for i, e in enumerate(data["entries"]):
+        tag = e.get("name", f"#{i}")
+        for f in _REQUIRED:
+            if not e.get(f):
+                errs.append(f"entry {tag}: missing `{f}`")
+        if e.get("kind") not in KINDS:
+            errs.append(f"entry {tag}: kind must be one of {KINDS}")
+        if e.get("trust", "unverified") not in TRUST:
+            errs.append(f"entry {tag}: trust must be one of {TRUST}")
+        if e.get("name") in seen:
+            errs.append(f"entry {tag}: duplicate name")
+        seen.add(e.get("name"))
+    return errs
+
+
+def validate_contribution(base: dict, head: dict, *, actor: str | None = None) -> list[str]:
+    """Gate a PR's registry change. Empty list = a valid (queued, unverified) contribution."""
+    errs = validate_registry(head)
+    if errs:
+        return errs
+    if head.get("name") != base.get("name"):
+        errs.append("contribution may not rename the registry")
+    if head.get("parent") != base.get("parent"):
+        errs.append("contribution may not change the registry parent")
+    b, h = _by_name(base), _by_name(head)
+    for name in h.keys() - b.keys():                      # ADDED
+        e = h[name]
+        if e.get("trust", "unverified") != "unverified":
+            errs.append(f"new entry {name!r} must be `unverified` (promotion is maintainer-only)")
+        if not (e.get("provenance") or {}).get("by"):
+            errs.append(f"new entry {name!r} must carry provenance.by")
+    for name in b.keys() - h.keys():                      # REMOVED
+        errs.append(f"contribution removes existing entry {name!r} (maintainer-only)")
+    for name in b.keys() & h.keys():                      # MODIFIED
+        if h[name].get("trust") != b[name].get("trust"):
+            errs.append(f"contribution changes trust of {name!r} (maintainer-only — use promote)")
+    return errs
+
+
+def promote(path: str | Path, name: str, *, to: str = "verified", by: str | None = None,
+            now: str | None = None) -> Entry:
+    """Maintainer-only: flip an entry's trust. Direct (not via PR)."""
+    if to not in TRUST:
+        raise ValueError(f"trust must be one of {TRUST}")
+    p = Path(path)
+    data = load_registry(p)
+    for e in data.get("entries", []):
+        if e["name"] == name:
+            e["trust"] = to
+            e.setdefault("provenance", {})["promoted_by"] = by or "maintainer"
+            e["provenance"]["promoted_at"] = now or _dt.datetime.now().isoformat(timespec="seconds")
+            p.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
+            return Entry(**{k: e.get(k) for k in ("name", "kind", "repo", "manifest", "version", "trust", "provenance")})
+    raise KeyError(f"no entry named {name!r}")
+
+
+def search(path: str | Path, query: str | None = None, *, min_trust: str = "unverified") -> list[dict]:
+    """Consumer view with a trust floor."""
+    floor = TRUST.index(min_trust)
+    rows = [e for e in load_registry(path).get("entries", []) if TRUST.index(e.get("trust", "unverified")) >= floor]
+    if query:
+        q = query.lower()
+        rows = [e for e in rows if q in e["name"].lower()]
+    return rows

skilltree/reports.py

@@ -0,0 +1,95 @@
+"""The feedback store — the observe→improve half of the Skill OS.
+
+Reports accumulate the gaps and problems found *in use*, so an improver can act
+on them later. Two report kinds to start:
+
+  - `missed_skill`      — a needed skill didn't exist (filed by the agent, or by
+                          the user telling the agent "you missed X").
+  - `expected_not_used` — a skill SHOULD have fired for a task but didn't
+                          ("expected xyz but the skill wasn't used").
+
+`report-missed-skill` (the shipped skill) calls `report_missed` via the CLI. An
+improver agent reads the open reports, then creates/improves skills and calls
+`resolve` to close them.
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import json
+from pathlib import Path
+from typing import Any
+
+DEFAULT_REPORTS = Path.home() / ".claude" / "skill-reports.json"
+
+
+def _now() -> str:
+    return _dt.datetime.now().isoformat(timespec="seconds")
+
+
+def _load(path: Path) -> list[dict]:
+    return json.loads(path.read_text(encoding="utf-8")) if path.is_file() else []
+
+
+def _save(path: Path, rows: list[dict]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(rows, indent=2) + "\n", encoding="utf-8")
+
+
+def file_report(reports_path: str | Path, *, kind: str, by: str, now: str | None = None,
+                **fields: Any) -> dict:
+    path = Path(reports_path)
+    rows = _load(path)
+    entry = {"id": f"r{len(rows) + 1}", "kind": kind, "by": by, "at": now or _now(),
+             "status": "open", **fields}
+    rows.append(entry)
+    _save(path, rows)
+    return entry
+
+
+def report_missed(reports_path: str | Path = DEFAULT_REPORTS, *, needed: str, happened: str,
+                  suggests: str | None = None, by: str = "agent", now: str | None = None) -> dict:
+    """File a missed-skill report: a capability was needed but no skill existed."""
+    return file_report(reports_path, kind="missed_skill", by=by, now=now,
+                       needed=needed, happened=happened, suggests=suggests)
+
+
+def mark_problem(reports_path: str | Path = DEFAULT_REPORTS, *, skill: str, expected: str,
+                 happened: str, by: str = "user", now: str | None = None) -> dict:
+    """Mark 'expected this skill to be used, but it wasn't' — feeds the improver."""
+    return file_report(reports_path, kind="expected_not_used", by=by, now=now,
+                       skill=skill, expected=expected, happened=happened)
+
+
+def list_reports(reports_path: str | Path = DEFAULT_REPORTS, *, kind: str | None = None,
+                 status: str | None = "open") -> list[dict]:
+    rows = _load(Path(reports_path))
+    if kind:
+        rows = [r for r in rows if r.get("kind") == kind]
+    if status:
+        rows = [r for r in rows if r.get("status") == status]
+    return rows
+
+
+def summary(reports_path: str | Path = DEFAULT_REPORTS) -> dict:
+    rows = _load(Path(reports_path))
+    open_rows = [r for r in rows if r.get("status") == "open"]
+    by_kind: dict[str, int] = {}
+    for r in open_rows:
+        by_kind[r["kind"]] = by_kind.get(r["kind"], 0) + 1
+    return {"total": len(rows), "open": len(open_rows), "open_by_kind": by_kind}
+
+
+def resolve(reports_path: str | Path, report_id: str, *, resolution: str,
+            by: str = "improver", now: str | None = None) -> dict:
+    """Close a report (after creating/improving the skill it asked for)."""
+    path = Path(reports_path)
+    rows = _load(path)
+    for r in rows:
+        if r["id"] == report_id:
+            r["status"] = "resolved"
+            r["resolution"] = resolution
+            r["resolved_by"] = by
+            r["resolved_at"] = now or _now()
+            _save(path, rows)
+            return r
+    raise KeyError(f"no report {report_id!r}")

skilltree/search.py

@@ -0,0 +1,148 @@
+"""The `search` arm — coordinate-scoped lexical search over the skill corpus.
+
+v1 (evidence-driven, see .claude/rules + the research): SQLite **FTS5 / BM25** over
+the skill files, with **coordinate-scoped subtree filtering** — rank within any
+coord-rooted region of the tree (`scope_coord="0.1"` → only `0.1` and its
+descendants). For a small corpus of short, keyword-dense skill docs, BM25 is
+enough; the differentiated capability is the subtree scoping (the coordinate is
+the address AND the search scope).
+
+A dense/vector layer fused via RRF is a LATER, evidence-driven upgrade — add it
+only when logged BM25 misses are semantic (synonym/paraphrase), not lexical.
+MCTS-style tree search is for skill *composition* (SCCC), not lookup.
+"""
+from __future__ import annotations
+
+import re
+import sqlite3
+from pathlib import Path
+
+_COORD_NAME = re.compile(r"^([0-9][0-9.]*)-(.+)$")
+_FTS_TERMS = re.compile(r"\w+")
+DEFAULT_EXTS = (".md", ".txt", ".mdx", ".rst")     # folder-mode (foldersearch) corpus
+
+
+def _title(text: str, fallback: str) -> str:
+    """First real heading/line of a doc — the title for a non-SKILL.md file (folder mode)."""
+    for line in text.splitlines():
+        s = line.strip()
+        if s and not s.startswith("---"):
+            return s.lstrip("# ").strip()[:120]
+    return fallback
+
+
+def _corpus(root: Path, exts: "tuple[str, ...] | None"):
+    """The files to index. `exts=None` → SKILL.md only (tree mode, the default). `exts` given →
+    every text file with a matching extension (folder mode), skipping dotfiles."""
+    if exts is None:
+        yield from root.rglob("SKILL.md")
+    else:
+        for p in root.rglob("*"):
+            if (p.is_file() and p.suffix.lower() in exts
+                    and not any(part.startswith(".") for part in p.parts)):
+                yield p
+
+
+def _read_skill(md: Path) -> tuple[str, str, str, str, str, int]:
+    txt = md.read_text(encoding="utf-8", errors="replace")
+    nm = re.search(r"^\s*name:\s*(.+?)\s*$", txt, re.M)
+    ds = re.search(r"^\s*description:\s*(.+?)\s*$", txt, re.M)
+    gl = re.search(r"^\s*glyphs:\s*(.+?)\s*$", txt, re.M)
+    vs = re.search(r"^\s*version:\s*(\d+)", txt, re.M)
+    name = nm.group(1).strip() if nm else _title(txt, md.stem)
+    desc = ds.group(1).strip() if ds else ""
+    glyphs = gl.group(1).strip() if gl else ""
+    version = int(vs.group(1)) if vs else 1
+    body = txt.split("---", 2)[-1].strip() if txt.lstrip().startswith("---") else txt.strip()
+    m = _COORD_NAME.match(name)
+    coord = m.group(1) if m else ""
+    return coord, name, desc, body, glyphs, version
+
+
+def _logical(name: str) -> str:
+    """The stable logical identity of a skill: drop the coord prefix and any `-v<N>` version suffix."""
+    m = _COORD_NAME.match(name)
+    base = m.group(2) if m else name
+    return re.sub(r"-v\d+$", "", base)
+
+
+def build_index(root_dir: str | Path, db_path: str = ":memory:",
+                vocab=None, *, exts: "tuple[str, ...] | None" = None) -> sqlite3.Connection:
+    """Index a corpus under `root_dir` into ONE FTS5/BM25 table. Returns the connection.
+
+    Two corpus modes, ONE engine:
+      - `exts=None` (default) → **tree mode**: index every `SKILL.md` (the skilltree/skillmap
+        corpus; coordinates come from each skill's `<coord>-<name>` frontmatter).
+      - `exts=(...)`           → **folder mode**: index every text file with a matching extension
+        (the former `foldersearch` — any folder; a file with no `<coord>-<name>` name has coord "").
+
+    The `--scope` filter in `search()` is the only difference between the two: it restricts to a
+    coordinate subtree when coordinates are present, and is simply unused on a plain folder.
+
+    GlyphSteer (optional): if `vocab` is given, each skill's `glyphs:` code is rendered to ASCII
+    sentinel **tags** (indexed for faceting; FTS5 drops the emoji); the raw code is kept for display.
+    """
+    con = sqlite3.connect(db_path)
+    con.execute("CREATE VIRTUAL TABLE skills USING fts5(name, description, body, tags, "
+                "coord UNINDEXED, path UNINDEXED, glyphs UNINDEXED, version UNINDEXED)")
+    rows = []
+    for md in _corpus(Path(root_dir), exts):
+        coord, name, desc, body, glyphs, version = _read_skill(md)
+        tags = " ".join(vocab.code_tags(glyphs)) if (vocab and glyphs) else ""
+        rows.append((name, desc, body, tags, coord, str(md), glyphs, version))
+    con.executemany("INSERT INTO skills(name, description, body, tags, coord, path, glyphs, version) "
+                    "VALUES (?,?,?,?,?,?,?,?)", rows)
+    con.commit()
+    return con
+
+
+def _fts_query(q: str) -> str:
+    terms = _FTS_TERMS.findall(q)
+    return " OR ".join(terms) if terms else q
+
+
+def search(con: sqlite3.Connection, query: str, *, scope_coord: str | None = None,
+           facet: str | None = None, vocab=None, limit: int = 10,
+           newest_only: bool = False) -> list[dict]:
+    """BM25-ranked search, optionally scoped to a coordinate subtree and/or faceted by a
+    GlyphSteer glyph (`facet`, resolved to its ASCII sentinel tag via `vocab`).
+    `newest_only=True` forwards only the **newest `version` per logical skill** (history kept on disk,
+    but search returns the latest) — the self-expansion/freshness routing."""
+    sql = ("SELECT name, coord, description, path, glyphs, version, bm25(skills) AS score "
+           "FROM skills WHERE skills MATCH ?")
+    params: list = [_fts_query(query)]
+    if scope_coord:
+        sql += " AND (coord = ? OR coord LIKE ?)"
+        params += [scope_coord, f"{scope_coord}.%"]
+    if facet:
+        tag = (vocab.tag_for(facet) if vocab else None) or facet
+        sql += " AND tags MATCH ?"
+        params.append(tag)
+    sql += " ORDER BY score"               # bm25(): lower = better
+    hits = [{"name": r[0], "coord": r[1], "description": r[2], "path": r[3], "glyphs": r[4],
+             "version": int(r[5]) if str(r[5]).isdigit() else 1, "score": r[6]}
+            for r in con.execute(sql, params)]
+    if newest_only:
+        best: dict[str, dict] = {}
+        for h in hits:                     # keep the highest version per logical name
+            k = _logical(h["name"])
+            if k not in best or h["version"] > best[k]["version"]:
+                best[k] = h
+        hits = sorted(best.values(), key=lambda h: h["score"])
+    return hits[:limit]
+
+
+def search_tree(root_dir: str | Path, query: str, *, scope_coord: str | None = None,
+                facet: str | None = None, vocab=None, limit: int = 10,
+                newest_only: bool = False) -> list[dict]:
+    """Convenience: index a SKILL.md tree and search it in one call."""
+    return search(build_index(root_dir, vocab=vocab), query, scope_coord=scope_coord,
+                  facet=facet, vocab=vocab, limit=limit, newest_only=newest_only)
+
+
+def search_folder(folder: str | Path, query: str, *, scope_coord: str | None = None,
+                  exts: "tuple[str, ...]" = DEFAULT_EXTS, limit: int = 10) -> list[dict]:
+    """Convenience (the folded `foldersearch` + `skillsearch`): index ANY folder's text files and
+    BM25-search them in one call. `scope_coord` restricts to a coordinate subtree when the folder
+    carries skilltree coordinates; on a plain folder it is simply coordinate-free search."""
+    return search(build_index(folder, exts=exts), query, scope_coord=scope_coord, limit=limit)

skilltree/validate.py

@@ -0,0 +1,89 @@
+"""Validate a materialized SkillTree (the `cat`-breadcrumb tree).
+
+The auto-loader only loads the root and never follows the breadcrumbs, so nothing
+guarantees the tree is traversable — this validator is that guarantee. It checks
+the things the filesystem won't:
+
+  - every node has a loadable SKILL.md (name + description frontmatter)
+  - every non-leaf node's body has a Read breadcrumb for EACH of its children
+  - every breadcrumb path actually resolves to a file (no dead ends)
+  - sibling names are unique (their dirs collide otherwise)
+
+A non-empty error list is a kill-criterion: someone walking the tree hits a dead
+end the platform would never warn about.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+import re
+
+from .model import KINDS, SkillTree, TreeNode, skill_name
+
+# a breadcrumb is `- <name> (<kind>): Read `<abspath>`` — match the backticked SKILL.md path
+# (verb-agnostic, so it survives wording tweaks; the verb is the Read tool, never `cat`)
+_CRUMB_RE = re.compile(r"`([^`]+/SKILL\.md)`")
+
+
+@dataclass
+class Violation:
+    severity: str        # "error" | "warning"
+    where: str
+    message: str
+
+
+def _has_frontmatter(skill_md: Path) -> bool:
+    if not skill_md.is_file():
+        return False
+    txt = skill_md.read_text(encoding="utf-8", errors="replace")
+    return bool(re.search(r"^\s*name:\s*\S", txt, re.M) and re.search(r"^\s*description:\s*\S", txt, re.M))
+
+
+def _skill_md(node_dir: Path, name: str) -> Path:
+    return node_dir / ".claude" / "skills" / name / "SKILL.md"
+
+
+def _walk(node: TreeNode, node_dir: Path, out: list[Violation]) -> None:
+    skill_md = _skill_md(node_dir, skill_name(node))
+    if node.kind not in KINDS:
+        out.append(Violation("warning", node.name, f"unknown kind {node.kind!r}"))
+    if not skill_md.is_file():
+        out.append(Violation("error", node.name, f"missing SKILL.md at {skill_md}"))
+        return
+    if not _has_frontmatter(skill_md):
+        out.append(Violation("error", node.name, "SKILL.md lacks name/description frontmatter (won't auto-load)"))
+
+    child_names = [c.name for c in node.children]
+    for d in {n for n in child_names if child_names.count(n) > 1}:
+        out.append(Violation("error", node.name, f"duplicate child name {d!r} (sibling dirs collide)"))
+
+    if node.children:
+        text = skill_md.read_text(encoding="utf-8")
+        found = {Path(m).resolve() for m in _CRUMB_RE.findall(text)}
+        expected = {_skill_md(node_dir / c.name, skill_name(c)).resolve() for c in node.children}
+        for missing in expected - found:
+            out.append(Violation("error", node.name, f"no Read breadcrumb for child → {missing}"))
+        for p in found:
+            if not Path(p).is_file():
+                out.append(Violation("error", node.name, f"dead breadcrumb: `{p}` does not resolve"))
+            elif p not in expected:
+                out.append(Violation("warning", node.name, f"breadcrumb `{p}` is not a declared child"))
+
+    for child in node.children:
+        _walk(child, node_dir / child.name, out)
+
+
+def validate(root: str | Path, tree: SkillTree | None = None) -> list[Violation]:
+    root = Path(root)
+    if tree is None:
+        manifest = root / "skilltree.json"
+        if not manifest.is_file():
+            return [Violation("error", str(root), "no skilltree.json manifest found")]
+        tree = SkillTree.load(manifest)
+    out: list[Violation] = []
+    _walk(tree.root, root, out)          # root node's dir IS the tree root
+    return out
+
+
+def is_valid(root: str | Path, tree: SkillTree | None = None) -> bool:
+    return not any(v.severity == "error" for v in validate(root, tree))