@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/audit_skill_descriptions.py

@@ -1,180 +0,0 @@
-#!/usr/bin/env python3
-"""
-Audit skill descriptions for triggering quality.
-
-Flags descriptions that are:
-  - too short (< 150 chars) or too long (> 200 chars, the linter limit)
-  - missing an explicit trigger verb prefix ("use when", "use if", "creates", ...)
-  - containing hedge terms ("may help", "can be useful", "covers various", ...)
-
-Context:
-  `archive/road-to-anthropic-alignment.md` Phase 2.2 — "pushy description" pattern
-  adapted from an external reference (roadmap archived 2026-04-21).
-
-Usage:
-  python3 scripts/audit_skill_descriptions.py               # human table
-  python3 scripts/audit_skill_descriptions.py --json        # machine-readable
-  python3 scripts/audit_skill_descriptions.py --root DIR    # audit another tree
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import re
-import sys
-from dataclasses import asdict, dataclass, field
-from pathlib import Path
-from typing import List
-
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-from _lib.agent_src import artefact_roots  # noqa: E402
-
-DEFAULT_ROOT: Path | None = None
-MIN_LENGTH = 150
-# Mirrors scripts/skill_linter.py `description_too_long` threshold.
-MAX_LENGTH = 200
-
-FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---", re.DOTALL)
-DESCRIPTION_RE = re.compile(r'^description:\s*"?(.*?)"?\s*$', re.MULTILINE)
-
-TRIGGER_PREFIX_RE = re.compile(
-    r"^\s*("
-    r"use\s+(when|if|for)\b|only\s+when\b|"
-    r"creates?\b|reviews?\b|writes?\b|handles?\b|generates?\b|runs?\b|"
-    r"builds?\b|fetches?\b|validates?\b|audits?\b|analyzes?\b|detects?\b|"
-    r"plans?\b|deploys?\b|configures?\b|scaffolds?\b|fixes?\b|refactors?\b|"
-    r"optimizes?\b|renders?\b|syncs?\b|explores?\b|installs?\b|updates?\b|"
-    r"manages?\b|orchestrates?\b|prepares?\b|finds?\b|executes?\b|reads?\b|"
-    r"checks?\b|tracks?\b"
-    r")",
-    re.IGNORECASE,
-)
-
-HEDGE_PHRASES = (
-    "may help",
-    "can be useful",
-    "covers various",
-    "might be",
-    "generally",
-    "as needed",
-    "when appropriate",
-)
-
-
-@dataclass
-class Finding:
-    skill: str
-    path: str
-    description: str
-    length: int
-    flags: List[str] = field(default_factory=list)
-
-    @property
-    def score(self) -> int:
-        # Higher score = worse. Used for sorting.
-        penalty = 0
-        if "no-trigger-prefix" in self.flags:
-            penalty += 30
-        if "too-short" in self.flags:
-            penalty += 20
-        if "very-short" in self.flags:
-            penalty += 10
-        penalty += sum(10 for f in self.flags if f.startswith("hedge:"))
-        return penalty
-
-
-def extract_description(text: str) -> str:
-    m = FRONTMATTER_RE.search(text)
-    if not m:
-        return ""
-    d = DESCRIPTION_RE.search(m.group(1))
-    return d.group(1).strip() if d else ""
-
-
-def audit_description(description: str) -> List[str]:
-    flags: List[str] = []
-    if not description:
-        flags.append("missing")
-        return flags
-    length = len(description)
-    if length < 80:
-        flags.append("very-short")
-    elif length < MIN_LENGTH:
-        flags.append("too-short")
-    if length > MAX_LENGTH:
-        flags.append("too-long")
-    if not TRIGGER_PREFIX_RE.match(description):
-        flags.append("no-trigger-prefix")
-    lowered = description.lower()
-    for phrase in HEDGE_PHRASES:
-        if phrase in lowered:
-            flags.append(f"hedge:{phrase}")
-    return flags
-
-
-def collect_findings(root: Path) -> List[Finding]:
-    findings: List[Finding] = []
-    for skill_md in sorted(root.glob("*/SKILL.md")):
-        text = skill_md.read_text(encoding="utf-8")
-        description = extract_description(text)
-        flags = audit_description(description)
-        findings.append(
-            Finding(
-                skill=skill_md.parent.name,
-                path=str(skill_md),
-                description=description,
-                length=len(description),
-                flags=flags,
-            )
-        )
-    return findings
-
-
-def render_text(findings: List[Finding], worst_only: bool) -> str:
-    flagged = [f for f in findings if f.flags]
-    flagged.sort(key=lambda f: (-f.score, f.skill))
-    lines = [f"Audited {len(findings)} skills, {len(flagged)} flagged.\n"]
-    if not flagged:
-        lines.append("✅  All descriptions look reasonable.")
-        return "\n".join(lines)
-    lines.append(f"{'SCORE':>5}  {'LEN':>4}  {'SKILL':<40}  FLAGS")
-    lines.append("-" * 90)
-    shown = flagged[:15] if worst_only else flagged
-    for f in shown:
-        lines.append(
-            f"{f.score:>5}  {f.length:>4}  {f.skill:<40}  {', '.join(f.flags)}"
-        )
-    if worst_only and len(flagged) > 15:
-        lines.append(f"\n... {len(flagged) - 15} more (use --full to show all)")
-    return "\n".join(lines)
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--root", type=Path, default=None)
-    parser.add_argument("--json", action="store_true", help="emit JSON")
-    parser.add_argument("--full", action="store_true", help="show all flagged, not just top 15")
-    args = parser.parse_args()
-    if args.root is not None:
-        if not args.root.exists():
-            print(f"error: {args.root} does not exist", file=sys.stderr)
-            return 2
-        roots = [args.root]
-    else:
-        roots = [r / "skills" for r in artefact_roots() if (r / "skills").is_dir()]
-        if not roots:
-            print("error: no skills/ directories found across artefact roots", file=sys.stderr)
-            return 2
-    findings: List[Finding] = []
-    for r in roots:
-        findings.extend(collect_findings(r))
-    if args.json:
-        print(json.dumps([asdict(f) for f in findings], indent=2))
-    else:
-        print(render_text(findings, worst_only=not args.full))
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/audit_skill_overlap.py

@@ -1,207 +0,0 @@
-#!/usr/bin/env python3
-"""Skill-family content-overlap analysis (6.0.0-C Phase 4 Step 8).
-
-Walks every ``SKILL.md`` across the package skill roots, builds a keyword
-vector from the body (frontmatter stripped), and flags pairs whose
-content cosine-similarity is >= OVERLAP_THRESHOLD. Each pair is annotated
-with whether the two skills share a domain (their ``packs:`` sets intersect)
-— the same-domain >70%-overlap pairs are the merge candidates the
-evidence-based-pruning contract consumes.
-
-Content similarity, NOT name prefix: `api-design` and `api-testing` are only
-flagged if their *bodies* overlap, not because they share the `api-` prefix.
-
-THIS SCRIPT MERGES NOTHING. It produces a candidate report for a future,
-human-driven consolidation roadmap (docs/contracts/evidence-based-pruning.md).
-
-Output:
-  - agents/reports/skill-overlap.json (machine-readable)
-  - agents/reports/skill-overlap.md  (human-readable)
-
-Usage:
-  python3 scripts/audit_skill_overlap.py
-  python3 scripts/audit_skill_overlap.py --threshold 0.7 --quiet
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import math
-import re
-import sys
-from collections import Counter
-from dataclasses import dataclass, field
-from itertools import combinations
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent.parent
-REPORT_DIR = ROOT / "agents" / "reports"
-OUT_JSON = REPORT_DIR / "skill-overlap.json"
-OUT_MD = REPORT_DIR / "skill-overlap.md"
-FM_RE = re.compile(r"^---\n(.*?)\n---", re.DOTALL)
-OVERLAP_THRESHOLD = 0.7  # evidence-based-pruning.md: >70% content overlap
-
-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", "run", "runs", "running", "each",
-    "every", "one", "two", "now", "then", "also", "based", "default", "skill",
-    "you", "your", "should", "must", "see", "do", "not",
-}
-
-
-@dataclass
-class Skill:
-    name: str
-    relpath: str
-    packs: set[str] = field(default_factory=set)
-    vector: Counter = field(default_factory=Counter)
-
-
-def _skill_roots() -> list[Path]:
-    pkgs = ROOT / "packages"
-    roots = [d for d in pkgs.glob("*/.agent-src.uncondensed/skills")
-             if d.is_dir()] if pkgs.is_dir() else []
-    legacy = ROOT / ".agent-src.uncondensed" / "skills"
-    if not roots and legacy.is_dir():
-        roots = [legacy]
-    return roots
-
-
-def _keyword_vector(text: str) -> Counter:
-    tokens = re.findall(r"[a-z][a-z0-9_-]{2,}", text.lower())
-    return Counter(t for t in tokens if t not in STOPWORDS)
-
-
-def _cosine(a: Counter, b: Counter) -> float:
-    shared = set(a) & set(b)
-    if not shared:
-        return 0.0
-    num = sum(a[t] * b[t] for t in shared)
-    da = math.sqrt(sum(v * v for v in a.values()))
-    db = math.sqrt(sum(v * v for v in b.values()))
-    return num / (da * db) if da and db else 0.0
-
-
-def _parse(md: Path) -> Skill:
-    import yaml
-    text = md.read_text(encoding="utf-8")
-    fm: dict = {}
-    body = text
-    m = FM_RE.search(text)
-    if m:
-        try:
-            fm = yaml.safe_load(m.group(1)) or {}
-        except yaml.YAMLError:
-            fm = {}
-        body = text[m.end():]
-    name = fm.get("name") if isinstance(fm, dict) else None
-    packs = fm.get("packs") if isinstance(fm, dict) else None
-    return Skill(
-        name=str(name) if name else md.parent.name,
-        relpath=str(md.relative_to(ROOT)),
-        packs=set(packs) if isinstance(packs, list) else set(),
-        vector=_keyword_vector(body),
-    )
-
-
-def collect() -> list[Skill]:
-    skills: list[Skill] = []
-    seen: set[str] = set()
-    for root in _skill_roots():
-        for md in sorted(root.rglob("SKILL.md")):
-            if "_archive" in md.parts:
-                continue
-            key = md.parent.name
-            if key in seen:
-                continue
-            seen.add(key)
-            skills.append(_parse(md))
-    return skills
-
-
-def find_pairs(skills: list[Skill], threshold: float) -> list[dict]:
-    pairs: list[dict] = []
-    for a, b in combinations(skills, 2):
-        sim = _cosine(a.vector, b.vector)
-        if sim >= threshold:
-            shared = sorted(a.packs & b.packs)
-            pairs.append({
-                "a": a.name, "b": b.name,
-                "a_path": a.relpath, "b_path": b.relpath,
-                "similarity": round(sim, 3),
-                "same_domain": bool(shared),
-                "shared_packs": shared,
-            })
-    pairs.sort(key=lambda p: (not p["same_domain"], -p["similarity"]))
-    return pairs
-
-
-def render_md(skills: list[Skill], pairs: list[dict], threshold: float) -> str:
-    merge = [p for p in pairs if p["same_domain"]]
-    cross = [p for p in pairs if not p["same_domain"]]
-    L = [
-        "# Skill-family overlap report (6.0.0-C Phase 4 Step 8)\n",
-        f"> Content cosine-similarity over {len(skills)} skills; pairs at "
-        f"≥ {threshold:.0%}. **Same-domain pairs (shared `packs:`) are the "
-        f"merge candidates** consumed by "
-        f"[`evidence-based-pruning.md`](../../docs/contracts/evidence-based-pruning.md). "
-        f"This report merges NOTHING — it is input to a future, human-driven "
-        f"consolidation roadmap.\n",
-        f"\n- Skills scanned: **{len(skills)}**",
-        f"\n- Overlap pairs ≥ {threshold:.0%}: **{len(pairs)}** "
-        f"({len(merge)} same-domain merge candidates, {len(cross)} cross-domain)\n",
-        "\n## Merge candidates — same-domain, ≥ threshold\n",
-    ]
-    if not merge:
-        L.append("None — no same-domain pair exceeds the overlap threshold.\n")
-    else:
-        L.append("| Skill A | Skill B | similarity | shared packs |")
-        L.append("|---|---|--:|---|")
-        for p in merge:
-            L.append(f"| `{p['a']}` | `{p['b']}` | {p['similarity']:.0%} | "
-                     f"{', '.join(p['shared_packs'])} |")
-    L.append("\n## Cross-domain overlaps (informational, not merge candidates)\n")
-    if not cross:
-        L.append("None.\n")
-    else:
-        L.append("| Skill A | Skill B | similarity |")
-        L.append("|---|---|--:|")
-        for p in cross:
-            L.append(f"| `{p['a']}` | `{p['b']}` | {p['similarity']:.0%} |")
-    return "\n".join(L) + "\n"
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__)
-    ap.add_argument("--threshold", type=float, default=OVERLAP_THRESHOLD)
-    ap.add_argument("--quiet", action="store_true")
-    args = ap.parse_args()
-
-    skills = collect()
-    if not skills:
-        print("❌  No skills found under the package skill roots.", file=sys.stderr)
-        return 3
-    pairs = find_pairs(skills, args.threshold)
-    REPORT_DIR.mkdir(parents=True, exist_ok=True)
-    OUT_JSON.write_text(json.dumps({
-        "threshold": args.threshold,
-        "skills_scanned": len(skills),
-        "pairs": pairs,
-    }, indent=2), encoding="utf-8")
-    OUT_MD.write_text(render_md(skills, pairs, args.threshold), encoding="utf-8")
-
-    if not args.quiet:
-        merge = sum(1 for p in pairs if p["same_domain"])
-        print(f"✅  Skill overlap: {len(skills)} skills, {len(pairs)} pair(s) "
-              f"≥ {args.threshold:.0%} ({merge} same-domain merge candidate(s)).")
-        print(f"   JSON: {OUT_JSON.relative_to(ROOT)}")
-        print(f"   MD:   {OUT_MD.relative_to(ROOT)}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/audit_user_type_axis.py

@@ -1,140 +0,0 @@
-#!/usr/bin/env python3
-"""Audit the user-type axis frontmatter coverage (step-9 Phase 4).
-
-Two checks across `.agent-src.uncondensed/skills/`:
-
-1. **Orphan values** — every `recommended_for_user_types` value must have
-   a corresponding `user-types/<value>.yml` config. Orphans are FATAL
-   (exit 1) — they imply the runtime filter would tag prompts against a
-   user-type with no documented identity.
-2. **Unused configs** — every `user-types/*.yml` should be consumed by
-   at least one skill. Unused configs are WARN-only (exit 0): seeding
-   future identities ahead of consumption is allowed.
-
-Writes a markdown report to `agents/runtime/reports/user-type-axis-audit.md` and
-emits a one-line summary to stdout. Stdlib-only — no PyYAML dependency.
-
-Usage:
-    python3 scripts/audit_user_type_axis.py            # human report + exit code
-    python3 scripts/audit_user_type_axis.py --quiet    # exit code only
-"""
-
-from __future__ import annotations
-
-import re
-import sys
-from collections import defaultdict
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parent.parent.parent
-SKILLS_ROOT = REPO_ROOT / ".agent-src.uncondensed" / "skills"
-USER_TYPES_ROOT = REPO_ROOT / "user-types"
-REPORT_PATH = REPO_ROOT / "agents" / "reports" / "user-type-axis-audit.md"
-
-_FRONTMATTER_LINE = re.compile(
-    r"^recommended_for_user_types:\s*\[([^\]]*)\]\s*$",
-    re.MULTILINE,
-)
-
-
-def _declared_user_types() -> set[str]:
-    """Read `user-types/*.yml` stems (one identity per YAML file)."""
-    if not USER_TYPES_ROOT.is_dir():
-        return set()
-    return {p.stem for p in USER_TYPES_ROOT.glob("*.yml")}
-
-
-def _scan_skill_values() -> dict[str, list[Path]]:
-    """Map every frontmatter user-type value → list of declaring SKILL.md paths."""
-    by_value: dict[str, list[Path]] = defaultdict(list)
-    if not SKILLS_ROOT.is_dir():
-        return by_value
-    for skill_md in sorted(SKILLS_ROOT.rglob("SKILL.md")):
-        text = skill_md.read_text(encoding="utf-8", errors="replace")
-        # Frontmatter is the leading `---` block — strip everything after.
-        if text.startswith("---\n"):
-            end = text.find("\n---", 4)
-            fm = text[4:end] if end >= 0 else text
-        else:
-            fm = text[:4096]
-        match = _FRONTMATTER_LINE.search(fm)
-        if not match:
-            continue
-        for raw in match.group(1).split(","):
-            value = raw.strip().strip('"').strip("'")
-            if value:
-                by_value[value].append(skill_md.relative_to(REPO_ROOT))
-    return by_value
-
-
-def _render_report(
-    declared: set[str],
-    by_value: dict[str, list[Path]],
-    orphans: set[str],
-    unused: set[str],
-) -> str:
-    lines: list[str] = [
-        "# User-type axis — frontmatter coverage audit",
-        "",
-        "Generated by `scripts/audit_user_type_axis.py` (step-9 Phase 4).",
-        "",
-        f"- Declared user-types (`user-types/*.yml`): **{len(declared)}**",
-        f"- Distinct frontmatter values across skills: **{len(by_value)}**",
-        f"- Orphans (FATAL): **{len(orphans)}**",
-        f"- Unused configs (WARN): **{len(unused)}**",
-        "",
-        "## Coverage matrix",
-        "",
-        "| user-type | declared | consuming skills |",
-        "| --- | --- | --- |",
-    ]
-    for ut in sorted(declared | set(by_value)):
-        flag_declared = "yes" if ut in declared else "**no (orphan)**"
-        count = len(by_value.get(ut, []))
-        lines.append(f"| `{ut}` | {flag_declared} | {count} |")
-    if orphans:
-        lines.extend(["", "## Orphans", ""])
-        for orphan in sorted(orphans):
-            lines.append(f"- `{orphan}` — referenced by:")
-            for path in by_value[orphan]:
-                lines.append(f"  - `{path}`")
-    if unused:
-        lines.extend(["", "## Unused configs (WARN)", ""])
-        for stem in sorted(unused):
-            lines.append(f"- `user-types/{stem}.yml` has no consuming skill yet.")
-    lines.append("")
-    return "\n".join(lines)
-
-
-def main(argv: list[str]) -> int:
-    quiet = "--quiet" in argv
-    declared = _declared_user_types()
-    by_value = _scan_skill_values()
-    used = set(by_value)
-    orphans = used - declared
-    unused = declared - used
-
-    report = _render_report(declared, by_value, orphans, unused)
-    REPORT_PATH.parent.mkdir(parents=True, exist_ok=True)
-    REPORT_PATH.write_text(report, encoding="utf-8")
-
-    if not quiet:
-        sys.stdout.write(
-            f"user-type-axis audit — declared={len(declared)} "
-            f"used={len(used)} orphans={len(orphans)} unused={len(unused)}\n"
-        )
-        if orphans:
-            sys.stdout.write(
-                "  FAIL orphans: " + ", ".join(sorted(orphans)) + "\n"
-            )
-        if unused:
-            sys.stdout.write(
-                "  warn unused: " + ", ".join(sorted(unused)) + "\n"
-            )
-        sys.stdout.write(f"  report: {REPORT_PATH.relative_to(REPO_ROOT)}\n")
-
-    return 1 if orphans else 0
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))