@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/skill_usage_collect.py

@@ -1,191 +0,0 @@
-#!/usr/bin/env python3
-"""Collect skill-activation signal from Claude Code session jsonl.
-
-Implements step-2-skill-inventory-rationalization.md Phase 1 Step 2.
-Reads `~/.claude/projects/<project-slug>/*.jsonl` for the current repo,
-parses each turn for two signals:
-
-  - exposure: the skill slug appeared in an `attachment.type=skill_listing`
-    payload (catalog presented to the agent that turn).
-  - mention:  the assistant-text response in the same or following turn
-    referenced the slug in backticks with one of the anchor verbs
-    (using, via, per, route, dispatch, invoke, call) OR cited a SKILL.md
-    path under `.augment/skills/<slug>/`, `.claude/skills/<slug>/`, or
-    `dist/agent-src/skills/<slug>/`.
-
-Emits one JSONL record per (session, turn, slug, kind) to
-`agents/runtime/metrics/skill-usage.jsonl` (append-only, deduped on the
-(session_id, turn_idx, slug, kind) tuple).
-
-Privacy: `prompt_excerpt_hash` = SHA-256 of the first 200 chars of the
-user prompt that opened the turn. No raw user or assistant bodies are
-persisted. See `agents/evidence/audits/2026-05-14-north-star/skill-usage-sources.md`.
-"""
-from __future__ import annotations
-
-import argparse
-import hashlib
-import json
-import re
-import sys
-from pathlib import Path
-from typing import Iterable, Iterator
-
-REPO = Path(__file__).resolve().parent.parent.parent
-OUT = REPO / "agents" / "metrics" / "skill-usage.jsonl"
-
-LISTING_LINE_RE = re.compile(r"^-\s+([a-z0-9][a-z0-9_-]+):\s", re.MULTILINE)
-ANCHOR_VERBS = ("using", "via", "per", "route", "routing", "dispatch", "dispatched", "invoke", "call")
-PATH_RE = re.compile(r"\.(?:augment|claude|agent-src)/skills/([a-z0-9][a-z0-9_-]+)/SKILL\.md")
-
-
-def project_slug(repo: Path) -> str:
-    return str(repo).replace("/", "-")
-
-
-def session_files(slug: str) -> list[Path]:
-    base = Path.home() / ".claude" / "projects" / slug
-    if not base.is_dir():
-        return []
-    return sorted(base.glob("*.jsonl"))
-
-
-def iter_turns(jsonl: Path) -> Iterator[dict]:
-    with jsonl.open("r", encoding="utf-8", errors="replace") as fh:
-        for line in fh:
-            line = line.strip()
-            if not line:
-                continue
-            try:
-                yield json.loads(line)
-            except json.JSONDecodeError:
-                continue
-
-
-def extract_listing(entry: dict) -> set[str]:
-    att = entry.get("attachment") or {}
-    if att.get("type") != "skill_listing":
-        return set()
-    content = att.get("content", "") or ""
-    return set(LISTING_LINE_RE.findall(content))
-
-
-def extract_text(entry: dict) -> str:
-    if entry.get("type") != "assistant":
-        return ""
-    msg = entry.get("message") or {}
-    content = msg.get("content")
-    if isinstance(content, str):
-        return content
-    if isinstance(content, list):
-        return "\n".join(p.get("text", "") for p in content if isinstance(p, dict) and p.get("type") == "text")
-    return ""
-
-
-def find_mentions(text: str, known_slugs: Iterable[str]) -> set[str]:
-    hits: set[str] = set()
-    if not text:
-        return hits
-    hits.update(PATH_RE.findall(text))
-    for slug in known_slugs:
-        token = f"`{slug}`"
-        if token not in text:
-            continue
-        lower = text.lower()
-        for verb in ANCHOR_VERBS:
-            if f"{verb} {token}".lower() in lower or f"{verb} the {token}".lower() in lower:
-                hits.add(slug)
-                break
-    return hits
-
-
-def hash_prompt(text: str) -> str:
-    if not text:
-        return ""
-    return hashlib.sha256(text[:200].encode("utf-8", errors="replace")).hexdigest()[:16]
-
-
-def collect_session(jsonl: Path, all_known: set[str]) -> list[dict]:
-    session_id = jsonl.stem
-    records: list[dict] = []
-    last_prompt_hash = ""
-    listed: set[str] = set()
-    turn_idx = -1
-    for entry in iter_turns(jsonl):
-        etype = entry.get("type")
-        if etype == "user":
-            turn_idx += 1
-            msg = entry.get("message") or {}
-            body = msg.get("content") if isinstance(msg.get("content"), str) else ""
-            last_prompt_hash = hash_prompt(body or "")
-            continue
-        if etype == "attachment":
-            listed |= extract_listing(entry)
-            continue
-        if etype == "assistant":
-            text = extract_text(entry)
-            mentions = find_mentions(text, listed | all_known)
-            ts = entry.get("timestamp") or ""
-            for slug in sorted(listed):
-                records.append({"session_id": session_id, "turn_idx": turn_idx, "slug": slug,
-                                "kind": "exposure", "ts": ts, "prompt_excerpt_hash": last_prompt_hash})
-            for slug in sorted(mentions):
-                records.append({"session_id": session_id, "turn_idx": turn_idx, "slug": slug,
-                                "kind": "mention", "ts": ts, "prompt_excerpt_hash": last_prompt_hash})
-            listed = set()
-    return records
-
-
-def load_known_slugs(repo: Path) -> set[str]:
-    slugs: set[str] = set()
-    for root in (repo / ".augment" / "skills", repo / ".claude" / "skills", repo / "dist/agent-src" / "skills"):
-        if not root.is_dir():
-            continue
-        for skill_md in root.glob("*/SKILL.md"):
-            slugs.add(skill_md.parent.name)
-    return slugs
-
-
-def dedup_key(rec: dict) -> tuple:
-    return (rec["session_id"], rec["turn_idx"], rec["slug"], rec["kind"])
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    ap.add_argument("--project-slug", help="Override the ~/.claude/projects slug (defaults to current repo)")
-    ap.add_argument("--out", type=Path, default=OUT, help="Output jsonl (default: agents/runtime/metrics/skill-usage.jsonl)")
-    ap.add_argument("--quiet", action="store_true", help="Suppress non-error output")
-    args = ap.parse_args()
-
-    slug = args.project_slug or project_slug(REPO)
-    files = session_files(slug)
-    if not files:
-        if not args.quiet:
-            print(f"no session files for slug {slug}", file=sys.stderr)
-        return 0
-    known = load_known_slugs(REPO)
-    seen: set[tuple] = set()
-    args.out.parent.mkdir(parents=True, exist_ok=True)
-    if args.out.exists():
-        for line in args.out.read_text(encoding="utf-8", errors="replace").splitlines():
-            try:
-                seen.add(dedup_key(json.loads(line)))
-            except (json.JSONDecodeError, KeyError):
-                continue
-    appended = 0
-    with args.out.open("a", encoding="utf-8") as fh:
-        for jsonl in files:
-            for rec in collect_session(jsonl, known):
-                k = dedup_key(rec)
-                if k in seen:
-                    continue
-                seen.add(k)
-                fh.write(json.dumps(rec, separators=(",", ":")) + "\n")
-                appended += 1
-    if not args.quiet:
-        print(f"✅  Wrote {appended} new record(s) to {args.out.relative_to(REPO)} ({len(seen)} total)")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/src/scripts/skill_usage_report.py

@@ -1,162 +0,0 @@
-#!/usr/bin/env python3
-"""Aggregate `agents/runtime/metrics/skill-usage.jsonl` into a per-skill report.
-
-Implements step-2-skill-inventory-rationalization.md Phase 1 Step 3.
-Groups records by slug; emits `agents/runtime/metrics/skill-usage-report.md`
-with columns:
-
-  slug · exposures_total · mentions_total · exposures_30d · mentions_30d
-       · last_seen · status
-
-`status` ∈ { active, exposed-only, dead } per:
-
-  active        = mentions_30d ≥ 1
-  exposed-only  = exposures_30d ≥ 1 ∧ mentions_30d == 0
-  dead          = exposures_30d == 0
-
-The report is **a baseline, not a verdict**. Rationalization decisions
-live in Phase 2 (`skill-rationalization-candidates.md`).
-"""
-from __future__ import annotations
-
-import argparse
-import json
-from collections import defaultdict
-from datetime import datetime, timedelta, timezone
-from pathlib import Path
-
-REPO = Path(__file__).resolve().parent.parent.parent
-IN = REPO / "agents" / "metrics" / "skill-usage.jsonl"
-OUT = REPO / "agents" / "metrics" / "skill-usage-report.md"
-
-
-def parse_ts(raw: str) -> datetime | None:
-    if not raw:
-        return None
-    try:
-        return datetime.fromisoformat(raw.replace("Z", "+00:00"))
-    except ValueError:
-        return None
-
-
-def load_records(path: Path) -> list[dict]:
-    if not path.exists():
-        return []
-    records: list[dict] = []
-    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
-        if not line.strip():
-            continue
-        try:
-            records.append(json.loads(line))
-        except json.JSONDecodeError:
-            continue
-    return records
-
-
-def aggregate(records: list[dict], now: datetime, window_days: int = 30) -> dict[str, dict]:
-    cutoff = now - timedelta(days=window_days)
-    per: dict[str, dict] = defaultdict(lambda: {
-        "exposures_total": 0, "mentions_total": 0,
-        "exposures_30d": 0, "mentions_30d": 0,
-        "last_seen": None,
-    })
-    for rec in records:
-        slug = rec.get("slug")
-        kind = rec.get("kind")
-        if not slug or kind not in ("exposure", "mention"):
-            continue
-        ts = parse_ts(rec.get("ts") or "")
-        bucket = per[slug]
-        bucket[f"{kind}s_total"] += 1
-        if ts and ts >= cutoff:
-            bucket[f"{kind}s_30d"] += 1
-        if ts and (bucket["last_seen"] is None or ts > bucket["last_seen"]):
-            bucket["last_seen"] = ts
-    return per
-
-
-def status_for(row: dict) -> str:
-    if row["mentions_30d"] >= 1:
-        return "active"
-    if row["exposures_30d"] >= 1:
-        return "exposed-only"
-    return "dead"
-
-
-def all_known_slugs(repo: Path) -> set[str]:
-    slugs: set[str] = set()
-    for root in (repo / ".augment" / "skills", repo / ".claude" / "skills", repo / "dist/agent-src" / "skills"):
-        if not root.is_dir():
-            continue
-        for skill_md in root.glob("*/SKILL.md"):
-            slugs.add(skill_md.parent.name)
-    return slugs
-
-
-def render(per: dict[str, dict], known: set[str]) -> str:
-    rows = []
-    for slug in sorted(known | set(per)):
-        data = per.get(slug, {
-            "exposures_total": 0, "mentions_total": 0,
-            "exposures_30d": 0, "mentions_30d": 0, "last_seen": None,
-        })
-        rows.append({"slug": slug, **data, "status": status_for(data)})
-    rows.sort(key=lambda r: (r["status"] != "dead", -r["exposures_total"], r["slug"]))
-
-    counts = {"active": 0, "exposed-only": 0, "dead": 0}
-    for r in rows:
-        counts[r["status"]] += 1
-    total = len(rows)
-
-    lines = [
-        "# Skill Usage Report (baseline)",
-        "",
-        "> Generated by `scripts/skill_usage_report.py`. Source:",
-        "> `agents/runtime/metrics/skill-usage.jsonl` (collector emits per-turn",
-        "> exposure/mention records). See",
-        "> [`step-2-skill-inventory-rationalization.md`](../roadmaps/step-2-skill-inventory-rationalization.md)",
-        "> Phase 1.",
-        "",
-        f"**Window:** 30-day rolling \u00b7 **Skills tracked:** {total} \u00b7 "
-        f"**Active:** {counts['active']} \u00b7 **Exposed-only:** {counts['exposed-only']} \u00b7 "
-        f"**Dead:** {counts['dead']}",
-        "",
-        "| # | slug | status | exposures_30d | mentions_30d | exposures_total | mentions_total | last_seen |",
-        "|---|---|---|---|---|---|---|---|",
-    ]
-    for i, r in enumerate(rows, 1):
-        last = r["last_seen"].date().isoformat() if r["last_seen"] else "\u2014"
-        lines.append(
-            f"| {i} | `{r['slug']}` | {r['status']} | {r['exposures_30d']} | "
-            f"{r['mentions_30d']} | {r['exposures_total']} | {r['mentions_total']} | {last} |"
-        )
-    lines.append("")
-    lines.append("**Read-out:** rows tagged `dead` are first-cut archive candidates; "
-                 "rows tagged `exposed-only` are first-cut merge / rename candidates "
-                 "(catalog noise, agent never invokes). Phase 2 confirms with "
-                 "structural overlap before any deletion.")
-    lines.append("")
-    return "\n".join(lines)
-
-
-def main() -> int:
-    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    ap.add_argument("--in", dest="inp", type=Path, default=IN)
-    ap.add_argument("--out", type=Path, default=OUT)
-    ap.add_argument("--window", type=int, default=30, help="Rolling window in days")
-    ap.add_argument("--quiet", action="store_true")
-    args = ap.parse_args()
-
-    records = load_records(args.inp)
-    now = datetime.now(timezone.utc)
-    per = aggregate(records, now, args.window)
-    known = all_known_slugs(REPO)
-    args.out.parent.mkdir(parents=True, exist_ok=True)
-    args.out.write_text(render(per, known), encoding="utf-8")
-    if not args.quiet:
-        print(f"\u2705  Wrote {args.out.relative_to(REPO)} ({len(known | set(per))} skill(s))")
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/src/scripts/smoke_path_resolution.py

@@ -1,93 +0,0 @@
-#!/usr/bin/env python3
-"""Smoke-test path resolution against the package's own `.augment/` projection.
-
-Per `agents/roadmaps/road-to-path-fixes.md` Phase 7 (Council Decision 3,
-2026-05-06): the package's `.augment/` tree has the same shape as the
-`.augment/` tree a consumer would receive after `scripts/install.sh`.
-If `load_context:` entries resolve cleanly here, they resolve cleanly
-in any consumer.
-
-What it does:
-  - Walks `.augment/rules/*.md`.
-  - Parses each rule's YAML frontmatter.
-  - Resolves every `load_context:` and `load_context_eager:` entry
-    against the rule file's directory.
-  - Reports any miss with a file:entry line.
-
-Exit codes: 0 = all entries resolve, 1 = one or more misses, 3 = no
-`.augment/rules/` directory found (run `task sync` first).
-"""
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-import yaml
-
-ROOT = Path(__file__).resolve().parent.parent.parent
-AUGMENT_RULES = ROOT / ".augment" / "rules"
-
-
-def _split_frontmatter(text: str):
-    if not text.startswith("---\n"):
-        return None
-    end = text.find("\n---\n", 4)
-    if end == -1:
-        return None
-    try:
-        fm = yaml.safe_load(text[4:end])
-    except yaml.YAMLError:
-        return None
-    return fm if isinstance(fm, dict) else {}
-
-
-def _check_rule(rule_file: Path, misses: list[tuple[str, str]]) -> int:
-    fm = _split_frontmatter(rule_file.read_text(encoding="utf-8"))
-    if not fm:
-        return 0
-    checked = 0
-    rule_dir = rule_file.parent
-    for key in ("load_context", "load_context_eager"):
-        entries = fm.get(key) or []
-        if not isinstance(entries, list):
-            continue
-        for entry in entries:
-            if not isinstance(entry, str):
-                continue
-            checked += 1
-            target = (rule_dir / entry).resolve()
-            if not target.is_file():
-                misses.append((str(rule_file.relative_to(ROOT)), entry))
-    return checked
-
-
-def main() -> int:
-    if not AUGMENT_RULES.is_dir():
-        print(
-            f"❌  {AUGMENT_RULES.relative_to(ROOT)} not found — run `task sync` first",
-            file=sys.stderr,
-        )
-        return 3
-
-    misses: list[tuple[str, str]] = []
-    rule_count = 0
-    entry_count = 0
-    for rule_file in sorted(AUGMENT_RULES.glob("*.md")):
-        rule_count += 1
-        entry_count += _check_rule(rule_file, misses)
-
-    if misses:
-        print(f"❌  {len(misses)} unresolved load_context entr(y/ies):")
-        for rule, entry in misses:
-            print(f"    {rule} → {entry!r}")
-        return 1
-
-    print(
-        f"✅  smoke-path-resolution clean "
-        f"({rule_count} rules, {entry_count} load_context entr(y/ies) resolved)"
-    )
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/src/scripts/smoke_quickstart.py

@@ -1,144 +0,0 @@
-#!/usr/bin/env python3
-"""Structural smoke-test for the README Quickstart path.
-
-Verifies the 3-step Quickstart from a fresh-project perspective:
-
-  1. `scripts/install.py --project <tmpdir>` produces a usable
-     `.agent-settings.yml` with the documented default `rule_loading_tier`.
-  2. The decision_engine block (P2.x of road-to-productization) parses
-     cleanly through the same engine parser the runtime uses.
-  3. The work-engine state-file format (`agents/runtime/state/<id>.json`) is
-     emit-ready — schema for `decision_result` matches the contract.
-
-What it does NOT do:
-  - Invoke a real LLM agent (CI doesn't run a model). The end-to-end
-    `/onboard → /work → decision_result` chain still requires the host
-    agent. This smoke test asserts the *mechanics* the agent depends
-    on, so a Quickstart break is caught before the agent ever runs.
-
-Exit codes: 0 = green; 1 = one or more checks failed; 2 = setup error.
-"""
-from __future__ import annotations
-
-import os
-import shutil
-import subprocess
-import sys
-import tempfile
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parent.parent.parent
-INSTALLER = ROOT / "src" / "scripts" / "install.py"
-TEMPLATE = ROOT / "src" / "config" / "agent-settings.template.yml"
-
-EXPECTED_DEFAULT_PROFILE = "balanced"
-
-
-def _fail(msg: str) -> int:
-    print(f"::error::{msg}", file=sys.stderr)
-    return 1
-
-
-def _check_installer_runs(tmpdir: Path) -> tuple[int, Path | None]:
-    """Step 1 — run installer against a fresh tmpdir."""
-    cmd = [
-        sys.executable,
-        str(INSTALLER),
-        "--project",
-        str(tmpdir),
-        "--package",
-        str(ROOT),
-        "--skip-bridges",
-    ]
-    # ADR-020: --project is reserved for maintainers; CI is a maintainer context.
-    env = {**os.environ, "AGENT_CONFIG_DEV_MODE": "1"}
-    try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=60, env=env)
-    except subprocess.TimeoutExpired:
-        return _fail("installer timed out after 60s"), None
-    if result.returncode != 0:
-        return (
-            _fail(f"installer exited {result.returncode}\nstdout:\n{result.stdout}\nstderr:\n{result.stderr}"),
-            None,
-        )
-    # ADR-038: installer writes the canonical settings file under agents/settings/.
-    settings = tmpdir / "agents" / "settings" / ".agent-settings.yml"
-    if not settings.exists():
-        return _fail("agents/settings/.agent-settings.yml not written by installer"), None
-    return 0, settings
-
-
-def _check_default_profile(settings: Path) -> int:
-    """Step 2 — assert default rule_loading_tier matches the contract."""
-    import yaml
-
-    parsed = yaml.safe_load(settings.read_text(encoding="utf-8"))
-    if not isinstance(parsed, dict):
-        return _fail(f"{settings.name}: top-level is not a YAML mapping")
-    profile = parsed.get("rule_loading_tier")
-    if profile != EXPECTED_DEFAULT_PROFILE:
-        return _fail(
-            f"rule_loading_tier drift: docs/contracts/rule-loading-tier-defaults.md "
-            f"declares '{EXPECTED_DEFAULT_PROFILE}', settings has '{profile!r}'"
-        )
-    return 0
-
-
-def _check_decision_engine_block(settings: Path) -> int:
-    """Step 3 — decision_engine block parses through the engine parser."""
-    sys.path.insert(0, str(ROOT / "src" / "scripts"))
-    from _lib.agent_src import resolve_logical  # noqa: E402
-
-    template_scripts = resolve_logical("templates/scripts") or (
-        ROOT / ".agent-src.uncondensed" / "templates" / "scripts"
-    )
-    sys.path.insert(0, str(template_scripts))
-    try:
-        from work_engine.scoring.decision_engine import (  # type: ignore[import-not-found]
-            DecisionEngineSettings,
-            parse as parse_decision_engine,
-        )
-    except ImportError as exc:
-        return _fail(f"decision_engine module not importable: {exc}")
-
-    import yaml
-
-    parsed = yaml.safe_load(settings.read_text(encoding="utf-8"))
-    block = parsed.get("decision_engine") if isinstance(parsed, dict) else None
-    try:
-        settings_obj = parse_decision_engine(block)
-    except Exception as exc:  # noqa: BLE001 — surface the schema error
-        return _fail(f"decision_engine block rejected by parser: {exc}")
-    if not isinstance(settings_obj, DecisionEngineSettings):
-        return _fail("parser returned non-DecisionEngineSettings instance")
-    return 0
-
-
-def main() -> int:
-    if not INSTALLER.exists():
-        print(f"::error::installer not found at {INSTALLER}", file=sys.stderr)
-        return 2
-    if not TEMPLATE.exists():
-        print(f"::error::template not found at {TEMPLATE}", file=sys.stderr)
-        return 2
-
-    failures = 0
-    tmpdir = Path(tempfile.mkdtemp(prefix="agent-config-quickstart-"))
-    try:
-        rc, settings = _check_installer_runs(tmpdir)
-        failures += rc
-        if settings is not None:
-            failures += _check_default_profile(settings)
-            failures += _check_decision_engine_block(settings)
-    finally:
-        shutil.rmtree(tmpdir, ignore_errors=True)
-
-    if failures:
-        print(f"\n❌  smoke-quickstart: {failures} check(s) failed", file=sys.stderr)
-        return 1
-    print("✅  smoke-quickstart: install → settings → decision_engine green")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())