@event4u/agent-config 6.1.0 → 7.0.0

package/src/scripts/command_suggester/sanitize.py

@@ -1,113 +0,0 @@
-"""Sanitize matcher input to prevent self-echo and quoted-code triggering.
-
-The suggestion engine scores against the user's raw message and the
-last 2 turns of context. Two adversarial inputs would otherwise
-re-trigger the engine on its own output or on user-pasted code:
-
-* **Self-echo** — the previous turn's suggestion block (`> 1. /commit
-  — …`) is part of the conversation context. Scoring against it
-  re-surfaces the same commands turn after turn.
-* **Quoted code** — user-pasted snippets that mention a command
-  (`` `/implement-ticket` ``, fenced ``` ```bash\ngit commit``` ```)
-  read like real intent signals to the substring matcher.
-
-Both patterns are stripped here before the matcher sees them. The
-sanitiser is **conservative**: only well-formed Markdown fences,
-inline-code spans, and the engine's own suggestion-line shape are
-removed. Plain prose is untouched so legitimate intent ("commit my
-changes please") still scores.
-"""
-from __future__ import annotations
-
-import re
-from typing import Iterable
-
-# Triple-backtick fence — handles language hints (```bash …```) and
-# unhinted blocks alike. Non-greedy so adjacent fences don't merge.
-_CODE_FENCE_RE = re.compile(r"```.*?```", re.DOTALL)
-# Inline code span. Excludes empty `` `` `` and respects single-line scope.
-_INLINE_CODE_RE = re.compile(r"`[^`\n]+`")
-# Suggestion-block line shape from `render.py`:
-#   > 1. /implement-ticket — drive ticket end-to-end…
-#   > 2. /refine-ticket — tighten the AC…
-# Numbered-options lines starting with `>` and a `/command` token.
-_SUGGESTION_LINE_RE = re.compile(
-    r"^\s*>\s*\d+\.\s*/[A-Za-z][A-Za-z0-9_-]*\b.*$",
-    re.MULTILINE,
-)
-# As-is escape hatch line — recognisable suffix from render.py.
-_AS_IS_LINE_RE = re.compile(
-    r"^\s*>\s*\d+\.\s*Just run the prompt as-is.*$",
-    re.MULTILINE | re.IGNORECASE,
-)
-# Header line emitted by render.py.
-_SUGGESTION_HEADER_RE = re.compile(
-    r"^\s*>\s*💡\s*Your request matches a command.*$",
-    re.MULTILINE,
-)
-# Recommendation line right after the block.
-_RECOMMENDATION_LINE_RE = re.compile(
-    r"^\s*\*\*Recommendation:\s*\d+\b.*$",
-    re.MULTILINE,
-)
-
-
-def strip_code_blocks(text: str) -> str:
-    """Remove fenced and inline code spans.
-
-    Fenced blocks first (greedy across newlines, non-greedy across
-    fences), then inline backticks. Plain text outside code is left
-    bit-identical.
-    """
-    if not text:
-        return text
-    out = _CODE_FENCE_RE.sub(" ", text)
-    out = _INLINE_CODE_RE.sub(" ", out)
-    return out
-
-
-def strip_suggestion_echo(text: str) -> str:
-    """Remove lines that look like the engine's own previous output.
-
-    Matches the four shapes `render.py` emits:
-
-    * the `> 💡 …` header
-    * `> N. /command — …` numbered options
-    * the `> N. Just run the prompt as-is …` escape hatch
-    * the `**Recommendation: N — …` follow-up line
-
-    Anything else (including user-authored quotes that happen to
-    mention a command) is preserved — only the engine's distinctive
-    block shape is filtered.
-    """
-    if not text:
-        return text
-    out = _SUGGESTION_HEADER_RE.sub("", text)
-    out = _SUGGESTION_LINE_RE.sub("", out)
-    out = _AS_IS_LINE_RE.sub("", out)
-    out = _RECOMMENDATION_LINE_RE.sub("", out)
-    return out
-
-
-def sanitize_message(message: str) -> str:
-    """Apply both filters to a single user message.
-
-    Order matters: strip code first (a `/command` inside a fence is
-    code, not an echo), then strip echoes from what remains.
-    """
-    return strip_suggestion_echo(strip_code_blocks(message))
-
-
-def sanitize_context(context_lines: Iterable[str]) -> list[str]:
-    """Apply `sanitize_message` to each line of recent-turn context.
-
-    Returns a new list — the caller's list is untouched. Empty strings
-    after sanitising are kept out of the result so they don't dilute
-    token-overlap scoring.
-    """
-    out: list[str] = []
-    for line in context_lines:
-        cleaned = sanitize_message(line)
-        if cleaned and cleaned.strip():
-            out.append(cleaned)
-    return out

package/src/scripts/command_suggester/settings.py

@@ -1,127 +0,0 @@
-"""Read `commands.suggestion.*` from `.agent-settings.yml` into `Settings`.
-
-Mirror of the chat-history pattern (`scripts/chat_history.py`):
-
-* Lazy PyYAML import — the engine works without yaml installed when no
-  settings file is present (test fixtures, cloud bundles).
-* Default-permissive: a missing file or missing section returns
-  `Settings()` defaults (suggestion layer enabled). Only an explicit
-  `enabled: false` flips the master switch off.
-* Malformed YAML / unreadable file → defaults; the suggester degrades
-  silently rather than crashing the turn.
-* Type-coerces with bounded fallbacks (floors clamped 0.0-1.0, ints
-  non-negative, blocklist forced to a tuple of strings).
-"""
-from __future__ import annotations
-
-from pathlib import Path
-from typing import Any, Iterable
-
-from .types import Settings
-
-DEFAULT_SETTINGS_FILE = ".agent-settings.yml"
-
-_DEFAULT = Settings()
-
-
-def load_settings(settings_path: Path | str | None = None) -> Settings:
-    """Return a `Settings` instance hydrated from `.agent-settings.yml`.
-
-    Parameters
-    ----------
-    settings_path:
-        Explicit override. ``None`` resolves to ``./.agent-settings.yml``
-        relative to the current working directory — same convention as
-        ``chat_history``.
-    """
-    path = Path(settings_path) if settings_path else Path(DEFAULT_SETTINGS_FILE)
-    raw = _read_section(path)
-    if raw is None:
-        return _DEFAULT
-    return _settings_from_raw(raw)
-
-
-def _read_section(path: Path) -> dict[str, Any] | None:
-    """Return the ``commands.suggestion`` mapping or ``None`` on any miss.
-
-    Centralized loader (road-to-portable-dev-preferences P3): tolerance
-    contract handles missing file / malformed YAML / no PyYAML uniformly.
-    No ``commands.*`` keys are whitelisted, so user-global cannot cascade
-    into this section.
-    """
-    try:
-        from scripts._lib.agent_settings import load_agent_settings
-    except ImportError:  # pragma: no cover — script-style invocation
-        import sys as _sys
-        from pathlib import Path as _Path
-        _sys.path.insert(0, str(_Path(__file__).resolve().parent.parent))
-        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
-
-    data = load_agent_settings(project_path=path)
-    commands = data.get("commands")
-    if not isinstance(commands, dict):
-        return None
-    section = commands.get("suggestion")
-    if not isinstance(section, dict):
-        return None
-    return section
-
-
-def _settings_from_raw(raw: dict[str, Any]) -> Settings:
-    return Settings(
-        enabled=_coerce_bool(raw.get("enabled"), _DEFAULT.enabled),
-        confidence_floor=_coerce_floor(
-            raw.get("confidence_floor"), _DEFAULT.confidence_floor
-        ),
-        cooldown_seconds=_coerce_nonneg_int(
-            raw.get("cooldown_seconds"), _DEFAULT.cooldown_seconds
-        ),
-        max_options=_coerce_nonneg_int(
-            raw.get("max_options"), _DEFAULT.max_options
-        ),
-        blocklist=_coerce_str_tuple(raw.get("blocklist")),
-    )
-
-
-def _coerce_bool(value: Any, default: bool) -> bool:
-    if isinstance(value, bool):
-        return value
-    if value is None:
-        return default
-    if isinstance(value, str):
-        s = value.strip().lower()
-        if s in ("true", "yes", "on", "1"):
-            return True
-        if s in ("false", "no", "off", "0"):
-            return False
-    return default
-
-
-def _coerce_floor(value: Any, default: float) -> float:
-    try:
-        f = float(value)  # type: ignore[arg-type]
-    except (TypeError, ValueError):
-        return default
-    if f < 0.0:
-        return 0.0
-    if f > 1.0:
-        return 1.0
-    return f
-
-
-def _coerce_nonneg_int(value: Any, default: int) -> int:
-    try:
-        i = int(value)  # type: ignore[arg-type]
-    except (TypeError, ValueError):
-        return default
-    return i if i >= 0 else default
-
-
-def _coerce_str_tuple(value: Any) -> tuple[str, ...]:
-    if not isinstance(value, Iterable) or isinstance(value, (str, bytes)):
-        return ()
-    out: list[str] = []
-    for item in value:
-        if isinstance(item, str) and item.strip():
-            out.append(item.strip())
-    return tuple(out)

package/src/scripts/command_suggester/types.py

@@ -1,78 +0,0 @@
-"""Type definitions for the command suggestion engine.
-
-Plain dataclasses — no third-party deps. Kept in a sibling module so
-match/rank/cooldown/render can import without cycles.
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from typing import Optional
-
-
-@dataclass(frozen=True)
-class CommandSpec:
-    """Loaded command metadata that drives matching.
-
-    Fields mirror the `suggestion:` frontmatter block plus the
-    command's `name` and `description`. Ineligible commands are
-    represented with `eligible=False` and are never returned by the
-    matcher; the loader keeps them so cross-referencing stays simple.
-    """
-
-    name: str
-    description: str
-    eligible: bool
-    trigger_description: str = ""
-    trigger_context: str = ""
-    rationale: str = ""
-    confidence_floor: Optional[float] = None
-    cooldown: Optional[str] = None
-
-
-@dataclass(frozen=True)
-class Match:
-    """A scored candidate. `score` is 0.0–1.0 inclusive.
-
-    `matched_trigger` is "description" | "context" | "both" and lets
-    the renderer surface why a command surfaced. `evidence` is the
-    short substring that fired (debugging / golden tests / explain).
-    `has_structural_bonus` is True when a heavy-signal pattern (ticket
-    key, file path, glob) co-occurred in the message — the ranker
-    treats those as specific enough to bypass vague-input suppression.
-    """
-
-    command: str
-    score: float
-    matched_trigger: str
-    evidence: str
-    has_structural_bonus: bool = False
-
-
-@dataclass(frozen=True)
-class Settings:
-    """Runtime knobs read from `.agent-settings.yml`.
-
-    Defaults match the "open decisions" leans in the roadmap.
-    Per-command frontmatter values override the global floor /
-    cooldown.
-    """
-
-    enabled: bool = True
-    confidence_floor: float = 0.6
-    cooldown_seconds: int = 600  # 10m
-    max_options: int = 4
-    blocklist: tuple[str, ...] = ()
-
-
-@dataclass
-class CooldownState:
-    """Per-conversation cooldown tracker — mutable on purpose."""
-
-    last_shown: dict[tuple[str, str], float] = field(default_factory=dict)
-    """Key: (command_name, trigger_evidence). Value: unix timestamp."""
-
-    explicit_invocations: dict[str, float] = field(default_factory=dict)
-    """Commands the user explicitly typed; clears their cooldown."""
-
-    disabled_for_conversation: bool = False
-    """Set by the `/command-suggestion-off` directive (Phase 5)."""

package/src/scripts/compile_router.py

@@ -1,232 +0,0 @@
-#!/usr/bin/env python3
-"""Compile rule frontmatter into ``router.json``.
-
-Reads ``.agent-src.uncondensed/rules/*.md``; produces deterministic JSON
-mapping kernel + tier-1 + tier-2 rules to their triggers and routed
-artifacts, per ``docs/contracts/rule-router.md``.
-
-Stdlib-only, deterministic (sorted keys + sorted lists), idempotent.
-Wired into ``task generate-tools`` after the condense step.
-"""
-from __future__ import annotations
-
-import json
-import sys
-from pathlib import Path
-try:  # invocation-agnostic import (repo-root-on-path vs scripts-on-path)
-    from scripts._lib.agent_settings import project_settings_path
-except ModuleNotFoundError:  # pragma: no cover
-    from _lib.agent_settings import project_settings_path
-
-ROOT = Path(__file__).resolve().parent.parent.parent
-# ADR-017: rules now live across multiple source roots. Legacy
-# .agent-src.uncondensed/rules/ is kept as a fallback for the
-# pure-condensed consumer projection.
-RULES_DIR = ROOT / ".agent-src.uncondensed" / "rules"
-OUT_PATH = ROOT / "dist" / "router.json"
-SETTINGS_PATH = project_settings_path(ROOT)
-SCHEMA_VERSION = 1
-
-# Compile-time rule toggles. Maps rule-id → settings predicate.
-# Rule omitted from router.json when predicate returns False.
-# Per road-to-token-frugality § Phase 8.2 — telegraph.speak compile-time toggle.
-COMPILE_TIME_TOGGLES = {
-    "telegraph-speak": lambda s: bool(
-        s.get("telegraph", {}).get("enabled", True)
-    ) and bool(s.get("telegraph", {}).get("speak", True)),
-}
-
-# Maps legacy tier values to the router-canonical names. See
-# docs/contracts/rule-router.md § Backward compatibility.
-LEGACY_TIER_MAP = {
-    "1": "tier-1",
-    "2": "tier-2",
-    "2a": "tier-2",
-    "3": "tier-1",
-    "mechanical-already": "tier-1",
-    "kernel": "kernel",
-    "tier-1": "tier-1",
-    "tier-2": "tier-2",
-}
-
-ALLOWED_TIERS = {"kernel", "tier-1", "tier-2"}
-ALLOWED_PROFILES = {"minimal", "balanced", "full"}
-ALLOWED_TRIGGER_KEYS = {"keyword", "phrase", "intent", "file_pattern",
-                        "path_prefix", "command"}
-
-
-def _parse_frontmatter(text: str) -> dict:
-    if not text.startswith("---\n"):
-        return {}
-    end = text.find("\n---", 4)
-    if end < 0:
-        return {}
-    block = text[4:end]
-    try:
-        import yaml  # type: ignore
-        data = yaml.safe_load(block) or {}
-        return data if isinstance(data, dict) else {}
-    except ImportError:
-        return _parse_frontmatter_minimal(block)
-
-
-def _parse_frontmatter_minimal(block: str) -> dict:
-    """Minimal YAML parser fallback (flat scalars + simple lists)."""
-    out: dict = {}
-    cur_key = None
-    for raw in block.splitlines():
-        line = raw.rstrip()
-        if not line or line.lstrip().startswith("#"):
-            continue
-        if line.startswith("  - ") and cur_key:
-            out.setdefault(cur_key, []).append(line[4:].strip())
-        elif ":" in line and not line.startswith(" "):
-            k, _, v = line.partition(":")
-            cur_key = k.strip()
-            v = v.strip()
-            if v in ("", "[]"):
-                out[cur_key] = [] if v == "[]" else None
-            else:
-                out[cur_key] = v.strip('"').strip("'")
-    return out
-
-
-def _resolve_tier(rule_type: str, raw_tier: str) -> str:
-    if rule_type == "always":
-        return "kernel"
-    return LEGACY_TIER_MAP.get(str(raw_tier), "tier-2")
-
-
-def _normalize_trigger(item) -> dict | None:
-    if not isinstance(item, dict):
-        return None
-    keys = [k for k in item if k in ALLOWED_TRIGGER_KEYS]
-    if len(keys) != 1:
-        return None
-    return {keys[0]: str(item[keys[0]])}
-
-
-def _load_settings() -> dict:
-    """Read .agent-settings.yml for compile-time toggles.
-
-    Centralized loader (road-to-portable-dev-preferences P3): tolerance
-    contract handles missing file / malformed YAML / no PyYAML uniformly.
-    """
-    try:
-        from scripts._lib.agent_settings import load_agent_settings
-    except ImportError:  # pragma: no cover — script-style invocation
-        import sys as _sys
-        from pathlib import Path as _Path
-        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
-        from _lib.agent_settings import load_agent_settings  # type: ignore[import-not-found]
-
-    return load_agent_settings(project_path=SETTINGS_PATH)
-
-
-def _iter_rule_files() -> list[Path]:
-    """Walk every source root for rule files. First root wins per id."""
-    try:
-        from scripts._lib.agent_src import artefact_roots  # type: ignore
-    except ImportError:
-        import sys as _sys
-        from pathlib import Path as _Path
-        _sys.path.insert(0, str(_Path(__file__).resolve().parent))
-        from _lib.agent_src import artefact_roots  # type: ignore[import-not-found]
-
-    seen: dict[str, Path] = {}
-    roots = artefact_roots()
-    if not roots:
-        # Pure-condensed fallback for consumer projections that vendor
-        # the flat dist/agent-src/ tree without sources.
-        if RULES_DIR.exists():
-            for path in sorted(RULES_DIR.glob("*.md")):
-                seen.setdefault(path.stem, path)
-    else:
-        for src_root in roots:
-            rd = src_root / "rules"
-            if not rd.exists():
-                continue
-            for path in sorted(rd.glob("*.md")):
-                seen.setdefault(path.stem, path)
-    return [seen[k] for k in sorted(seen)]
-
-
-def _collect(rules_dir: Path) -> dict:
-    settings = _load_settings()
-    kernel: list[str] = []
-    tiered: dict[str, list[dict]] = {"tier-1": [], "tier-2": []}
-    for path in _iter_rule_files():
-        fm = _parse_frontmatter(path.read_text(encoding="utf-8"))
-        if not fm:
-            continue
-        rule_id = path.stem
-        if rule_id in COMPILE_TIME_TOGGLES:
-            if not COMPILE_TIME_TOGGLES[rule_id](settings):
-                continue
-        rule_type = str(fm.get("type", "auto"))
-        # Manual rules are reference-only (ADR-004) — no router emission.
-        if rule_type == "manual":
-            continue
-        tier = _resolve_tier(rule_type, fm.get("tier", ""))
-        if tier not in ALLOWED_TIERS:
-            continue
-        if tier == "kernel":
-            kernel.append(rule_id)
-            continue
-        triggers_raw = fm.get("triggers") or []
-        triggers = [t for t in (_normalize_trigger(x) for x in triggers_raw) if t]
-        routes_to = sorted(str(x) for x in (fm.get("routes_to") or []))
-        entry = {"id": rule_id, "triggers": triggers, "routes_to": routes_to}
-        tiered[tier].append(entry)
-    for k in tiered:
-        tiered[k].sort(key=lambda x: x["id"])
-    return {"kernel": sorted(kernel), **{k.replace("-", "_"): v for k, v in tiered.items()}}
-
-
-def build() -> dict:
-    collected = _collect(RULES_DIR)
-    return {
-        "schema_version": SCHEMA_VERSION,
-        "kernel": collected["kernel"],
-        "tier_1": collected["tier_1"],
-        "tier_2": collected["tier_2"],
-        "profiles": {
-            "minimal":  ["__kernel__"],
-            "balanced": ["__kernel__", "__tier_1__"],
-            "full":     ["__kernel__", "__tier_1__", "__tier_2__"],
-        },
-    }
-
-
-PRETTY_PATH = OUT_PATH.with_suffix(".pretty.json")
-
-
-def main(argv: list[str]) -> int:
-    out = build()
-    # Default: minified (Phase 2 of road-to-value-dashboard-netto-cuts).
-    # `--pretty` writes the human-readable variant ONLY (no minified).
-    # The Python consumers in this repo (`lint_rule_budget`,
-    # `check_router`) use `json.load()` and are format-agnostic.
-    pretty_text = json.dumps(out, indent=2, sort_keys=False) + "\n"
-    minified_text = json.dumps(out, separators=(",", ":"), sort_keys=False) + "\n"
-    text = pretty_text if "--pretty" in argv else minified_text
-    target_path = PRETTY_PATH if "--pretty" in argv else OUT_PATH
-    if "--check" in argv:
-        if not OUT_PATH.exists() or OUT_PATH.read_text(encoding="utf-8") != minified_text:
-            print("router.json out of date — run scripts/compile_router.py", file=sys.stderr)
-            return 1
-        print("✅  router.json is up to date")
-        return 0
-    target_path.parent.mkdir(parents=True, exist_ok=True)
-    target_path.write_text(text, encoding="utf-8")
-    counts = (len(out["kernel"]), len(out["tier_1"]), len(out["tier_2"]))
-    fmt = "pretty" if "--pretty" in argv else "minified"
-    print(
-        f"✅  {target_path.name} ({fmt}) — "
-        f"kernel={counts[0]}  tier-1={counts[1]}  tier-2={counts[2]}"
-    )
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))