@event4u/agent-config 5.10.0 → 6.0.0

package/scripts/cross_repo_retrieve.py

@@ -1,172 +0,0 @@
-"""Cross-repo retrieval — read-only, targeted, opt-in (ADR-032 Option A).
-
-Phase 4 of `road-to-leaner-core-and-discovery`. Given a query and the opted-in
-`linked_projects` siblings, runs a bounded *targeted* search (path-glob +
-content grep — never a full walk) and returns the retrieval envelope defined in
-`docs/contracts/cross-repo-retrieval.md`. Reuses the redaction + chunking floor
-from `knowledge_ingest.py` so no secret crosses a repo boundary.
-
-Scope guards (Option A):
-  - read-only, no writes, no network;
-  - only siblings with `include: true` in agents/settings/.agent-settings.local.yml;
-  - `large`-flagged siblings REQUIRE a `--path-scope` (reject an unscoped query);
-  - ≤ --max-chunks results, one concept per query.
-
-Usage:
-    python3 scripts/cross_repo_retrieve.py "<query>" [--path-scope GLOB]
-            [--max-chunks N] [--format text|json] [--root PATH]
-"""
-from __future__ import annotations
-
-import argparse
-import fnmatch
-import json
-import subprocess
-import sys
-from pathlib import Path
-
-REPO_ROOT = Path(__file__).resolve().parent.parent
-sys.path.insert(0, str(REPO_ROOT / "scripts"))
-sys.path.insert(0, str(REPO_ROOT / "packages" / "core" / "installer" / "python"))
-from linked_projects_list import collect as collect_siblings  # type: ignore  # noqa: E402
-
-try:
-    from knowledge_ingest import redact, chunk_text  # type: ignore
-except Exception:  # pragma: no cover - keep retrieval usable if ingest moves
-    def redact(text, counters):  # type: ignore
-        return text, 0
-
-    def chunk_text(text, target_bytes=2048):  # type: ignore
-        return [text[:target_bytes]] if text else []
-
-DEFAULT_MAX_CHUNKS = 8
-MAX_FILES_SCANNED = 2000  # hard ceiling on the targeted walk, defence-in-depth
-TEXT_SUFFIXES = {".md", ".txt", ".py", ".ts", ".tsx", ".js", ".jsx", ".php", ".go",
-                 ".rs", ".rb", ".java", ".json", ".yml", ".yaml", ".toml", ".sql", ".sh"}
-SKIP_DIRS = {".git", "node_modules", "dist", "vendor", ".venv", "__pycache__",
-             ".idea", ".vscode", "build", "target", ".next", "coverage"}
-
-
-def _freshness(repo: Path, rel: str) -> str:
-    try:
-        out = subprocess.run(
-            ["git", "log", "-1", "--format=%ad", "--date=short", "--", rel],
-            cwd=repo, capture_output=True, text=True, timeout=8, check=False,
-        )
-        if out.returncode == 0 and out.stdout.strip():
-            return out.stdout.strip()
-    except (OSError, subprocess.SubprocessError):
-        pass
-    try:
-        from datetime import datetime, timezone
-        ts = (repo / rel).stat().st_mtime
-        return datetime.fromtimestamp(ts, timezone.utc).date().isoformat()
-    except OSError:
-        return "unknown"
-
-
-def _iter_files(repo: Path, path_scope: str | None):
-    count = 0
-    for p in sorted(repo.rglob("*")):
-        if count >= MAX_FILES_SCANNED:
-            break
-        if not p.is_file() or p.suffix.lower() not in TEXT_SUFFIXES:
-            continue
-        if any(part in SKIP_DIRS for part in p.relative_to(repo).parts):
-            continue
-        rel = str(p.relative_to(repo))
-        if path_scope and not fnmatch.fnmatch(rel, path_scope):
-            continue
-        count += 1
-        yield p, rel
-
-
-def _terms(query: str) -> list[str]:
-    return [t for t in query.lower().replace(",", " ").split() if len(t) > 2]
-
-
-def search_sibling(repo: Path, query: str, terms: list[str], path_scope: str | None,
-                   budget: int) -> list[dict]:
-    hits: list[dict] = []
-    repo_name = repo.name
-    for p, rel in _iter_files(repo, path_scope):
-        if len(hits) >= budget:
-            break
-        rel_lower = rel.lower()
-        path_match = any(t in rel_lower for t in terms)
-        try:
-            text = p.read_text(encoding="utf-8", errors="replace")
-        except OSError:
-            continue
-        text_lower = text.lower()
-        content_terms = [t for t in terms if t in text_lower]
-        if not path_match and not content_terms:
-            continue
-        # Pull the most relevant chunk (first chunk containing a term, else the head).
-        chunks = chunk_text(text)
-        chosen = next((c for c in chunks if any(t in c.lower() for t in terms)), chunks[0] if chunks else "")
-        redacted, _ = redact(chosen, {})
-        reason = (f"path matches: {rel}" if path_match
-                  else f"content term(s): {', '.join(content_terms[:3])}")
-        hits.append({
-            "source_repo": repo_name,
-            "path": rel,
-            "chunk": redacted[:2048],
-            "freshness": _freshness(repo, rel),
-            "match_reason": reason,
-        })
-    return hits
-
-
-def retrieve(root: Path, query: str, path_scope: str | None, max_chunks: int) -> dict:
-    siblings = collect_siblings(root, show_all=False)  # opted-in only
-    if not siblings:
-        return {"query": query, "matches": [], "note": "no opted-in linked-project siblings — nothing to search"}
-    terms = _terms(query)
-    if not terms:
-        return {"query": query, "matches": [], "note": "query too short — give at least one term > 2 chars"}
-    matches: list[dict] = []
-    skipped: list[str] = []
-    for sib in siblings:
-        if len(matches) >= max_chunks:
-            break
-        repo = Path(sib["path"])
-        if sib.get("large") and not path_scope:
-            skipped.append(sib["path"])
-            continue
-        matches.extend(search_sibling(repo, query, terms, path_scope, max_chunks - len(matches)))
-    out: dict = {"query": query, "matches": matches[:max_chunks]}
-    if skipped:
-        out["note"] = ("large sibling(s) skipped — supply --path-scope to search them: "
-                       + "; ".join(skipped))
-    return out
-
-
-def render_text(result: dict) -> str:
-    matches = result["matches"]
-    if not matches:
-        return result.get("note", "no matches")
-    lines = ["| source_repo | path | freshness | why |", "|---|---|---|---|"]
-    for m in matches:
-        lines.append(f"| {m['source_repo']} | {m['path']} | {m['freshness']} | {m['match_reason']} |")
-    if result.get("note"):
-        lines += ["", f"> {result['note']}"]
-    return "\n".join(lines)
-
-
-def main(argv: list[str] | None = None) -> int:
-    ap = argparse.ArgumentParser(description="Targeted, read-only cross-repo retrieval (ADR-032 Option A).")
-    ap.add_argument("query", help="What to retrieve (one concept; ≥ 1 term > 2 chars).")
-    ap.add_argument("--path-scope", default=None, help="Glob to scope the search (required for large siblings).")
-    ap.add_argument("--max-chunks", type=int, default=DEFAULT_MAX_CHUNKS)
-    ap.add_argument("--format", choices=("text", "json"), default="text")
-    ap.add_argument("--root", default=".")
-    args = ap.parse_args(argv)
-
-    result = retrieve(Path(args.root).resolve(), args.query, args.path_scope, args.max_chunks)
-    print(json.dumps(result, indent=2) if args.format == "json" else render_text(result))
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/scripts/discovery_stats.py

@@ -1,70 +0,0 @@
-#!/usr/bin/env python3
-"""Pretty-print the ``stats`` block from the committed discovery manifest.
-
-Cheap sanity surface for developers: counts by category, lifecycle, and
-trust level — answers "how many skills are professional vs core?" in
-one terminal line. Reads only the committed manifest; no scan, no
-generation. See ADR-015.
-
-CLI:
-  python scripts/discovery_stats.py [--manifest PATH]
-
-Exit codes:
-  0  printed
-  1  manifest missing or malformed
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from pathlib import Path
-
-ROOT = Path(__file__).resolve().parents[1]
-DEFAULT_MANIFEST = ROOT / "dist" / "discovery" / "discovery-manifest.json"
-
-
-def _fmt_row(label: str, counts: dict[str, int]) -> str:
-    parts = [f"{k}={v}" for k, v in counts.items()]
-    return f"  {label:<14} " + "  ".join(parts)
-
-
-def main(argv: list[str] | None = None) -> int:
-    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    parser.add_argument("--manifest", type=Path, default=DEFAULT_MANIFEST)
-    args = parser.parse_args(argv)
-
-    if not args.manifest.exists():
-        print(
-            f"error: manifest not found at {args.manifest} "
-            "— run `task build-discovery` first.",
-            file=sys.stderr,
-        )
-        return 1
-
-    try:
-        manifest = json.loads(args.manifest.read_text(encoding="utf-8"))
-    except json.JSONDecodeError as exc:
-        print(f"error: invalid JSON: {exc}", file=sys.stderr)
-        return 1
-
-    stats = manifest.get("stats")
-    if not isinstance(stats, dict):
-        print("error: manifest has no `stats` block (regenerate)", file=sys.stderr)
-        return 1
-
-    rel = args.manifest.relative_to(ROOT) if args.manifest.is_absolute() else args.manifest
-    print(f"Discovery stats — {rel}")
-    print(f"  total          {stats.get('total_artefacts', 0)}")
-    print(_fmt_row("by category", stats.get("by_category", {})))
-    print(_fmt_row("by lifecycle", stats.get("by_lifecycle", {})))
-    print(_fmt_row("by trust", stats.get("by_trust_level", {})))
-    if stats.get("unassigned_count"):
-        print(f"  unassigned     {stats['unassigned_count']}")
-    if stats.get("documented_unassigned_count"):
-        print(f"  documented     {stats['documented_unassigned_count']}")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/extract_audit_patterns.py

@@ -1,202 +0,0 @@
-#!/usr/bin/env python3
-"""Mine repeated phase patterns from ``agents/runtime/state/audit/*.jsonl``.
-
-Consumer side of `audit-log-v1` (see
-`docs/contracts/audit-log-v1.md`). Reads append-only JSONL audit
-lines emitted by the `work_engine` phase hook and surfaces patterns
-that repeat across **independent** runs — i.e. distinct `work_id`
-values — so the human reviewer can promote them via the
-`learning-to-rule-or-skill` skill.
-
-Read-only: never mutates the JSONL, never writes outside `--output`.
-
-Pattern shape (one per row):
-
-  {
-    "summary":   "<phase>:<outcome>:<rules_hash>",
-    "phase":     "verify",
-    "outcome":   "success",
-    "rules_applied": ["verify-before-complete", "commit-policy"],
-    "count":     7,                # distinct work_ids
-    "line_ids":  ["01HXY...", ...],
-    "first_seen": "2026-05-01T...",
-    "last_seen":  "2026-05-11T..."
-  }
-
-Repetition gate: a pattern is emitted only when ``count >= 2`` and
-the two contributing lines come from **different** ``work_id`` values
-(independence floor — same gate as the skill's evidence rule).
-
-Usage::
-
-  python3 scripts/extract_audit_patterns.py                  # human table
-  python3 scripts/extract_audit_patterns.py --json           # machine
-  python3 scripts/extract_audit_patterns.py --min-count 3
-  python3 scripts/extract_audit_patterns.py --month 2026-05  # one file
-  python3 scripts/extract_audit_patterns.py --audit-dir <p>  # override
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from collections import defaultdict
-from dataclasses import dataclass, field, asdict
-from pathlib import Path
-from typing import Iterable
-
-ROOT = Path(__file__).resolve().parent.parent
-DEFAULT_AUDIT_DIR = ROOT / "agents" / "runtime" / "state" / "audit"
-SCHEMA_VERSION = 1
-
-
-@dataclass
-class Pattern:
-    summary: str
-    phase: str
-    outcome: str
-    rules_applied: list[str]
-    count: int = 0
-    line_ids: list[str] = field(default_factory=list)
-    work_ids: set[str] = field(default_factory=set)
-    first_seen: str = ""
-    last_seen: str = ""
-
-    def to_dict(self) -> dict:
-        d = asdict(self)
-        d["work_ids"] = sorted(self.work_ids)
-        return d
-
-
-def _iter_lines(audit_dir: Path, month: str | None) -> Iterable[dict]:
-    """Yield parsed JSONL records from the audit directory.
-
-    Silently skips malformed lines (forward-compat per contract § 86).
-    """
-    if not audit_dir.exists():
-        return
-    files = (
-        [audit_dir / f"{month}.jsonl"] if month
-        else sorted(audit_dir.glob("*.jsonl"))
-    )
-    for path in files:
-        if not path.exists():
-            continue
-        with path.open("r", encoding="utf-8") as fh:
-            for raw in fh:
-                raw = raw.strip()
-                if not raw:
-                    continue
-                try:
-                    rec = json.loads(raw)
-                except json.JSONDecodeError:
-                    continue
-                if rec.get("schema_version") != SCHEMA_VERSION:
-                    continue
-                yield rec
-
-
-def _pattern_key(rec: dict) -> tuple[str, str, tuple[str, ...]]:
-    rules = tuple(sorted(rec.get("rules_applied") or []))
-    return (rec.get("phase", ""), rec.get("outcome", ""), rules)
-
-
-def _resolve_supersedes(records: list[dict]) -> list[dict]:
-    """Apply supersede chains: drop records whose id is superseded."""
-    superseded: set[str] = set()
-    for rec in records:
-        if rec.get("type") == "supersede" and rec.get("supersedes"):
-            superseded.add(rec["supersedes"])
-    return [r for r in records if r.get("id") not in superseded]
-
-
-def mine(audit_dir: Path, month: str | None, min_count: int) -> list[dict]:
-    """Group records into patterns; enforce independence floor."""
-    records = _resolve_supersedes(list(_iter_lines(audit_dir, month)))
-    groups: dict[tuple, Pattern] = {}
-    for rec in records:
-        if rec.get("type") not in (None, "phase"):
-            continue
-        key = _pattern_key(rec)
-        if key not in groups:
-            phase, outcome, rules = key
-            rules_hash = "+".join(rules) or "<none>"
-            groups[key] = Pattern(
-                summary=f"{phase}:{outcome}:{rules_hash}",
-                phase=phase,
-                outcome=outcome,
-                rules_applied=list(rules),
-            )
-        pat = groups[key]
-        ts = rec.get("ts", "")
-        wid = rec.get("work_id", "")
-        if wid:
-            pat.work_ids.add(wid)
-        line_id = rec.get("id", "")
-        if line_id:
-            pat.line_ids.append(line_id)
-        pat.count = len(pat.work_ids)
-        if not pat.first_seen or ts < pat.first_seen:
-            pat.first_seen = ts
-        if not pat.last_seen or ts > pat.last_seen:
-            pat.last_seen = ts
-    out = [p.to_dict() for p in groups.values() if p.count >= min_count]
-    out.sort(key=lambda d: (-d["count"], d["summary"]))
-    return out
-
-
-def _render_table(patterns: list[dict]) -> str:
-    if not patterns:
-        return "(no patterns at or above the min-count threshold)"
-    lines = [
-        f"{'count':>5}  {'phase':<10} {'outcome':<8} {'rules':<40} summary",
-        f"{'-' * 5}  {'-' * 10} {'-' * 8} {'-' * 40} -------",
-    ]
-    for p in patterns:
-        rules = ",".join(p["rules_applied"]) or "<none>"
-        if len(rules) > 38:
-            rules = rules[:35] + "..."
-        lines.append(
-            f"{p['count']:>5}  {p['phase']:<10} {p['outcome']:<8} "
-            f"{rules:<40} {p['summary']}"
-        )
-    return "\n".join(lines)
-
-
-def main(argv: list[str] | None = None) -> int:
-    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    ap.add_argument(
-        "--audit-dir", type=Path, default=DEFAULT_AUDIT_DIR,
-        help="Override audit-log directory (default: %(default)s).",
-    )
-    ap.add_argument(
-        "--month", help="Single YYYY-MM file instead of all months.",
-    )
-    ap.add_argument(
-        "--min-count", type=int, default=2,
-        help="Minimum distinct work_ids required (default: 2).",
-    )
-    ap.add_argument(
-        "--json", action="store_true", help="Emit machine-readable JSON.",
-    )
-    args = ap.parse_args(argv)
-
-    if args.min_count < 2:
-        print(
-            "❌  --min-count must be >= 2 (independence floor per "
-            "audit-log-v1 § Privacy floor).",
-            file=sys.stderr,
-        )
-        return 2
-
-    patterns = mine(args.audit_dir, args.month, args.min_count)
-    if args.json:
-        json.dump(patterns, sys.stdout, indent=2, sort_keys=True)
-        sys.stdout.write("\n")
-    else:
-        print(_render_table(patterns))
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/first_run_gate_hook.py

@@ -1,178 +0,0 @@
-#!/usr/bin/env python3
-"""First-run gate — surface the marketplace-install-but-unscaffolded shape.
-
-Phase 2 of `road-to-hooks-actually-fire-in-consumers`.
-
-When a consumer enables the plugin via `/plugin install` but never
-runs `agent-config init` (or `hooks:install --claude --regen`), the
-hooks declared in `hooks/hooks.json` fire but cannot do anything —
-their commands resolve through an `$CLAUDE_PROJECT_DIR/agent-config`
-that does not exist, or call a regenerator script that lives only in
-package source-checkouts. The user has no way to discover this.
-
-This hook runs on `session_start` only. It detects the failure shape
-and surfaces it two ways (Council R3 HIGH — stderr alone is invisible
-to the average user):
-
-1. One stderr line — Claude shows session-start hook stderr in its
-   lifecycle log; power users will see it there.
-2. A file at `$CLAUDE_PROJECT_DIR/.augment/.first-run-action-needed.md`
-   that the user discovers on the next `ls` of their tree.
-
-Setup-complete detector (Council R3 MEDIUM — prevents banner spam):
-the hook exits early without writing if the checklist passes
-(`./agent-config` symlink executable + `.augment/scripts/update_roadmap_progress.py`
-exists). Once the user runs `hooks:install --claude --regen`, the
-file written by a prior run gets cleaned up the next time this hook
-runs successfully.
-
-Contract: never blocks. Returns 0 on every path.
-"""
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import sys
-from pathlib import Path
-
-
-PLUGIN_ID = "agent-config@event4u-agent-config"
-ACTION_NEEDED_FILE = ".augment/.first-run-action-needed.md"
-
-REGENERATOR_PATHS = (
-    ".augment/scripts/update_roadmap_progress.py",
-    ".agent-src/scripts/update_roadmap_progress.py",
-    ".agent-src.uncondensed/scripts/update_roadmap_progress.py",
-)
-
-ACTION_NEEDED_BODY = """# First-run action needed — `agent-config` plugin
-
-You enabled the `agent-config@event4u-agent-config` plugin via
-`/plugin install`, but your project is missing the prerequisites
-the plugin's hooks need to actually fire:
-
-- `./agent-config` symlink at the repo root (needed by every hook).
-- `.augment/scripts/update_roadmap_progress.py` (needed by the
-  roadmap-progress hook to regenerate the dashboard).
-
-Fix in one command:
-
-```bash
-./agent-config hooks:install --claude --regen
-```
-
-Or run the full installer:
-
-```bash
-./agent-config init
-```
-
-After either command, this file deletes itself on the next session
-start. If you don't want the plugin's hooks, disable it via
-`/plugin disable agent-config@event4u-agent-config` and delete
-this file manually.
-"""
-
-
-def _plugin_enabled(consumer_root: Path) -> bool:
-    """Returns True iff `.claude/settings.json` has the plugin id under
-    `enabledPlugins` with a truthy value."""
-    settings = consumer_root / ".claude" / "settings.json"
-    if not settings.is_file():
-        return False
-    try:
-        data = json.loads(settings.read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return False
-    if not isinstance(data, dict):
-        return False
-    enabled = data.get("enabledPlugins")
-    if not isinstance(enabled, dict):
-        return False
-    return bool(enabled.get(PLUGIN_ID))
-
-
-def _agent_config_executable(consumer_root: Path) -> bool:
-    """`./agent-config` exists AND is executable (whether file or symlink)."""
-    p = consumer_root / "agent-config"
-    if not p.exists():
-        return False
-    return os.access(p, os.X_OK)
-
-
-def _regenerator_present(consumer_root: Path) -> bool:
-    return any((consumer_root / rel).is_file() for rel in REGENERATOR_PATHS)
-
-
-def _setup_complete(consumer_root: Path) -> bool:
-    return _agent_config_executable(consumer_root) and _regenerator_present(consumer_root)
-
-
-def _write_action_file(consumer_root: Path) -> bool:
-    """Best-effort write. Returns True on success."""
-    target = consumer_root / ACTION_NEEDED_FILE
-    try:
-        target.parent.mkdir(parents=True, exist_ok=True)
-        target.write_text(ACTION_NEEDED_BODY, encoding="utf-8")
-        return True
-    except OSError as exc:
-        sys.stderr.write(
-            f"first-run-gate: could not write {target}: {exc}\n"
-        )
-        return False
-
-
-def _cleanup_action_file(consumer_root: Path) -> None:
-    """Remove the action-needed file once setup is complete. Best-effort."""
-    target = consumer_root / ACTION_NEEDED_FILE
-    if target.exists():
-        try:
-            target.unlink()
-        except OSError:
-            pass
-
-
-def run(consumer_root: Path) -> int:
-    if os.environ.get("AGENT_CONFIG_REPLAY") == "1":
-        # Fixture-driven replay must not mutate state.
-        return 0
-    if not _plugin_enabled(consumer_root):
-        # Plugin not enabled — nothing to gate on. Silent.
-        return 0
-    if _setup_complete(consumer_root):
-        # Setup checklist passes — clean up any stale action-needed file
-        # left by a prior run, then exit silently.
-        _cleanup_action_file(consumer_root)
-        return 0
-
-    # Failure shape detected. Two visible surfaces:
-    sys.stderr.write(
-        "first-run-gate: agent-config plugin is enabled but "
-        "scaffolding is missing — run `./agent-config hooks:install "
-        "--claude --regen` (details written to "
-        f"{ACTION_NEEDED_FILE})\n"
-    )
-    _write_action_file(consumer_root)
-    return 0
-
-
-def parse_args(argv: list[str]) -> argparse.Namespace:
-    p = argparse.ArgumentParser(description=__doc__.splitlines()[0])
-    p.add_argument("--platform", default="generic")
-    return p.parse_args(argv)
-
-
-def main(argv: list[str] | None = None) -> int:
-    _ = parse_args(argv if argv is not None else sys.argv[1:])
-    # Drain stdin envelope so the dispatcher pipe contract holds.
-    try:
-        sys.stdin.read()
-    except OSError:
-        pass
-    consumer_root = Path(os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd())
-    return run(consumer_root)
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())