@event4u/agent-config 1.39.0 → 1.40.0

package/scripts/extract_audit_patterns.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""Mine repeated phase patterns from ``agents/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" / "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/install

@@ -15,13 +15,30 @@
 #   --source <dir>    Package source directory (default: auto-detect)
 #   --target <dir>    Target project root (default: cwd)
 #   --profile <name>  Cost profile for bridges (minimal|balanced|full)
+#   --tools <list>    Comma-separated tool IDs to install (default: all).
+#                     Valid: claude-code,claude-desktop,cursor,windsurf,
+#                            cline,gemini-cli,copilot,augment,aider,codex,all
+#   --list-tools      Print supported tool IDs with descriptions, then exit
+#   --yes, -y         Non-interactive mode: do not prompt (default for non-TTY)
 #   --force           Overwrite existing bridge files
 #   --dry-run         Show what payload sync would do (does not run bridges)
 #   --verbose         Detailed payload sync output
 #   --quiet           Suppress non-error output
 #   --skip-sync       Skip payload sync (install.sh)
 #   --skip-bridges    Skip bridge files (install.py)
+#   --global          Phase-3: ship kernel rules + curated skills to user-scope
+#                     dirs (~/.claude/, ~/.cursor/, ~/.codeium/windsurf/,
+#                     ~/.config/agent-config/) so the agent has them in every
+#                     project. Pair with --tools to scope surfaces; default = all.
+#   --uninstall       With --global: remove the event4u/ namespace dir from each
+#                     enabled surface (no effect on user-added files).
 #   --help, -h        Show this help
+#
+# Examples:
+#   bash scripts/install                                # everything (default)
+#   bash scripts/install --tools=claude-code,cursor     # only those two
+#   bash scripts/install --tools=cursor --yes           # CI-friendly
+#   bash scripts/install --list-tools                   # show catalog
 
 set -uo pipefail
 
@@ -32,19 +49,67 @@ INSTALL_PY="$SCRIPT_DIR/install.py"
 SOURCE_DIR=""
 TARGET_DIR=""
 PROFILE=""
+TOOLS=""
+TOOLS_EXPLICIT=false
+YES=false
 FORCE=false
 DRY_RUN=false
 VERBOSE=false
 QUIET=false
 SKIP_SYNC=false
 SKIP_BRIDGES=false
+LIST_TOOLS=false
+GLOBAL_INSTALL=false
+UNINSTALL=false
+
+# Single source of truth for valid tool IDs (also referenced by install.sh / install.py).
+VALID_TOOLS="claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex all"
 
 show_help() {
-    sed -n '3,25p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+    sed -n '3,35p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+list_tools() {
+    cat <<'EOF'
+Supported --tools IDs (default: all):
+
+  claude-code      .claude/rules, .claude/skills, .claude/commands, .claude/settings.json
+  claude-desktop   ~/Library/Application Support/Claude/ (global, see Phase 4 docs)
+  cursor           .cursor/rules, .cursor/commands (legacy .cursorrules also written)
+  windsurf         .windsurf/rules, .windsurf/workflows (legacy .windsurfrules also written)
+  cline            .clinerules/ symlinks
+  gemini-cli       GEMINI.md, .gemini/settings.json
+  copilot          .github/copilot-instructions.md, .vscode/settings.json
+  augment          .augment/ payload + settings (substrate — recommended for every install)
+  aider            AGENTS.md (Linux Foundation cross-tool contract; always written)
+  codex            AGENTS.md (same as aider — no extra action)
+  all              every ID above (the default; backward-compatible)
+
+Examples:
+  --tools=claude-code,cursor       project-local install for those two surfaces
+  --tools=all                      equivalent to omitting the flag
+EOF
 }
 
 err() { echo "  ❌  $*" >&2; }
 
+# Validate a comma-separated tool list against $VALID_TOOLS. Empty input is
+# rejected so a stray --tools= does not silently behave like --tools=all.
+validate_tools() {
+    local raw="$1"
+    [[ -z "$raw" ]] && { err "--tools requires a non-empty value (use --list-tools to see options)"; return 1; }
+    local IFS=','
+    local item
+    for item in $raw; do
+        [[ -z "$item" ]] && { err "--tools contains an empty entry"; return 1; }
+        if [[ " $VALID_TOOLS " != *" $item "* ]]; then
+            err "Unknown tool ID: $item (run --list-tools for the catalog)"
+            return 1
+        fi
+    done
+    return 0
+}
+
 while [[ $# -gt 0 ]]; do
     case "$1" in
         --source)        SOURCE_DIR="$2"; shift 2 ;;
@@ -53,17 +118,84 @@ while [[ $# -gt 0 ]]; do
         --target=*)      TARGET_DIR="${1#*=}"; shift ;;
         --profile)       PROFILE="$2"; shift 2 ;;
         --profile=*)     PROFILE="${1#*=}"; shift ;;
+        --tools)         TOOLS="$2"; TOOLS_EXPLICIT=true; shift 2 ;;
+        --tools=*)       TOOLS="${1#*=}"; TOOLS_EXPLICIT=true; shift ;;
+        --list-tools)    LIST_TOOLS=true; shift ;;
+        --yes|-y)        YES=true; shift ;;
         --force)         FORCE=true; shift ;;
         --dry-run)       DRY_RUN=true; shift ;;
         --verbose)       VERBOSE=true; shift ;;
         --quiet)         QUIET=true; shift ;;
         --skip-sync)     SKIP_SYNC=true; shift ;;
         --skip-bridges)  SKIP_BRIDGES=true; shift ;;
+        --global)        GLOBAL_INSTALL=true; shift ;;
+        --uninstall)     UNINSTALL=true; shift ;;
         --help|-h)       show_help; exit 0 ;;
         *)               err "Unknown argument: $1"; show_help >&2; exit 1 ;;
     esac
 done
 
+if $LIST_TOOLS; then
+    list_tools
+    exit 0
+fi
+
+# Interactive --tools picker (S9). Fires only when:
+#   - --tools was not explicitly passed
+#   - --yes / -y was not passed (CI / non-interactive opt-out)
+#   - stdin AND stdout are both TTYs (so we're not in a pipe / curl|bash flow)
+#   - --dry-run, --quiet, --skip-sync, --skip-bridges did not opt out of UX
+# Otherwise we fall through to the backward-compatible "all" default.
+prompt_tools() {
+    local choice picked tool i=0
+    local -a menu=(claude-code claude-desktop cursor windsurf cline gemini-cli copilot augment aider codex)
+    echo ""
+    echo "  📦 Pick the tools to install (comma-separated numbers, blank = all):"
+    for tool in "${menu[@]}"; do
+        i=$((i+1))
+        printf "    %2d) %s\n" "$i" "$tool"
+    done
+    echo "    a)  all (default)"
+    echo ""
+    printf "  Selection: "
+    IFS= read -r choice || choice=""
+    choice="${choice// /}"
+    if [[ -z "$choice" || "$choice" == "a" || "$choice" == "all" ]]; then
+        TOOLS="all"; return
+    fi
+    picked=""
+    local IFS=','
+    for n in $choice; do
+        if ! [[ "$n" =~ ^[0-9]+$ ]] || (( n < 1 || n > ${#menu[@]} )); then
+            err "Invalid selection: $n (expected 1-${#menu[@]} or 'a')"; exit 1
+        fi
+        picked+="${menu[$((n-1))]},"
+    done
+    TOOLS="${picked%,}"
+    echo "  ✅  Selected: $TOOLS"
+}
+
+if ! $TOOLS_EXPLICIT && ! $YES && ! $QUIET && ! $LIST_TOOLS && ! $GLOBAL_INSTALL && [[ -t 0 && -t 1 ]]; then
+    prompt_tools
+    TOOLS_EXPLICIT=true
+fi
+
+if $UNINSTALL && ! $GLOBAL_INSTALL; then
+    err "--uninstall is only valid combined with --global"
+    exit 1
+fi
+
+# Default = "all": backward compatible with pre-Phase-1 invocations. An
+# explicit --tools= (empty value) is rejected by validate_tools — only an
+# absent flag falls through to "all".
+if ! $TOOLS_EXPLICIT && [[ -z "$TOOLS" ]]; then
+    TOOLS="all"
+fi
+
+if ! validate_tools "$TOOLS"; then
+    exit 1
+fi
+
 # Auto-detect source: directory above this script
 if [[ -z "$SOURCE_DIR" ]]; then
     SOURCE_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -103,6 +235,7 @@ run_sync() {
     $DRY_RUN && args+=(--dry-run)
     $VERBOSE && args+=(--verbose)
     $QUIET   && args+=(--quiet)
+    args+=(--tools="$TOOLS")
     bash "$INSTALL_SH" "${args[@]}"
 }
 
@@ -123,10 +256,32 @@ run_bridges() {
     [[ -n "$PROFILE" ]] && args+=(--profile="$PROFILE")
     $FORCE && args+=(--force)
     $QUIET && args+=(--quiet)
+    args+=(--tools="$TOOLS")
     "$python_bin" "$INSTALL_PY" "${args[@]}"
 }
 
 RC=0
+
+# --global: dedicated user-scope path. Skips the project-bridge sync entirely
+# and forwards to install.py --global (Phase 3 / S13). --uninstall pairs with
+# --global to wipe the event4u/ namespace dir under each surface.
+if $GLOBAL_INSTALL; then
+    if ! python_bin="$(find_python)"; then
+        err "Python 3 not found — required for --global install"
+        exit 1
+    fi
+    if [[ ! -f "$INSTALL_PY" ]]; then
+        err "Missing $INSTALL_PY"
+        exit 1
+    fi
+    args=(--package "$SOURCE_DIR" --global --tools="$TOOLS")
+    $FORCE     && args+=(--force)
+    $QUIET     && args+=(--quiet)
+    $UNINSTALL && args+=(--uninstall)
+    "$python_bin" "$INSTALL_PY" "${args[@]}"
+    exit $?
+fi
+
 if ! $SKIP_SYNC; then
     if [[ ! -f "$INSTALL_SH" ]]; then
         err "Missing $INSTALL_SH"