@event4u/agent-config 2.18.0 → 2.20.0

package/scripts/lint_namespace.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Namespace linter. Enforces `<stem>-<intent>` kebab-case + reserved
+names list across skills / rules / commands / personas.
+
+Contract: docs/contracts/namespace.md.
+Wired into: `task lint-skills` (taskfiles/ci-fast.yml).
+"""
+from __future__ import annotations
+import argparse, re, sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+SRC = ROOT / ".agent-src.uncompressed"
+
+# Source-of-truth regex; mirrored in docs/contracts/namespace.md § 1.
+NAME_RE = re.compile(r"^[a-z][a-z0-9]*(-[a-z0-9]+)*$")
+
+MIN_LEN = 2
+MIN_LEN_SKILL = 3
+MAX_LEN = 64
+
+RESERVED = {"pattern", "claude-memories", "default", "index", "router"}
+
+# Filenames that are documentation, not artefacts.
+NON_ARTEFACTS = {"README.md", "INDEX.md"}
+
+# (kind, root, glob, depth, sub_verb) — depth tells us how to extract
+# the name. depth=0 → file stem; depth=1 → first directory under root.
+# sub_verb=True → the path is a `<group>/<verb>.md` form; reserved-name
+# check is skipped because the verb is namespaced under the group.
+TARGETS = [
+    ("skill",    SRC / "skills",    "*/SKILL.md", 1, False),
+    ("rule",     SRC / "rules",     "*.md",       0, False),
+    ("command",  SRC / "commands",  "*.md",       0, False),
+    ("command",  SRC / "commands",  "*/*.md",     0, True),
+    ("persona",  SRC / "personas",  "*.md",       0, False),
+]
+
+
+def _name_for(path: Path, root: Path, depth: int) -> str:
+    if depth == 0:
+        return path.stem
+    rel = path.relative_to(root)
+    return rel.parts[0]
+
+
+def _shape_errors(name: str, *, sub_verb: bool = False,
+                  kind: str = "command") -> list[str]:
+    errs = []
+    floor = MIN_LEN_SKILL if kind == "skill" else MIN_LEN
+    if not (floor <= len(name) <= MAX_LEN):
+        errs.append(f"length — {len(name)} chars (must be {floor}–{MAX_LEN})")
+    if not NAME_RE.match(name):
+        errs.append("regex — must match ^[a-z][a-z0-9]*(-[a-z0-9]+)*$")
+    if name in RESERVED and not sub_verb:
+        errs.append(f"reserved — '{name}' in reserved-names list")
+    return errs
+
+
+def _skill_name_field(path: Path) -> str | None:
+    """Read `name:` from skill frontmatter. None on missing / unparseable."""
+    try:
+        text = path.read_text(encoding="utf-8")
+    except Exception:
+        return None
+    if not text.startswith("---"):
+        return None
+    end = text.find("\n---", 3)
+    if end < 0:
+        return None
+    fm = text[3:end]
+    for line in fm.splitlines():
+        m = re.match(r"^name:\s*['\"]?([^'\"]+)['\"]?\s*$", line.strip())
+        if m:
+            return m.group(1).strip()
+    return None
+
+
+def scan() -> tuple[int, int]:
+    issues = 0
+    checked = 0
+    seen: set[tuple[str, str]] = set()
+    for kind, root, glob, depth, sub_verb in TARGETS:
+        if not root.is_dir():
+            continue
+        for path in sorted(root.glob(glob)):
+            if path.name in NON_ARTEFACTS:
+                continue
+            name = _name_for(path, root, depth)
+            key = (kind, str(path.relative_to(root)))
+            if key in seen:
+                continue
+            seen.add(key)
+            checked += 1
+            errs = _shape_errors(name, sub_verb=sub_verb, kind=kind)
+            if kind == "skill":
+                fm_name = _skill_name_field(path)
+                if fm_name and fm_name != name:
+                    errs.append(f"skill — frontmatter name='{fm_name}' != dir '{name}'")
+            for e in errs:
+                rel = path.relative_to(ROOT)
+                print(f"❌ {rel}: {e}", file=sys.stderr)
+                issues += 1
+    return checked, issues
+
+
+def check_single(name: str) -> int:
+    errs = _shape_errors(name)
+    if not errs:
+        print(f"✅ '{name}' is a valid artefact name")
+        return 0
+    for e in errs:
+        print(f"❌ '{name}': {e}", file=sys.stderr)
+    return 1
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__)
+    ap.add_argument("--name", help="Check a single candidate name and exit.")
+    ap.add_argument("--quiet", action="store_true",
+                    help="Suppress the summary line on success.")
+    args = ap.parse_args()
+    if args.name:
+        return check_single(args.name)
+    checked, issues = scan()
+    if issues:
+        print(f"BASELINE: {issues} issue(s) across {checked} name(s)", file=sys.stderr)
+        return 1
+    if not args.quiet:
+        print(f"BASELINE: 0 issues · {checked} name(s) checked")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/schemas/user-type.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/event4u-app/agent-config/scripts/schemas/user-type.schema.json",
+  "title": "User-type frontmatter",
+  "$comment": "Source: docs/contracts/user-type-schema.md. The runtime review-lens axis seeded under .agent-src.uncompressed/user-types/. Distinct from the install-time user-type-axis YAMLs in user-types/ (root) which carry their own user-type-axis.schema.json.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["id", "kind", "description", "version", "source"],
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]*$",
+      "description": "Must match the user-type filename stem."
+    },
+    "kind": {
+      "type": "string",
+      "const": "user-type",
+      "description": "Discriminator — locks this file as a review-lens user-type, distinct from the install-time user-type-axis YAMLs."
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 240
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^[0-9]+(\\.[0-9]+){0,2}$"
+    },
+    "source": {
+      "type": "string",
+      "enum": ["package", "project"],
+      "description": "Project-specific the typical case — most end-user simulations are consumer-domain, not package-defaults."
+    }
+  }
+}

package/scripts/skill_linter.py

@@ -39,7 +39,7 @@ from validate_frontmatter import (  # noqa: E402
 )
 
 Severity = Literal["error", "warning", "info"]
-ArtifactType = Literal["skill", "rule", "command", "guideline", "persona", "unknown"]
+ArtifactType = Literal["skill", "rule", "command", "guideline", "persona", "user-type", "unknown"]
 
 REQUIRED_PERSONA_SECTIONS_CORE = [
     "Focus",
@@ -57,6 +57,20 @@ REQUIRED_PERSONA_SECTIONS = REQUIRED_PERSONA_SECTIONS_CORE
 VALID_PERSONA_TIERS = {"core", "specialist"}
 # Locked in docs/contracts/persona-schema.md § 4: core ≤ 120, specialist ≤ 100.
 PERSONA_LINE_BUDGETS = {"core": 120, "specialist": 100}
+
+# User-type spine — locked in docs/contracts/user-type-schema.md § 3.
+# Runtime end-user simulation lens (sister axis to personas — methodology vs
+# end-user). Single tier in v1 (no core/specialist split).
+REQUIRED_USERTYPE_SECTIONS = [
+    "Focus",
+    "Daily Workflow",
+    "Vocabulary",
+    "Operational Constraints",
+    "Unique Questions",
+    "Ticket Red Flags",
+    "Anti-Patterns",
+]
+USERTYPE_LINE_BUDGET = 120
 # Wing-scoped overrides — Wing-3 (GTM) and Wing-4 (Money/Strategy/Ops) carry
 # denser cognition (funnel × channel × lifecycle, or finance × org × strategy)
 # than Wing-1/2 specialists, so the line cap rises to keep the seven-section
@@ -514,6 +528,8 @@ def detect_artifact_type(path: Path, text: str) -> ArtifactType:
         return "guideline"
     if "/personas/" in path_str:
         return "persona"
+    if "/user-types/" in path_str:
+        return "user-type"
     if has_skill_heading:
         return "skill"
     return "unknown"
@@ -1849,6 +1865,106 @@ def lint_persona(path: Path, text: str) -> LintResult:
     )
 
 
+def lint_usertype(path: Path, text: str) -> LintResult:
+    """Lint a user-type .md file (frontmatter schema + required sections + size).
+
+    User-types are the runtime end-user simulation lens (sister axis to
+    personas — methodology vs end-user). Contract:
+    docs/contracts/user-type-schema.md.
+    """
+    issues: List[Issue] = []
+
+    frontmatter = extract_frontmatter(text)
+    if not frontmatter:
+        issues.append(Issue("error", "missing_frontmatter", "User-type requires YAML frontmatter"))
+        return LintResult(
+            file=str(path),
+            artifact_type="user-type",
+            status="fail",
+            issues=issues,
+            suggestions=[".agent-src.uncompressed/user-types/_template/user-type.md"],
+        )
+
+    # Required keys per docs/contracts/user-type-schema.md § 1.
+    required = {
+        "id": re.compile(r'^id:\s*"?([\w-]+)"?\s*$', re.MULTILINE),
+        "kind": re.compile(r'^kind:\s*"?([\w-]+)"?\s*$', re.MULTILINE),
+        "description": re.compile(r'^description:\s*"?([^"\n]+?)"?\s*$', re.MULTILINE),
+        "version": re.compile(r'^version:\s*"?([\d.]+)"?\s*$', re.MULTILINE),
+        "source": re.compile(r'^source:\s*"?(package|project)"?\s*$', re.MULTILINE),
+    }
+    parsed: dict = {}
+    for field, pattern in required.items():
+        value = extract_frontmatter_field(frontmatter, pattern)
+        if not value:
+            issues.append(Issue("error", f"missing_{field}", f"User-type frontmatter must declare `{field}`"))
+        else:
+            parsed[field] = value
+
+    if "id" in parsed and parsed["id"] != path.stem:
+        issues.append(Issue(
+            "error",
+            "id_filename_mismatch",
+            f"User-type id `{parsed['id']}` must match filename stem `{path.stem}`",
+        ))
+
+    if "kind" in parsed and parsed["kind"] != "user-type":
+        issues.append(Issue(
+            "error",
+            "invalid_kind",
+            f"User-type kind must be `user-type` (got `{parsed['kind']}`)",
+        ))
+
+    if "description" in parsed and len(parsed["description"]) > 160:
+        issues.append(Issue(
+            "warning",
+            "long_description",
+            f"User-type description is {len(parsed['description'])} chars (target ≤ 160)",
+        ))
+
+    sections = extract_sections(text)
+    for required_section in REQUIRED_USERTYPE_SECTIONS:
+        if required_section not in sections:
+            issues.append(Issue(
+                "error",
+                "missing_section",
+                f"User-type is missing required section `## {required_section}`",
+            ))
+
+    # Anti-Generic Quality Bar: ≥ 3 Unique Questions
+    uq_block = extract_section_block(text, "Unique Questions")
+    if uq_block:
+        bullet_count = len(re.findall(r"^\s*[-*]\s+", uq_block, re.MULTILINE))
+        if bullet_count < 3:
+            issues.append(Issue(
+                "warning",
+                "too_few_unique_questions",
+                f"User-type has {bullet_count} unique questions (target ≥ 3)",
+            ))
+
+    line_count = len(text.splitlines())
+    if line_count > USERTYPE_LINE_BUDGET:
+        issues.append(Issue(
+            "warning",
+            "size_budget",
+            f"User-type has {line_count} lines (budget ≤ {USERTYPE_LINE_BUDGET})",
+        ))
+
+    if not H1_PATTERN.search(text):
+        issues.append(Issue("warning", "missing_h1", "User-type is missing an H1 heading"))
+
+    if not text.endswith("\n"):
+        issues.append(Issue("warning", "no_trailing_newline", "File must end with exactly one newline"))
+
+    return LintResult(
+        file=str(path),
+        artifact_type="user-type",
+        status=classify_status(issues),
+        issues=issues,
+        suggestions=[],
+    )
+
+
 def gather_all_candidate_files(root: Path) -> list[Path]:
     """Gather all lintable files. Prefers .agent-src.uncompressed/ (source of truth).
     Falls back to .agent-src/ only if uncompressed doesn't exist.
@@ -1906,6 +2022,18 @@ def gather_all_candidate_files(root: Path) -> list[Path]:
             if not f.is_symlink():
                 candidates.append(f)
 
+    # User-types (sister axis to personas — methodology vs end-user).
+    # Top-level .md only; README and _template/ subtree excluded.
+    uncompressed_usertypes = root / ".agent-src.uncompressed" / "user-types"
+    augment_usertypes = root / ".agent-src" / "user-types"
+    usertypes_base = uncompressed_usertypes if uncompressed_usertypes.exists() else augment_usertypes
+    if usertypes_base.exists():
+        for f in usertypes_base.glob("*.md"):
+            if f.name.lower() == "readme.md":
+                continue
+            if not f.is_symlink():
+                candidates.append(f)
+
     # Frugality charter (Phase 0.4 Layer 2). Lives in contexts/, not
     # walked by the artifact-type loops above, but still needs the
     # index-integrity check.
@@ -2093,8 +2221,13 @@ def _is_execution_artifact(path: Path, text: str) -> bool:
     path_lower = str(path).lower()
     text_lower = text.lower()
 
-    # Exclude commands, guidelines, and personas — they are not execution-oriented
-    if "/commands/" in path_lower or "/guidelines/" in path_lower or "/personas/" in path_lower:
+    # Exclude commands, guidelines, personas, user-types — not execution-oriented
+    if (
+        "/commands/" in path_lower
+        or "/guidelines/" in path_lower
+        or "/personas/" in path_lower
+        or "/user-types/" in path_lower
+    ):
         return False
 
     # File name match — strong signal
@@ -2779,7 +2912,7 @@ def lint_output_schema(path: Path, text: str) -> List[Issue]:
 
 
 # Artefact types that carry a JSON-Schema contract for their frontmatter.
-_SCHEMA_ARTEFACT_TYPES = {"skill", "rule", "command", "persona"}
+_SCHEMA_ARTEFACT_TYPES = {"skill", "rule", "command", "persona", "user-type"}
 
 
 def lint_frontmatter_schema(path: Path, text: str, artifact_type: str) -> List[Issue]:
@@ -2840,6 +2973,8 @@ def lint_file(path: Path, repo_root: Path | None = None) -> LintResult:
         result = lint_guideline(display_path, text)
     elif artifact_type == "persona":
         result = lint_persona(display_path, text)
+    elif artifact_type == "user-type":
+        result = lint_usertype(display_path, text)
     else:
         # Frugality charter lives in contexts/ (artifact_type == unknown)
         # but still needs Layer 2 index-integrity validation.

package/scripts/skill_overlap.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python3
+"""Structural overlap detection across skills (description + triggers).
+
+Implements step-2-skill-inventory-rationalization.md Phase 2 Step 2.
+Mirrors `scripts/audit_overlap.py` (the rule-side analog) but reads
+`.agent-src.uncompressed/skills/<slug>/SKILL.md` frontmatter directly
+and emits `agents/metrics/skill-overlap.md` listing pairs scoring
+≥ 0.6 on either:
+
+  - description-trigger Jaccard (tokenized union of `description` +
+    any `triggers:` / `keywords:` / `intents:` frontmatter values);
+  - symbol-set overlap (paths cited inside the SKILL.md body —
+    `.agent-src.uncompressed/...`, `agents/...`, `scripts/...`).
+
+The 0.6 threshold matches the roadmap; the rule-side script uses
+lower thresholds because rules have richer trigger metadata. Skills
+encode most signal in prose, so we raise the bar.
+
+Output is **a baseline, not a verdict**. Phase 2 Step 3 combines this
+report with the 30-day activation counts before any action.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from itertools import combinations
+from pathlib import Path
+
+REPO = Path(__file__).resolve().parent.parent
+SKILLS = REPO / ".agent-src.uncompressed" / "skills"
+OUT = REPO / "agents" / "metrics" / "skill-overlap.md"
+
+# Roadmap target. Empirical calibration (210 skills, 2026-05-16) shows
+# this threshold catches structural carbon-copies only — known-similar
+# pairs like blade-ui / flux land around 0.35 token-jaccard because
+# skill descriptions encode distinct trigger language by design.
+STRONG_TOKEN = 0.6
+STRONG_SYMBOL = 0.6
+# Calibrated review threshold — flags pairs worth a Phase 2 Step 3
+# review without exceeding signal-to-noise. Below this, descriptions
+# diverge enough that overlap is coincidental.
+CANDIDATE_TOKEN = 0.30
+CANDIDATE_SYMBOL = 0.50
+# Symbol-jaccard is noisy below this floor — two skills sharing a single
+# context-spine reference produce 1.0 with no signal. Require a non-trivial
+# symbol set on both sides before the symbol axis counts as evidence.
+SYMBOL_MIN_SET = 4
+
+STOPWORDS = {
+    "the", "and", "for", "with", "when", "use", "or", "of", "to", "a", "an",
+    "is", "in", "on", "by", "be", "at", "as", "it", "if", "are", "this",
+    "that", "from", "but", "not", "can", "any", "all", "no", "after",
+    "before", "during", "user", "agent", "code", "project", "via", "into",
+    "onto", "even", "without", "naming", "skill", "skills", "rule", "rules",
+    "command", "commands", "guideline", "guidelines",
+}
+
+PATH_RE = re.compile(r"`?(?:\.agent-src(?:\.uncompressed)?|agents|scripts|docs|tests|\.augment|\.claude)/[A-Za-z0-9_./-]+`?")
+TOKEN_RE = re.compile(r"[A-Za-z][A-Za-z0-9_-]{2,}")
+
+
+def parse_frontmatter(text: str) -> tuple[dict, str]:
+    if not text.startswith("---"):
+        return {}, text
+    parts = text.split("---", 2)
+    if len(parts) < 3:
+        return {}, text
+    fm_raw, body = parts[1], parts[2]
+    fm: dict[str, str] = {}
+    current_key: str | None = None
+    buf: list[str] = []
+    for line in fm_raw.splitlines():
+        if not line.strip():
+            continue
+        if line.startswith(" ") and current_key is not None:
+            buf.append(line.strip())
+            continue
+        if current_key is not None:
+            fm[current_key] = " ".join(buf) if buf else fm.get(current_key, "")
+        if ":" in line:
+            k, v = line.split(":", 1)
+            current_key, buf = k.strip(), []
+            v = v.strip()
+            if v:
+                fm[current_key] = v.strip().strip('"').strip("'")
+                current_key = None
+    if current_key is not None and buf:
+        fm[current_key] = " ".join(buf)
+    return fm, body
+
+
+def tokenize(text: str) -> set[str]:
+    return {t.lower() for t in TOKEN_RE.findall(text or "")
+            if t.lower() not in STOPWORDS and not t.isdigit() and len(t) > 2}
+
+
+def symbol_set(body: str) -> set[str]:
+    return {m.strip("`") for m in PATH_RE.findall(body or "")}
+
+
+def jaccard(a: set, b: set) -> float:
+    if not a and not b:
+        return 0.0
+    return len(a & b) / len(a | b)
+
+
+def load_skills(root: Path) -> list[dict]:
+    skills: list[dict] = []
+    if not root.is_dir():
+        return skills
+    for skill_md in sorted(root.glob("*/SKILL.md")):
+        slug = skill_md.parent.name
+        text = skill_md.read_text(encoding="utf-8", errors="replace")
+        fm, body = parse_frontmatter(text)
+        desc = fm.get("description", "")
+        trig = " ".join(fm.get(k, "") for k in ("triggers", "keywords", "intents", "domain"))
+        skills.append({
+            "slug": slug,
+            "tokens": tokenize(desc + " " + trig),
+            "symbols": symbol_set(body),
+        })
+    return skills
+
+
+def analyse(skills: list[dict]) -> list[dict]:
+    pairs: list[dict] = []
+    for a, b in combinations(skills, 2):
+        j = jaccard(a["tokens"], b["tokens"])
+        if min(len(a["symbols"]), len(b["symbols"])) >= SYMBOL_MIN_SET:
+            s = jaccard(a["symbols"], b["symbols"])
+        else:
+            s = 0.0
+        if j >= STRONG_TOKEN or s >= STRONG_SYMBOL:
+            tier = "strong"
+        elif j >= CANDIDATE_TOKEN or s >= CANDIDATE_SYMBOL:
+            tier = "candidate"
+        else:
+            continue
+        pairs.append({
+            "skill_a": a["slug"], "skill_b": b["slug"],
+            "tier": tier,
+            "description_jaccard": round(j, 3),
+            "symbol_jaccard": round(s, 3),
+        })
+    pairs.sort(key=lambda p: (p["tier"] != "strong",
+                              -max(p["description_jaccard"], p["symbol_jaccard"])))
+    return pairs
+
+
+def render(pairs: list[dict], total: int) -> str:
+    strong = [p for p in pairs if p["tier"] == "strong"]
+    candidate = [p for p in pairs if p["tier"] == "candidate"]
+    lines = [
+        "# Skill Structural Overlap (baseline)",
+        "",
+        "> Generated by `scripts/skill_overlap.py`. Scans",
+        "> `.agent-src.uncompressed/skills/*/SKILL.md` frontmatter (description +",
+        "> trigger metadata) and body symbol references. Reports pairs in two",
+        f"> tiers: **strong** ≥ {STRONG_TOKEN} description-token Jaccard or ≥ {STRONG_SYMBOL}",
+        f"> symbol-set Jaccard (roadmap floor); **candidate** ≥ {CANDIDATE_TOKEN} / ≥ {CANDIDATE_SYMBOL}",
+        "> (empirical calibration — skill descriptions encode distinct trigger",
+        "> language by design, so the roadmap floor catches structural carbon-",
+        "> copies only). See [`step-2-skill-inventory-rationalization.md`](../roadmaps/step-2-skill-inventory-rationalization.md)",
+        "> Phase 2 Step 2.",
+        "",
+        f"**Skills scanned:** {total} · **Strong pairs:** {len(strong)} · "
+        f"**Candidate pairs:** {len(candidate)}",
+        "",
+        "| # | skill_a | skill_b | tier | desc_jaccard | symbol_jaccard |",
+        "|---|---|---|---|---|---|",
+    ]
+    for i, p in enumerate(pairs, 1):
+        lines.append(f"| {i} | `{p['skill_a']}` | `{p['skill_b']}` | {p['tier']} | "
+                     f"{p['description_jaccard']} | {p['symbol_jaccard']} |")
+    lines.append("")
+    lines.append("**Read-out:** `strong` pairs are first-cut merge / supersede candidates. "
+                 "`candidate` pairs are worth a Phase 2 Step 3 review but the description "
+                 "signal is faint — usage data (30-day activation report) is the deciding "
+                 "input, not this report. Structural overlap alone is evidence, not a verdict.")
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--out", type=Path, default=OUT)
+    ap.add_argument("--quiet", action="store_true")
+    args = ap.parse_args()
+    skills = load_skills(SKILLS)
+    if not skills:
+        print(f"no skills under {SKILLS}", file=sys.stderr)
+        return 1
+    pairs = analyse(skills)
+    args.out.parent.mkdir(parents=True, exist_ok=True)
+    args.out.write_text(render(pairs, len(skills)), encoding="utf-8")
+    if not args.quiet:
+        print(f"✅  Wrote {args.out.relative_to(REPO)} "
+              f"({len(skills)} skills, {len(pairs)} pair(s) flagged)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())