@event4u/agent-config 1.38.0 → 1.40.0

package/scripts/_lib/agent_settings.py

@@ -0,0 +1,168 @@
+"""Centralized loader for ``.agent-settings.yml`` with user-global fallback.
+
+Phase 1 of road-to-portable-dev-preferences. Single source of truth for
+how scripts read agent settings — replaces ~15 ad-hoc loaders in P3.
+
+Resolution order (project wins, user-global fills gaps for whitelisted
+keys only):
+
+  1. Project ``./.agent-settings.yml``                  (full file, all keys)
+  2. ``~/.config/agent-config/agent-settings.yml``      (whitelist only)
+  3. Built-in defaults                                  (currently empty)
+
+Whitelisted keys (``MERGEABLE_KEYS``) are exact dotted paths. A
+non-whitelisted key in the user-global file is silently ignored — the
+``verbose=True`` flag surfaces ignored paths via ``logging.info`` for
+debugging.
+
+Contract — pure, read-only, tolerant:
+
+* Lazy PyYAML import; no yaml installed → defaults returned.
+* Missing project file → user-global + defaults.
+* Missing user-global file → project + defaults.
+* Both missing → defaults.
+* Malformed YAML / unreadable file → defaults, logged at WARNING.
+* No file is ever created or written by this module.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_PROJECT_FILE = ".agent-settings.yml"
+DEFAULT_USER_GLOBAL_FILE = (
+    Path.home() / ".config" / "agent-config" / "agent-settings.yml"
+)
+
+#: Exact dotted paths allowed to cascade from user-global into the merged
+#: settings. Anything not listed here is silently ignored when present in
+#: the user-global file. Adding a key requires an ADR — see
+#: ``agents/roadmaps/road-to-portable-dev-preferences.md``.
+MERGEABLE_KEYS: tuple[str, ...] = (
+    "name",
+    "ide",
+    "cost_profile",
+    "personal.bot_icon",
+    "personal.autonomy",
+    "caveman.speak_scope",
+)
+
+_DEFAULTS: dict[str, Any] = {}
+
+
+def load_agent_settings(
+    project_path: Path | str | None = None,
+    user_global_path: Path | str | None = None,
+    verbose: bool = False,
+) -> dict[str, Any]:
+    """Return the merged settings dict.
+
+    ``project_path`` defaults to ``./.agent-settings.yml`` (CWD-relative).
+    ``user_global_path`` defaults to
+    ``~/.config/agent-config/agent-settings.yml``. Both arguments accept
+    ``Path`` or ``str``. Pass ``verbose=True`` to log keys present in
+    user-global that are not on the whitelist.
+    """
+    project = _read_yaml(
+        Path(project_path) if project_path else Path(DEFAULT_PROJECT_FILE),
+    ) or {}
+    user_global_raw = _read_yaml(
+        Path(user_global_path) if user_global_path else DEFAULT_USER_GLOBAL_FILE,
+    ) or {}
+
+    user_global_filtered, ignored = _filter_whitelist(
+        user_global_raw, MERGEABLE_KEYS,
+    )
+    if verbose and ignored:
+        logger.info(
+            "agent_settings: ignored non-whitelisted user-global keys: %s",
+            sorted(ignored),
+        )
+
+    merged: dict[str, Any] = _deep_copy_defaults(_DEFAULTS)
+    _deep_merge(merged, user_global_filtered)
+    _deep_merge(merged, project)
+    return merged
+
+
+def _read_yaml(path: Path) -> dict[str, Any] | None:
+    """Best-effort YAML read; never raises. Returns ``None`` on any failure."""
+    if not path.is_file():
+        return None
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError:
+        return None
+    try:
+        with path.open(encoding="utf-8") as fh:
+            data = yaml.safe_load(fh) or {}
+    except (OSError, yaml.YAMLError):
+        logger.warning("agent_settings: unreadable or malformed YAML at %s", path)
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _filter_whitelist(
+    raw: dict[str, Any], allowed: tuple[str, ...],
+) -> tuple[dict[str, Any], list[str]]:
+    """Return ``(filtered_dict, ignored_paths)`` from a user-global blob."""
+    filtered: dict[str, Any] = {}
+    for dotted in allowed:
+        value = _get_dotted(raw, dotted)
+        if value is not None:
+            _set_dotted(filtered, dotted, value)
+    ignored = [p for p in _leaf_paths(raw) if p not in allowed]
+    return filtered, ignored
+
+
+def _get_dotted(data: dict[str, Any], dotted: str) -> Any:
+    cursor: Any = data
+    for part in dotted.split("."):
+        if not isinstance(cursor, dict) or part not in cursor:
+            return None
+        cursor = cursor[part]
+    return cursor
+
+
+def _set_dotted(target: dict[str, Any], dotted: str, value: Any) -> None:
+    parts = dotted.split(".")
+    cursor = target
+    for part in parts[:-1]:
+        nxt = cursor.setdefault(part, {})
+        if not isinstance(nxt, dict):
+            nxt = {}
+            cursor[part] = nxt
+        cursor = nxt
+    cursor[parts[-1]] = value
+
+
+def _leaf_paths(data: dict[str, Any], prefix: str = "") -> list[str]:
+    paths: list[str] = []
+    for key, value in data.items():
+        path = f"{prefix}.{key}" if prefix else key
+        if isinstance(value, dict) and value:
+            paths.extend(_leaf_paths(value, path))
+        else:
+            paths.append(path)
+    return paths
+
+
+def _deep_merge(dst: dict[str, Any], src: dict[str, Any]) -> None:
+    """Merge ``src`` into ``dst`` in-place; nested dicts are merged recursively."""
+    for key, value in src.items():
+        if (
+            isinstance(value, dict)
+            and isinstance(dst.get(key), dict)
+        ):
+            _deep_merge(dst[key], value)
+        else:
+            dst[key] = value
+
+
+def _deep_copy_defaults(src: dict[str, Any]) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    _deep_merge(out, src)
+    return out

package/scripts/compress.py

@@ -26,6 +26,8 @@ import shutil
 import sys
 from pathlib import Path
 
+import yaml
+
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from _lib.script_output import info, success, flush_summary, resolve_level  # noqa: E402
 
@@ -503,6 +505,149 @@ def generate_windsurfrules() -> int:
     return len(rules)
 
 
+# ── Modern editor formats (road-to-simplicity-and-everywhere Phase 5) ─
+# Cursor `.cursor/rules/*.mdc` (frontmatter: description, globs,
+# alwaysApply) and Windsurf `.windsurf/rules/*.md` (frontmatter:
+# trigger, description, globs) are the formats current editors prefer.
+# Legacy `.windsurfrules` aggregate stays for users who prefer it.
+
+CURSOR_RULES_MDC_DIR = PROJECT_ROOT / ".cursor" / "rules"
+WINDSURF_RULES_DIR = PROJECT_ROOT / ".windsurf" / "rules"
+WINDSURF_WORKFLOWS_DIR = PROJECT_ROOT / ".windsurf" / "workflows"
+CURSOR_COMMANDS_DIR = PROJECT_ROOT / ".cursor" / "commands"
+
+
+def _parse_frontmatter(content: str) -> tuple[dict, str]:
+    """Split a `---`-delimited YAML frontmatter from the body."""
+    if not content.startswith("---"):
+        return {}, content
+    end = content.find("\n---", 3)
+    if end == -1:
+        return {}, content
+    raw = content[3:end].strip()
+    body = content[end + 4:].lstrip("\n")
+    try:
+        meta = yaml.safe_load(raw) or {}
+    except yaml.YAMLError:
+        meta = {}
+    return meta if isinstance(meta, dict) else {}, body
+
+
+def _emit_cursor_mdc(source: Path, target: Path) -> None:
+    """Write a Cursor `.mdc` file with Cursor-shaped frontmatter."""
+    meta, body = _parse_frontmatter(source.read_text())
+    description = (meta.get("description") or "").replace("\n", " ").strip()
+    always_apply = bool(meta.get("alwaysApply") or meta.get("type") == "always")
+    lines = [
+        "---",
+        f"description: {description}",
+        "globs: ",
+        f"alwaysApply: {'true' if always_apply else 'false'}",
+        "---",
+        "",
+        body.rstrip() + "\n",
+    ]
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text("\n".join(lines))
+
+
+def _emit_windsurf_rule(source: Path, target: Path) -> None:
+    """Write a Windsurf rule with Wave-8 frontmatter (trigger/description/globs)."""
+    meta, body = _parse_frontmatter(source.read_text())
+    description = (meta.get("description") or "").replace("\n", " ").strip()
+    always_apply = bool(meta.get("alwaysApply") or meta.get("type") == "always")
+    trigger = "always_on" if always_apply else "model_decision"
+    lines = [
+        "---",
+        f"trigger: {trigger}",
+        f"description: {description}",
+        "globs: ",
+        "---",
+        "",
+        body.rstrip() + "\n",
+    ]
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text("\n".join(lines))
+
+
+def _clean_modern_dir(target_dir: Path, valid_names: set[str]) -> None:
+    """Drop files in `target_dir` whose names are not in `valid_names`."""
+    if not target_dir.exists():
+        return
+    for item in target_dir.iterdir():
+        if item.name == "README.md":
+            continue
+        if item.name not in valid_names:
+            if item.is_dir() and not item.is_symlink():
+                shutil.rmtree(item)
+            else:
+                item.unlink()
+
+
+def generate_cursor_mdc_rules() -> int:
+    """Emit `.cursor/rules/*.mdc` per source rule (alongside legacy `.md` symlinks)."""
+    rules = sorted(RULES_SOURCE.glob("*.md"))
+    valid = {f"{r.stem}.mdc" for r in rules}
+    _clean_modern_dir(CURSOR_RULES_MDC_DIR, valid | {r.name for r in rules})
+    for rule in rules:
+        _emit_cursor_mdc(rule, CURSOR_RULES_MDC_DIR / f"{rule.stem}.mdc")
+    info(f"  ✅  Wrote {len(rules)} `.cursor/rules/*.mdc` files")
+    return len(rules)
+
+
+def generate_windsurf_modern_rules() -> int:
+    """Emit `.windsurf/rules/*.md` per source rule (Wave-8 frontmatter)."""
+    rules = sorted(RULES_SOURCE.glob("*.md"))
+    valid = {r.name for r in rules}
+    _clean_modern_dir(WINDSURF_RULES_DIR, valid)
+    for rule in rules:
+        _emit_windsurf_rule(rule, WINDSURF_RULES_DIR / rule.name)
+    info(f"  ✅  Wrote {len(rules)} `.windsurf/rules/*.md` files")
+    return len(rules)
+
+
+def generate_cursor_commands() -> int:
+    """Symlink `.cursor/commands/<slug>.md` per source command."""
+    if not COMMANDS_SOURCE.exists():
+        return 0
+    cmds = list(_iter_commands())
+    valid = {f"{slug}.md" for _, slug in cmds}
+    _clean_modern_dir(CURSOR_COMMANDS_DIR, valid)
+    CURSOR_COMMANDS_DIR.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for source_file, slug in cmds:
+        link = CURSOR_COMMANDS_DIR / f"{slug}.md"
+        if link.exists() or link.is_symlink():
+            link.unlink()
+        rel = Path("../../.agent-src/commands") / source_file.relative_to(COMMANDS_SOURCE)
+        link.symlink_to(rel)
+        count += 1
+    info(f"  ✅  Linked {count} `.cursor/commands/*.md` files")
+    return count
+
+
+def generate_windsurf_workflows() -> int:
+    """Symlink `.windsurf/workflows/<slug>.md` per source command."""
+    if not COMMANDS_SOURCE.exists():
+        return 0
+    cmds = list(_iter_commands())
+    valid = {f"{slug}.md" for _, slug in cmds}
+    _clean_modern_dir(WINDSURF_WORKFLOWS_DIR, valid)
+    WINDSURF_WORKFLOWS_DIR.mkdir(parents=True, exist_ok=True)
+    count = 0
+    for source_file, slug in cmds:
+        link = WINDSURF_WORKFLOWS_DIR / f"{slug}.md"
+        if link.exists() or link.is_symlink():
+            link.unlink()
+        rel = Path("../../.agent-src/commands") / source_file.relative_to(COMMANDS_SOURCE)
+        link.symlink_to(rel)
+        count += 1
+    info(f"  ✅  Linked {count} `.windsurf/workflows/*.md` files")
+    return count
+
+
+
+
 def generate_gemini_md() -> None:
     """Create GEMINI.md symlink to AGENTS.md."""
     link = PROJECT_ROOT / "GEMINI.md"
@@ -695,9 +840,15 @@ def generate_tools() -> None:
     skills = generate_claude_skills()
     commands = generate_claude_commands()
     personas = generate_persona_symlinks()
+    cursor_mdc = generate_cursor_mdc_rules()
+    windsurf_modern = generate_windsurf_modern_rules()
+    cursor_cmds = generate_cursor_commands()
+    windsurf_wf = generate_windsurf_workflows()
     summary = (
         f"✅  generate-tools — rules={rules} skills={skills} "
-        f"commands={commands} personas={personas}"
+        f"commands={commands} personas={personas} "
+        f"cursor_mdc={cursor_mdc} windsurf_rules={windsurf_modern} "
+        f"cursor_commands={cursor_cmds} windsurf_workflows={windsurf_wf}"
     )
     if resolve_level() == "verbose":
         print(f"\n{summary}")
@@ -806,6 +957,7 @@ def clean_tools() -> None:
         PROJECT_ROOT / ".claude",
         PROJECT_ROOT / ".cursor",
         PROJECT_ROOT / ".clinerules",
+        PROJECT_ROOT / ".windsurf",
         PROJECT_ROOT / ".windsurfrules",
         PROJECT_ROOT / "GEMINI.md",
     ]

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())