@event4u/agent-config 5.4.1 → 5.6.0

package/scripts/memory_lookup.py

@@ -56,12 +56,21 @@ CURATED_TYPES = {
 # conflict rule still treats them as repo entries against operational.
 KNOWLEDGE_TYPE = "knowledge"
 
+# Cross-repo retrieval (road-to-leaner-core-and-discovery Phase 4). When this
+# type is requested AND opted-in linked-project siblings exist, matches from
+# scripts/cross_repo_retrieve.py are projected as `source="cross-repo"` Hits,
+# scored below curated/knowledge so cross-repo context never outranks the
+# project's own truth (mirrors the 0.85× knowledge discount, then floored
+# further). Opt-in by caller (type must be requested) + lazy import → existing
+# call sites and consumers without the script are unaffected.
+CROSS_REPO_TYPE = "cross-repo"
+
 
 @dataclass
 class Hit:
     id: str
     type: str
-    source: str            # "curated" | "intake" | "operational"
+    source: str            # "curated" | "intake" | "operational" | "knowledge" | "cross-repo"
     path: str              # file (or logical locator) that produced the hit
     score: float           # naive, content-match based [0..1]
     entry: dict = field(default_factory=dict)
@@ -416,6 +425,45 @@ def package_operational_provider() -> Optional[OperationalProvider]:
     return _cli_operational_provider
 
 
+def _cross_repo_hits(keys: list[str], limit: int) -> list[Hit]:
+    """Project cross-repo matches into discounted, tagged Hits.
+
+    Lazy + guarded: imports `cross_repo_retrieve` on demand and swallows any
+    failure (script absent in a consumer install, no opted-in siblings) so the
+    cross-repo type degrades to zero hits rather than breaking retrieval. Scores
+    sit below curated/knowledge (0.85× floor, then a small per-rank decrement)
+    so cross-repo context never outranks the project's own truth.
+    """
+    query = " ".join(k for k in keys if k).strip()
+    if not query:
+        return []
+    try:
+        import os
+        import sys as _sys
+        from pathlib import Path as _Path
+
+        here = _Path(__file__).resolve().parent
+        if str(here) not in _sys.path:
+            _sys.path.insert(0, str(here))
+        import cross_repo_retrieve  # type: ignore
+
+        result = cross_repo_retrieve.retrieve(_Path(os.getcwd()), query, None, limit)
+    except Exception:  # noqa: BLE001 — optional surface; never break retrieval
+        return []
+
+    hits: list[Hit] = []
+    for i, m in enumerate(result.get("matches", [])):
+        hits.append(Hit(
+            id=f"cross-repo:{m.get('source_repo', '')}:{m.get('path', '')}",
+            type=CROSS_REPO_TYPE,
+            source="cross-repo",
+            path=f"{m.get('source_repo', '')}/{m.get('path', '')}",
+            score=round(0.7 * 0.85 - i * 0.01, 4),
+            entry=m,
+        ))
+    return hits
+
+
 def retrieve(
     types: list[str],
     keys: list[str],
@@ -455,6 +503,9 @@ def retrieve(
                     entry=entry,
                 ))
             continue
+        if mtype == CROSS_REPO_TYPE:
+            repo_hits.extend(_cross_repo_hits(keys, limit))
+            continue
         if mtype not in CURATED_TYPES:
             continue
         for path, entry in _iter_curated_entries(mtype):
@@ -503,7 +554,7 @@ CONTRACT_VERSION = 1
 
 # Memory types this file-backed backend can answer. Types outside this
 # set map to `unknown_type` per the retrieval contract.
-_KNOWN_TYPES = CURATED_TYPES | {KNOWLEDGE_TYPE}
+_KNOWN_TYPES = CURATED_TYPES | {KNOWLEDGE_TYPE, CROSS_REPO_TYPE}
 
 
 def retrieve_v1(

package/scripts/project_thin_rules.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Thin-projection of the rule layer (lean-initial-context build-out, Phase 3.1).
+
+The dominant always-on cost is rule BODIES (~58k GPT tok; kernel only ~6.5k).
+0B.6 verdict: demote every non-kernel rule body to a progressive-disclosure
+pointer the agent resolves on trigger-match (the one mechanism 0B.5 confirmed
+works for the primary tool — like skills). The kernel stays full-bodied.
+
+A **thin** rule entry keeps the matching signal (frontmatter `description` +
+`triggers`) so the router still selects it, and replaces the body with a
+one-line pointer to the full text. The agent loads the body on match.
+
+This module is the mechanism + a measurement harness. It writes to a target
+dir of your choosing — it never overwrites the live `.claude/` / `.augment/`
+projections. condense.py reads `lean_projection.mode` (default `eager-all`)
+to decide whether the real generate-tools path calls in here; until that flag
+is flipped + live-A/B-validated, the default projection is unchanged.
+
+Usage:
+    python3 scripts/project_thin_rules.py --measure          # measure delta, no write
+    python3 scripts/project_thin_rules.py --out <dir>        # write thin rules to <dir>
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+from _lib import token_count  # noqa: E402
+
+RULES_SOURCE = REPO_ROOT / ".agent-src" / "rules"
+ROUTER = REPO_ROOT / "dist" / "router.json"
+
+
+def kernel_ids() -> set[str]:
+    """The always-full-bodied set — authoritative kernel list from the router."""
+    return set(json.loads(ROUTER.read_text(encoding="utf-8")).get("kernel", []))
+
+
+def split_frontmatter(text: str) -> tuple[str, str]:
+    """Return (frontmatter_including_fences, body). Empty fm if none."""
+    if text.startswith("---\n"):
+        end = text.find("\n---\n", 4)
+        if end != -1:
+            return text[: end + 5], text[end + 5 :]
+    return "", text
+
+
+def _description(fm: str) -> str:
+    m = re.search(r'^description:\s*"?(.+?)"?\s*$', fm, re.MULTILINE)
+    return m.group(1).strip() if m else ""
+
+
+# How many trigger keywords/phrases to surface as the always-on match hint.
+# The full trigger set lives in dist/router.json (compiled from source) — the
+# projected entry only needs enough signal for the agent to recognise a match
+# and load the body. The router, not this list, drives actual selection.
+_TRIGGER_HINT_LIMIT = 6
+
+
+def _trigger_hint(fm: str) -> str:
+    """A short, comma-joined sample of the rule's trigger keywords/phrases."""
+    hits: list[str] = []
+    for m in re.finditer(r'^\s*-\s*(?:keyword|phrase|intent):\s*"?(.+?)"?\s*$', fm, re.MULTILINE):
+        hits.append(m.group(1).strip())
+        if len(hits) >= _TRIGGER_HINT_LIMIT:
+            break
+    return ", ".join(hits)
+
+
+def thin_entry(rule_id: str, text: str) -> str:
+    """Build the minimal progressive-disclosure pointer for a non-kernel rule.
+
+    The always-on layer keeps only the match signal (description + a short
+    trigger hint) and a pointer to the full body — NOT the full frontmatter.
+    The router (dist/router.json, compiled from source) holds the complete
+    `triggers:` / `routes_to:`; selection is unchanged. Dropping the inlined
+    frontmatter is where the bulk of the token saving comes from.
+    """
+    fm, _body = split_frontmatter(text)
+    desc = _description(fm)
+    hint = _trigger_hint(fm)
+    title = rule_id.replace("-", " ").title()
+    fires = f" Fires on: {hint}." if hint else ""
+    return (
+        f"## {title}\n"
+        f"> Routed rule — load the body on trigger-match.{fires} {desc} "
+        f"Body: [`{rule_id}`](../../.agent-src.uncondensed/rules/{rule_id}.md)\n"
+    )
+
+
+def build_thin(rules_dir: Path = RULES_SOURCE) -> dict[str, str]:
+    """Map {filename: thin_or_full_text} for every rule. Kernel stays full."""
+    kernel = kernel_ids()
+    out: dict[str, str] = {}
+    for p in sorted(rules_dir.glob("*.md")):
+        text = p.read_text(encoding="utf-8")
+        out[p.name] = text if p.stem in kernel else thin_entry(p.stem, text)
+    return out
+
+
+def measure(rules_dir: Path = RULES_SOURCE) -> dict:
+    """Eager vs thin token footprint for the rule layer."""
+    kernel = kernel_ids()
+    eager_blob = "".join(
+        p.read_text(encoding="utf-8") for p in sorted(rules_dir.glob("*.md"))
+    )
+    thin_blob = "".join(build_thin(rules_dir).values())
+    eager = token_count.measure(eager_blob)
+    thin = token_count.measure(thin_blob)
+    n = len(list(rules_dir.glob("*.md")))
+    return {
+        "rules_total": n,
+        "kernel_full": len(kernel & {p.stem for p in rules_dir.glob("*.md")}),
+        "non_kernel_thinned": n - len(kernel & {p.stem for p in rules_dir.glob("*.md")}),
+        "eager_gpt": eager["tokens_gpt"],
+        "thin_gpt": thin["tokens_gpt"],
+        "saved_gpt": eager["tokens_gpt"] - thin["tokens_gpt"],
+        "saved_pct": round(
+            100 * (eager["tokens_gpt"] - thin["tokens_gpt"]) / eager["tokens_gpt"], 1
+        )
+        if eager["tokens_gpt"]
+        else 0.0,
+        "eager_chars": eager["chars"],
+        "thin_chars": thin["chars"],
+        "token_method": token_count.method_note(),
+    }
+
+
+def write_thin(out_dir: Path, rules_dir: Path = RULES_SOURCE) -> int:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    files = build_thin(rules_dir)
+    for name, text in files.items():
+        (out_dir / name).write_text(text, encoding="utf-8")
+    return len(files)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--measure", action="store_true", help="print the eager-vs-thin token delta")
+    ap.add_argument("--out", type=Path, help="write thin rule files to this dir")
+    ap.add_argument("--json", action="store_true")
+    args = ap.parse_args(argv)
+
+    if args.out:
+        n = write_thin(args.out)
+        print(f"wrote {n} thin rule files → {args.out}")
+        return 0
+
+    m = measure()
+    if args.json:
+        print(json.dumps(m, indent=2, sort_keys=True))
+    else:
+        print(f"Rule-layer thin projection (kernel full-bodied + {m['non_kernel_thinned']} non-kernel pointers):")
+        print(f"  eager: {m['eager_gpt']:>6} GPT tok ({m['eager_chars']:,} chars)")
+        print(f"  thin:  {m['thin_gpt']:>6} GPT tok ({m['thin_chars']:,} chars)")
+        print(f"  saved: {m['saved_gpt']:>6} GPT tok  ({m['saved_pct']}% of the rule layer)")
+        print(f"  method: {m['token_method']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/render_value_md.py

@@ -57,10 +57,6 @@ def fmt_signed_int(value: int) -> str:
     return f"{value:+,}".replace(",", " ")
 
 
-def fmt_eur(value: float) -> str:
-    return f"{value:+.2f} €"
-
-
 def fmt_pct(value: float) -> str:
     return f"{value:+.2f}%"
 
@@ -89,7 +85,6 @@ def render_intro(report: Dict[str, Any]) -> str:
     avg_in = ref.get("avg_input_tokens", 8000)
     avg_out = ref.get("avg_output_tokens", 600)
     tier = ref.get("model_tier", "sonnet")
-    sourced = ref.get("pricing_sourced_on", "—")
     return (
         f"# Value Dashboard — was kostet das Paket, was bringt es?\n"
         "\n"
@@ -101,11 +96,12 @@ def render_intro(report: Dict[str, Any]) -> str:
         "\n"
         "## Wie diese Seite zu lesen ist\n"
         "\n"
-        "**Panel A (Kostenleiter)** — von oben nach unten lesen. Jede "
+        "**Panel A (Token-Leiter)** — von oben nach unten lesen. Jede "
         "Stufe sagt: *was sie macht*, *wie viele Input-Tokens sie pro "
-        "Request hinzufügt oder spart*, *was das in € auf "
-        f"{requests:,} Requests kostet*, und *wo wir kumulativ stehen*. "
-        "Die fett gedruckte **NETTO**-Zeile am Ende ist die Antwort.\n"
+        "Request hinzufügt oder spart*, und *wo wir kumulativ stehen*. "
+        "Die fett gedruckte **NETTO**-Zeile am Ende ist die Antwort. "
+        "Bewusst rein in Tokens — kein €-Vergleich, da Abo-Nutzer keine "
+        "Per-Request-API-Preise zahlen.\n"
         "\n"
         "**Panel B (Verhalten)** — vier reale Vergleiche, *mit* vs. "
         "*ohne* Paket. Hier liegt der nicht-Token-Wert: passende Skill-"
@@ -122,8 +118,7 @@ def render_intro(report: Dict[str, Any]) -> str:
         f"- **{requests:,}** Requests, durchschnittlich "
         f"**{avg_in:,}** Input-Tokens und **{avg_out:,}** Output-Tokens "
         "pro Request\n"
-        f"- Modell-Tier: `{tier}` · "
-        f"Preisstand `{sourced}` (Quelle: `internal/bench/pricing.yaml`)\n"
+        f"- Modell-Tier (Workload-Annahme): `{tier}`\n"
         "- Wer einen anderen Workload fährt, rechnet selbst nach — die "
         "Methodik ist offengelegt; nichts ist hardcodiert versteckt.\n"
     )
@@ -135,8 +130,8 @@ def render_panel_a(report: Dict[str, Any]) -> str:
         "Liest sich von oben nach unten. Positive Δ-Werte = das Paket "
         "*kostet* Tokens (Regel-Load ist die ehrliche Up-Front-Steuer); "
         "negative Δ-Werte = das Paket *spart* Tokens.\n",
-        "| Stufe | Was sie tut | Δ Tokens | Δ € (1k Req) | Kumulativ | Quelle |",
-        "|---|---|---:|---:|---:|---|",
+        "| Stufe | Was sie tut | Δ Tokens | Kumulativ | Quelle |",
+        "|---|---|---:|---:|---|",
     ]
     for rung in report.get("cost_ladder", []):
         if rung["id"] == "baseline":
@@ -145,7 +140,6 @@ def render_panel_a(report: Dict[str, Any]) -> str:
             label_cell = rung["label"]
         what = rung.get("what_it_does", "")
         token_delta = int(rung.get("token_delta", 0))
-        eur_delta = float(rung.get("eur_delta", 0.0))
         cum = float(rung.get("cumulative_pct", 0.0))
         conf = confidence_badge(rung.get("confidence", "pending"))
         source = rung.get("source_report", "")
@@ -154,17 +148,16 @@ def render_panel_a(report: Dict[str, Any]) -> str:
             what = f"{what} ⚠️ erst teurer"
         lines.append(
             f"| {label_cell} | {what} | "
-            f"{fmt_signed_int(token_delta)} | {fmt_eur(eur_delta)} | "
+            f"{fmt_signed_int(token_delta)} | "
             f"{fmt_pct(cum)} | `{source}` · {conf} |"
         )
         if rung.get("footnote"):
             lines.append(
-                f"| | _Fußnote:_ {rung['footnote']} | | | | |"
+                f"| | _Fußnote:_ {rung['footnote']} | | | |"
             )
 
     totals = report.get("totals", {})
     cum_tokens = int(totals.get("cumulative_token_delta", 0))
-    cum_eur = float(totals.get("cumulative_eur_delta", 0.0))
     cum_pct = float(totals.get("cumulative_pct", 0.0))
     verdict = totals.get("net_verdict", "—")
     verdict_label = {
@@ -177,8 +170,6 @@ def render_panel_a(report: Dict[str, Any]) -> str:
             "",
             f"{verdict_label} — "
             f"**{fmt_signed_int(cum_tokens)} Tokens / Request**, "
-            f"**{fmt_eur(cum_eur)}** auf "
-            f"{report.get('reference_scale', {}).get('requests', 1000):,} Requests, "
             f"kumulativ **{fmt_pct(cum_pct)}** vs. Baseline.\n",
         ]
     )
@@ -250,10 +241,10 @@ def render_glossary() -> str:
         "nutzt. Spart Output-Tokens — wenn der Korpus es belohnt.\n"
         "- **Ohne Paket / Mit Paket** — *without the package* / *with "
         "the package* — die zwei Arme des A/B-Vergleichs.\n"
-        "- **€-per-1k-requests** — Token-Kosten auf der "
-        "Referenz-Skala (1.000 Requests durchschnittlicher Größe, "
-        "gepreist mit den aktuellen Sonnet-Raten aus "
-        "`internal/bench/pricing.yaml`).\n"
+        "- **Δ Tokens** — Input-Token-Differenz pro Request gegenüber der "
+        "Baseline. Bewusst die einzige Kosten-Einheit: ein €-Vergleich "
+        "würde Per-Request-API-Preise unterstellen, die Abo-Nutzer nicht "
+        "zahlen.\n"
     )
 
 

package/scripts/schemas/command.schema.json

@@ -20,7 +20,7 @@
     "description": {
       "type": "string",
       "minLength": 1,
-      "maxLength": 500
+      "maxLength": 200
     },
     "disable-model-invocation": {
       "type": "boolean",

package/scripts/schemas/rule.schema.json

@@ -20,7 +20,7 @@
     "description": {
       "type": "string",
       "minLength": 1,
-      "maxLength": 500
+      "maxLength": 190
     },
     "alwaysApply": {
       "type": "boolean",

package/scripts/schemas/skill.schema.json

@@ -15,8 +15,8 @@
     "description": {
       "type": "string",
       "minLength": 1,
-      "maxLength": 300,
-      "description": "Trigger phrase; ≤ 200 chars recommended, 300 is the hard ceiling."
+      "maxLength": 220,
+      "description": "Trigger phrase; ≤ 200 chars recommended, 220 is the ceiling (lean-initial-context: descriptions load eagerly via progressive disclosure). Over-cap is a soft warning, not a hard fail — a warning window so authors adapt."
     },
     "source": {
       "type": "string",

package/scripts/skill_discovery.py

@@ -0,0 +1,254 @@
+"""Skill discovery recommender — local-only, explained, no network.
+
+Phase 3 of `road-to-leaner-core-and-discovery`. Turns existing local signals
+(skill catalog frontmatter, role shortlists, optional local-analytics JSONL)
+into a short, *explained* skill shortlist. Every recommendation carries a
+non-empty `why` (contract: docs/contracts/skill-discovery.md). Adds no
+always-loaded layer; reads local files only.
+
+Four classes:
+  most-useful-for-role   — role skills.yml priority order
+  related-to-current-task— skills sharing the role's core domains
+  recently-adopted       — analytics events (last 14d) with a skill id
+  popular-in-role        — analytics skill-events filtered by role, by frequency
+
+Analytics is optional; missing / empty / opted-out degrades gracefully to
+the role shortlist with an honest `why`. Honours the same opt-out as
+local-analytics.md (AGENT_CONFIG_NO_LOCAL_ANALYTICS env + analytics.local config).
+
+Usage:
+    python3 scripts/skill_discovery.py [--role ROLE] [--format text|json] [--limit N]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+SKILLS_DIR = REPO_ROOT / ".agent-src" / "skills"
+ROLES_DIR = REPO_ROOT / "agents" / "roles"
+COMMANDS_DIR = REPO_ROOT / ".agent-src" / "commands"
+RECENT_DAYS = 14
+
+sys.path.insert(0, str(REPO_ROOT / "scripts"))
+try:
+    from _lib.user_global_paths import event4u_root  # type: ignore
+except Exception:  # pragma: no cover - fallback when run outside repo
+    def event4u_root(env=None):  # type: ignore
+        return Path.home() / ".event4u" / "agent-config"
+
+CLASSES = ("most-useful-for-role", "related-to-current-task", "recently-adopted", "popular-in-role")
+
+
+@dataclass
+class Skill:
+    name: str
+    description: str
+    domain: str
+
+
+@dataclass
+class Rec:
+    skill: str
+    cls: str
+    why: str
+    first_command: str = ""
+
+
+def _frontmatter(text: str) -> dict:
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    try:
+        return yaml.safe_load(text[3:end]) or {}
+    except yaml.YAMLError:
+        return {}
+
+
+def load_catalog() -> dict[str, Skill]:
+    out: dict[str, Skill] = {}
+    if not SKILLS_DIR.exists():
+        return out
+    for d in sorted(SKILLS_DIR.iterdir()):
+        sk = d / "SKILL.md"
+        if not sk.is_file():
+            continue
+        fm = _frontmatter(sk.read_text(encoding="utf-8", errors="replace"))
+        name = str(fm.get("name") or d.name).strip().strip('"')
+        out[name] = Skill(name, str(fm.get("description", "")).strip(), str(fm.get("domain", "")).strip())
+    return out
+
+
+def load_role_shortlist(role: str) -> list[dict]:
+    f = ROLES_DIR / role / "skills.yml"
+    if not f.is_file():
+        return []
+    data = yaml.safe_load(f.read_text(encoding="utf-8", errors="replace")) or {}
+    return [s for s in (data.get("skills") or []) if isinstance(s, dict) and s.get("id")]
+
+
+def available_roles() -> list[str]:
+    if not ROLES_DIR.exists():
+        return []
+    return sorted(d.name for d in ROLES_DIR.iterdir() if (d / "skills.yml").is_file())
+
+
+def analytics_enabled(settings: dict) -> bool:
+    if os.environ.get("AGENT_CONFIG_NO_LOCAL_ANALYTICS", "").strip():
+        return False
+    val = ((settings.get("analytics") or {}).get("local"))
+    return str(val).strip().lower() not in ("off", "false", "0", "no")
+
+
+def load_settings() -> dict:
+    try:
+        from _lib.agent_settings import load_agent_settings  # type: ignore
+        return load_agent_settings(cwd=Path.cwd()) or {}
+    except Exception:
+        return {}
+
+
+def load_analytics_events() -> list[dict]:
+    path = event4u_root() / "workspace" / "analytics" / "events.jsonl"
+    if not path.is_file():
+        return []
+    events: list[dict] = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            events.append(json.loads(line))
+        except json.JSONDecodeError:
+            continue
+    return events
+
+
+def _days_ago(ts: str, now: datetime) -> int | None:
+    try:
+        dt = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return (now - dt).days
+    except (ValueError, AttributeError):
+        return None
+
+
+def first_command(name: str) -> str:
+    for cand in (COMMANDS_DIR / f"{name}.md", *COMMANDS_DIR.glob(f"*/{name}.md")):
+        if cand.is_file():
+            return f"/{name}"
+    return f"Skill › {name}"
+
+
+def recommend(role: str, catalog: dict[str, Skill], shortlist: list[dict],
+              events: list[dict], use_analytics: bool, now: datetime, limit: int) -> list[Rec]:
+    recs: list[Rec] = []
+    claimed: set[str] = set()
+
+    def add(name: str, cls: str, why: str) -> None:
+        if name in claimed or name not in catalog or not why:
+            return
+        claimed.add(name)
+        recs.append(Rec(name, cls, why, first_command(name)))
+
+    # 1. most-useful-for-role — role shortlist priority order.
+    short_ids = [s["id"] for s in shortlist]
+    for s in shortlist[:limit]:
+        why = (s.get("why") or "").strip() or f"on the {role} role's priority shortlist"
+        add(s["id"], "most-useful-for-role", why)
+
+    # 2. related-to-current-task — same domain as the role's core skills, not yet shortlisted.
+    role_domains = {catalog[i].domain for i in short_ids if i in catalog and catalog[i].domain}
+    related = [sk for n, sk in sorted(catalog.items())
+               if sk.domain in role_domains and n not in short_ids and sk.domain]
+    for sk in related[:limit]:
+        add(sk.name, "related-to-current-task", f"same domain ({sk.domain}) as your {role} core skills")
+
+    # 3 + 4. analytics-backed, or graceful role-shortlist fallback.
+    skill_events = [e for e in events if isinstance(e.get("data"), dict) and e["data"].get("skill")]
+    if use_analytics and skill_events:
+        recent = sorted(
+            ((e["data"]["skill"], _days_ago(e.get("ts", ""), now)) for e in skill_events),
+            key=lambda kv: (kv[1] is None, kv[1] if kv[1] is not None else 1e9),
+        )
+        for name, days in recent:
+            if days is not None and days <= RECENT_DAYS:
+                add(name, "recently-adopted", f"used {days}d ago in this workspace")
+        role_counts = Counter(
+            e["data"]["skill"] for e in skill_events if e["data"].get("role") == role
+        )
+        for name, n in role_counts.most_common(limit):
+            add(name, "popular-in-role", f"launched {n}× by the {role} role locally")
+    else:
+        reason = "from your role shortlist — no local usage signal yet"
+        for s in shortlist[limit: limit * 2]:
+            add(s["id"], "recently-adopted", reason)
+        for s in shortlist:
+            add(s["id"], "popular-in-role", reason)
+    return recs
+
+
+def render_text(role: str, recs: list[Rec], analytics_on: bool) -> str:
+    lines = [f"# Suggested skills for the `{role}` role", ""]
+    note = "local analytics: on" if analytics_on else "local analytics: off (role shortlist only)"
+    lines.append(f"_{note}_\n")
+    lines += ["| skill | class | why | first command |", "|---|---|---|---|"]
+    for r in recs:
+        lines.append(f"| `{r.skill}` | {r.cls} | {r.why} | `{r.first_command}` |")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(description="Local skill-discovery recommender (read-only, explained).")
+    ap.add_argument("--role", default=None, help="Role id (defaults to active role experience, else prompts).")
+    ap.add_argument("--format", choices=("text", "json"), default="text")
+    ap.add_argument("--limit", type=int, default=5)
+    ap.add_argument("--now", default=None, help="ISO timestamp override for tests.")
+    args = ap.parse_args(argv)
+
+    settings = load_settings()
+    role = args.role or ((settings.get("roles") or {}).get("active_role") or "").strip()
+    roles = available_roles()
+    if not role:
+        print(f"No role given and no active role set. Available roles: {', '.join(roles) or '(none)'}", file=sys.stderr)
+        print("Re-run with --role <role>.", file=sys.stderr)
+        return 2
+    if role not in roles:
+        print(f"Unknown role {role!r}. Available: {', '.join(roles) or '(none)'}", file=sys.stderr)
+        return 2
+
+    catalog = load_catalog()
+    shortlist = load_role_shortlist(role)
+    use_analytics = analytics_enabled(settings)
+    events = load_analytics_events() if use_analytics else []
+    now = datetime.fromisoformat(args.now.replace("Z", "+00:00")) if args.now else datetime.now(timezone.utc)
+    if now.tzinfo is None:
+        now = now.replace(tzinfo=timezone.utc)
+
+    recs = recommend(role, catalog, shortlist, events, use_analytics, now, args.limit)
+
+    if args.format == "json":
+        print(json.dumps({
+            "role": role,
+            "analytics": use_analytics,
+            "recommendations": [r.__dict__ for r in recs],
+        }, indent=2))
+    else:
+        print(render_text(role, recs, use_analytics))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/skill_linter.py

@@ -533,12 +533,16 @@ def detect_artifact_type(path: Path, text: str) -> ArtifactType:
     path_str = str(path).lower()
     has_skill_heading = "## When to use" in text and "## Procedure" in text
 
-    # Skills take priority — /skills/commands/SKILL.md is a skill, not a command
+    # A file inside a /commands/ tree is a command — the commands tree wins,
+    # even for a cluster head literally named `skill.md` or a sub-command under
+    # a `skills/` cluster dir (e.g. /commands/skills/discover.md). The only
+    # /commands/ file that is NOT a command is a nested skill body, which is
+    # always `SKILL.md` (case-sensitive — command files are lowercase).
+    if "/commands/" in path_str and path.name != "SKILL.md":
+        return "command"
+    # Skills: a SKILL.md body, or anything under a /skills/ tree.
     if path.name.lower() == "skill.md" or "/skills/" in path_str:
         return "skill"
-    # Commands are flat .md files in /commands/ directories (not SKILL.md)
-    if "/commands/" in path_str and path.name.lower() != "skill.md":
-        return "command"
     if "/rules/" in path_str:
         return "rule"
     if "/guidelines/" in path_str: