@event4u/agent-config 1.13.0 → 1.15.0

package/scripts/check_public_links.py

@@ -0,0 +1,185 @@
+#!/usr/bin/env python3
+"""
+Public-link checker for the agent-config public surface.
+
+Scans the public-surface files (README.md, AGENTS.md, docs/architecture.md)
+for markdown links into `docs/contracts/`, then validates each link against
+the `stability:` frontmatter declared by the target file (per
+`docs/contracts/STABILITY.md`).
+
+Rules:
+  - target stability=stable        → OK (no marker required).
+  - target stability=beta          → OK; warns if surrounding text has no
+                                     visible "(beta)" marker.
+  - target stability=experimental  → ERROR. Public surface MUST NOT link
+                                     to experimental contracts.
+  - target outside docs/contracts/ but referenced for contract-shaped
+    intent (links into agents/contexts/*.md from public files) → ERROR.
+  - target file missing            → ERROR.
+  - target file under docs/contracts/ without `stability:` frontmatter
+    (except STABILITY.md itself) → ERROR.
+
+Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
+
+Usage:
+    python3 scripts/check_public_links.py
+    python3 scripts/check_public_links.py --list      # list contracts + levels
+    python3 scripts/check_public_links.py --json      # machine-readable
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+PUBLIC_FILES = [Path("README.md"), Path("AGENTS.md"), Path("docs/architecture.md")]
+CONTRACTS_DIR = Path("docs/contracts")
+STABILITY_FILE = CONTRACTS_DIR / "STABILITY.md"
+
+LINK_RE = re.compile(r"\[(?P<text>[^\]]+)\]\((?P<href>[^)\s]+)(?:\s+\"[^\"]*\")?\)")
+FRONTMATTER_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+STABILITY_RE = re.compile(r"^stability:\s*(\w+)\s*$", re.MULTILINE)
+
+
+@dataclass
+class Violation:
+    file: str
+    line: int
+    href: str
+    reason: str
+    severity: str  # "error" | "warning"
+
+
+def read_stability(path: Path) -> str | None:
+    if not path.exists():
+        return None
+    txt = path.read_text(encoding="utf-8")
+    m = FRONTMATTER_RE.match(txt)
+    if not m:
+        return None
+    sm = STABILITY_RE.search(m.group(1))
+    return sm.group(1) if sm else None
+
+
+def collect_contracts() -> dict[Path, str | None]:
+    out: dict[Path, str | None] = {}
+    for p in sorted((ROOT / CONTRACTS_DIR).glob("*.md")):
+        rel = p.relative_to(ROOT)
+        out[rel] = read_stability(p)
+    return out
+
+
+def resolve(public_file: Path, href: str) -> Path | None:
+    href = href.split("#", 1)[0]
+    if not href or href.startswith(("http://", "https://", "mailto:", "tel:")):
+        return None
+    if href.startswith("/"):
+        return Path(href.lstrip("/"))
+    return (public_file.parent / href).resolve().relative_to(ROOT.resolve())
+
+
+def scan_file(public_file: Path, contracts: dict[Path, str | None]) -> list[Violation]:
+    abs_path = ROOT / public_file
+    if not abs_path.exists():
+        return []
+    violations: list[Violation] = []
+    for lineno, line in enumerate(abs_path.read_text(encoding="utf-8").splitlines(), 1):
+        for m in LINK_RE.finditer(line):
+            href = m.group("href")
+            text = m.group("text")
+            try:
+                target = resolve(public_file, href)
+            except ValueError:
+                continue
+            if target is None:
+                continue
+            if target.parts[:2] == ("agents", "contexts") and target.suffix == ".md":
+                violations.append(Violation(str(public_file), lineno, href,
+                    "public surface MUST NOT link into agents/contexts/ — move target to docs/contracts/",
+                    "error"))
+                continue
+            if target.parts[:2] != ("docs", "contracts") or target.suffix != ".md":
+                continue
+            if target == STABILITY_FILE:
+                continue
+            if target not in contracts:
+                violations.append(Violation(str(public_file), lineno, href,
+                    f"target not found: {target}", "error"))
+                continue
+            level = contracts[target]
+            if level is None:
+                violations.append(Violation(str(public_file), lineno, href,
+                    f"target missing 'stability:' frontmatter: {target}", "error"))
+                continue
+            if level == "experimental":
+                violations.append(Violation(str(public_file), lineno, href,
+                    f"public surface MUST NOT link to experimental contract: {target}",
+                    "error"))
+                continue
+            if level == "beta":
+                window = line.lower()
+                if "(beta)" not in window and "[beta]" not in window:
+                    violations.append(Violation(str(public_file), lineno, href,
+                        f"link to beta contract '{target}' lacks visible (beta) marker",
+                        "warning"))
+    return violations
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--list", action="store_true", help="list contracts + stability levels")
+    ap.add_argument("--json", action="store_true", help="machine-readable output")
+    ap.add_argument("--strict", action="store_true",
+                    help="fail on warnings as well as errors (default: errors only)")
+    args = ap.parse_args()
+
+    contracts = collect_contracts()
+    if args.list:
+        for p, lvl in contracts.items():
+            print(f"  {lvl or '(no frontmatter)':14}  {p}")
+        return 0
+
+    missing_fm = [p for p, lvl in contracts.items() if lvl is None and p != STABILITY_FILE]
+    violations: list[Violation] = []
+    for p in missing_fm:
+        violations.append(Violation(str(p), 0, "(self)",
+            "missing 'stability:' frontmatter required by docs/contracts/STABILITY.md",
+            "error"))
+    for f in PUBLIC_FILES:
+        violations.extend(scan_file(f, contracts))
+
+    if args.json:
+        print(json.dumps([asdict(v) for v in violations], indent=2))
+    else:
+        errors = [v for v in violations if v.severity == "error"]
+        warnings = [v for v in violations if v.severity == "warning"]
+        for v in violations:
+            icon = "❌" if v.severity == "error" else "⚠️ "
+            loc = f"{v.file}:{v.line}" if v.line else v.file
+            print(f"{icon}  {loc}  {v.href}\n     → {v.reason}")
+        if not violations:
+            print(f"✅  public-link check clean — {len(contracts)} contracts scanned, "
+                  f"{len(PUBLIC_FILES)} public files clean")
+        else:
+            print(f"\nsummary: {len(errors)} error(s), {len(warnings)} warning(s)")
+
+    has_errors = any(v.severity == "error" for v in violations)
+    has_warnings = any(v.severity == "warning" for v in violations)
+    if has_errors:
+        return 1
+    if has_warnings and args.strict:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as e:
+        print(f"❌  internal error: {e}", file=sys.stderr)
+        sys.exit(3)

package/scripts/check_references.py

@@ -78,6 +78,7 @@ EXAMPLE_PATH_PATTERNS = [
     re.compile(r"agents/overrides/"),           # override examples
     re.compile(r"commands/old-cmd"),            # example placeholder
     re.compile(r"agents/README"),               # README reference (may not exist in package)
+    re.compile(r"agents/index[\w.-]*\.md"),     # planned auto-generated artefact index (F5)
     re.compile(r"agents/docs/"),               # project-specific docs (not in package)
     re.compile(r"agents/contexts/"),           # project-specific contexts (not in package)
     re.compile(r"agents/gates"),               # project-specific policy docs

package/scripts/check_reply_consistency.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+"""check_reply_consistency.py — enforce user-interaction.md Iron Laws.
+
+Single-Source Recommendation Line: a reply with numbered options must
+have ONE bolded `Recommendation: N` / `Empfehlung: N` line, no inline
+`(recommended)` / `(rec)` / `(empfohlen)` tag next to options, and the
+recommended number must appear in the option block.
+
+Modes:
+  --stdin / --file <path>   Validate a single draft (all rules).
+  --scan-dir <dir>          Scan .md tree for legacy inline-tag regression.
+
+Exit codes:
+  0 ok · 2 inline tag · 3 multi-rec · 4 rec-not-in-options
+  5 options-without-rec (strict) · 6 scan-dir found · 9 usage error
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+OPTION_LINE_RE = re.compile(r"^\s*>?\s*(\d+)\.\s+\S")
+REC_LINE_RE = re.compile(
+    r"(?:Recommendation|Empfehlung)\s*:\s*(\d+)\b", re.IGNORECASE
+)
+TAG_RE = re.compile(r"\((?:recommended|rec|empfohlen)\)", re.IGNORECASE)
+CODESPAN_RE = re.compile(r"`[^`\n]*`")
+
+
+def _strip_codespans(line: str) -> str:
+    return CODESPAN_RE.sub("``", line)
+
+
+def find_inline_tag(text: str) -> tuple[int, str] | None:
+    """Return (line_no, raw_line) of the first numbered-option line carrying
+    an inline (recommended)-class tag outside code spans, or None."""
+    for idx, raw in enumerate(text.splitlines(), start=1):
+        stripped = _strip_codespans(raw)
+        if not OPTION_LINE_RE.match(stripped):
+            continue
+        if TAG_RE.search(stripped):
+            return idx, raw.strip()
+    return None
+
+
+def find_option_blocks(text: str) -> list[list[int]]:
+    """Group consecutive numbered-option lines into blocks; return list of
+    blocks, each a list of the numbers found in that block."""
+    blocks: list[list[int]] = []
+    current: list[int] = []
+    for raw in text.splitlines():
+        m = OPTION_LINE_RE.match(raw)
+        if m:
+            current.append(int(m.group(1)))
+        else:
+            if len(current) >= 2:
+                blocks.append(current)
+            current = []
+    if len(current) >= 2:
+        blocks.append(current)
+    return blocks
+
+
+def validate(text: str, strict: bool = False) -> tuple[int, str]:
+    """Run rules. Returns (exit_code, human_message)."""
+    tag = find_inline_tag(text)
+    if tag:
+        line_no, snippet = tag
+        return 2, f"line {line_no}: inline tag on numbered option — {snippet!r}"
+
+    blocks = find_option_blocks(text)
+    rec_numbers = [int(n) for n in REC_LINE_RE.findall(text)]
+
+    if not blocks:
+        return 0, "ok (no numbered options block)"
+
+    if not rec_numbers:
+        if strict:
+            return 5, "numbered options without Recommendation:/Empfehlung: line"
+        return 0, "ok (options without recommendation; non-strict)"
+
+    distinct = sorted(set(rec_numbers))
+    if len(distinct) > 1:
+        return 3, f"multiple distinct recommendation numbers: {distinct}"
+
+    rec_num = distinct[0]
+    for block in blocks:
+        if rec_num in block:
+            return 0, f"ok (recommendation {rec_num} matches option block)"
+    return 4, f"recommendation {rec_num} not present in any option block"
+
+
+def cmd_scan_dir(root: Path) -> int:
+    if not root.is_dir():
+        print(f"error: not a directory: {root}", file=sys.stderr)
+        return 9
+    violations: list[tuple[Path, int, str]] = []
+    for md in sorted(root.rglob("*.md")):
+        text = md.read_text(encoding="utf-8")
+        for idx, raw in enumerate(text.splitlines(), start=1):
+            stripped = _strip_codespans(raw)
+            if OPTION_LINE_RE.match(stripped) and TAG_RE.search(stripped):
+                violations.append((md, idx, raw.strip()))
+    if violations:
+        for path, line, snippet in violations:
+            print(f"  🔴 {path}:{line} — inline-tag — {snippet}", file=sys.stderr)
+        print(f"\n❌  {len(violations)} legacy-pattern violation(s)", file=sys.stderr)
+        return 6
+    print(f"✅  No legacy (recommended) tags found under {root}")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(description=__doc__.split("\n", 1)[0])
+    g = p.add_mutually_exclusive_group(required=True)
+    g.add_argument("--stdin", action="store_true", help="read draft from stdin")
+    g.add_argument("--file", type=Path, help="read draft from file")
+    g.add_argument("--scan-dir", type=Path, help="scan dir for legacy inline tags")
+    p.add_argument("--strict", action="store_true",
+                   help="numbered options REQUIRE recommendation line (rule 5)")
+    p.add_argument("-v", "--verbose", action="store_true")
+    args = p.parse_args(argv)
+
+    if args.scan_dir:
+        return cmd_scan_dir(args.scan_dir)
+
+    text = sys.stdin.read() if args.stdin else args.file.read_text(encoding="utf-8")
+    code, msg = validate(text, strict=args.strict)
+    if code == 0:
+        if args.verbose:
+            print(f"✅  {msg}")
+        return 0
+    print(f"❌  [exit {code}] {msg}", file=sys.stderr)
+    return code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/command_suggester/__init__.py

@@ -0,0 +1,51 @@
+"""Context-aware command suggestion engine.
+
+Public API exposed for the always-on `command-suggestion` rule and for
+tests. The engine is **deterministic** and **read-only**: it scores
+candidate commands against a user message + recent context, applies
+ranking, suppresses cooled-down suggestions, and renders a numbered
+options block. It never executes a command — the user pick is what
+triggers the standard slash flow.
+
+See `agents/contexts/command-suggestion-eligibility.md` for the
+locked eligibility table and `road-to-context-aware-command-suggestion`
+for the full design.
+"""
+from .types import CommandSpec, Match, Settings, CooldownState
+from .loader import load_commands
+from .match import match
+from .rank import rank
+from .cooldown import (
+    apply_cooldown,
+    CooldownStore,
+    detect_disable_directive,
+    is_explicit_slash_invocation,
+)
+from .render import render
+from .sanitize import (
+    sanitize_context,
+    sanitize_message,
+    strip_code_blocks,
+    strip_suggestion_echo,
+)
+from .settings import load_settings
+
+__all__ = [
+    "CommandSpec",
+    "Match",
+    "Settings",
+    "CooldownState",
+    "CooldownStore",
+    "load_commands",
+    "load_settings",
+    "match",
+    "rank",
+    "apply_cooldown",
+    "detect_disable_directive",
+    "is_explicit_slash_invocation",
+    "render",
+    "sanitize_context",
+    "sanitize_message",
+    "strip_code_blocks",
+    "strip_suggestion_echo",
+]

package/scripts/command_suggester/cooldown.py

@@ -0,0 +1,132 @@
+"""Suppress recently-shown suggestions per conversation.
+
+Cooldown key is `(command_name, evidence)` so two distinct triggers
+for the same command (e.g. `/commit` from "git status shows changes"
+vs. from "save this to git") track separately. The user explicitly
+invoking a command via `/command` clears that command's cooldown so
+the next genuine match surfaces immediately.
+
+The store is in-memory; persistence is the agent's job (conversation
+state). Phase 5 wires the per-conversation `disabled_for_conversation`
+flag into the same store.
+"""
+from __future__ import annotations
+
+import re
+import time
+from typing import Mapping
+
+from .types import CommandSpec, CooldownState, Match, Settings
+
+
+_DURATION_RE = re.compile(r"^\s*(\d+)\s*([smhd])\s*$", re.IGNORECASE)
+_DISABLE_DIRECTIVE_RE = re.compile(
+    r"(?:^|\s)/command-suggestion-(off|on)\b", re.IGNORECASE
+)
+_EXPLICIT_SLASH_RE = re.compile(r"^\s*/[A-Za-z][A-Za-z0-9_-]*\b")
+
+
+def is_explicit_slash_invocation(message: str) -> bool:
+    """Return True when the message starts with an explicit ``/command``.
+
+    Per the `command-suggestion` rule, explicit slash invocations
+    bypass the suggestion layer entirely \u2014 they're handled by
+    `slash-commands` directly. The engine should not score in that
+    case. Helper exposed for the runtime caller and the GT-CS4
+    golden.
+    """
+    if not message:
+        return False
+    return bool(_EXPLICIT_SLASH_RE.match(message))
+
+
+def detect_disable_directive(message: str) -> bool | None:
+    """Detect a `/command-suggestion-off` / `-on` directive in the user message.
+
+    Returns ``True`` to disable for the rest of the conversation,
+    ``False`` to re-enable, ``None`` when no directive is present.
+    The latest occurrence in the message wins (order-stable on tie).
+    Mutating the `CooldownStore` is the caller's responsibility — this
+    helper stays pure so tests don't have to fake time.
+    """
+    if not message:
+        return None
+    last: bool | None = None
+    for m in _DISABLE_DIRECTIVE_RE.finditer(message):
+        last = m.group(1).lower() == "off"
+    return last
+
+
+def parse_cooldown(value: str | None, default_seconds: int) -> int:
+    """Convert `'10m'` / `'30s'` / `'1h'` / `'2d'` to seconds.
+
+    Returns ``default_seconds`` for any malformed or missing input —
+    keeping the runtime fail-soft. The schema validator caps the
+    string length, so we never see absurd inputs in practice.
+    """
+    if not value:
+        return default_seconds
+    m = _DURATION_RE.match(str(value))
+    if not m:
+        return default_seconds
+    n, unit = int(m.group(1)), m.group(2).lower()
+    factor = {"s": 1, "m": 60, "h": 3600, "d": 86400}[unit]
+    return n * factor
+
+
+class CooldownStore:
+    """Thin wrapper around `CooldownState` with time-aware helpers.
+
+    Tests inject a fixed `now` to make decay deterministic; runtime
+    leaves it as `time.time`.
+    """
+
+    def __init__(self, state: CooldownState | None = None, *, now=time.time):
+        self.state = state or CooldownState()
+        self._now = now
+
+    def is_cooled_down(
+        self, command: str, evidence: str, *, window_seconds: int
+    ) -> bool:
+        last = self.state.last_shown.get((command, evidence))
+        if last is None:
+            return False
+        return (self._now() - last) < window_seconds
+
+    def record_shown(self, matches: list[Match]) -> None:
+        ts = self._now()
+        for m in matches:
+            self.state.last_shown[(m.command, m.evidence)] = ts
+
+    def record_explicit_invocation(self, command: str) -> None:
+        """Clear the cooldown when the user explicitly types `/command`.
+
+        We drop every entry for that command (across all evidences)
+        so a deliberate invocation always produces a clean slate.
+        """
+        ts = self._now()
+        self.state.explicit_invocations[command] = ts
+        keys_to_drop = [
+            k for k in self.state.last_shown if k[0] == command
+        ]
+        for k in keys_to_drop:
+            del self.state.last_shown[k]
+
+
+def apply_cooldown(
+    matches: list[Match],
+    store: CooldownStore,
+    settings: Settings,
+    specs_by_name: Mapping[str, CommandSpec],
+) -> list[Match]:
+    if store.state.disabled_for_conversation:
+        return []
+    out: list[Match] = []
+    for m in matches:
+        spec = specs_by_name.get(m.command)
+        per_cmd = spec.cooldown if spec else None
+        window = parse_cooldown(per_cmd, settings.cooldown_seconds)
+        if store.is_cooled_down(m.command, m.evidence, window_seconds=window):
+            continue
+        out.append(m)
+    return out

package/scripts/command_suggester/loader.py

@@ -0,0 +1,70 @@
+"""Read command frontmatter into `CommandSpec` instances.
+
+Reuses the package's stdlib-only `validate_frontmatter.parse_frontmatter`
+so the loader and the linter agree on what counts as well-formed.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Any
+
+from .types import CommandSpec
+
+# Sibling stdlib parser — same one the linter calls.
+_SCRIPTS_DIR = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(_SCRIPTS_DIR))
+from validate_frontmatter import parse_frontmatter  # noqa: E402
+
+
+def load_commands(commands_dir: Path) -> list[CommandSpec]:
+    """Load every `*.md` under ``commands_dir`` as a `CommandSpec`.
+
+    Files without a `suggestion` block are loaded as `eligible=False`
+    with empty rationale — keeps tests deterministic on legacy data.
+    Bad frontmatter is skipped silently; the linter is the gate, not
+    this loader.
+    """
+    specs: list[CommandSpec] = []
+    for path in sorted(commands_dir.glob("*.md")):
+        text = path.read_text(encoding="utf-8")
+        data, _offset = parse_frontmatter(text)
+        if data is None:
+            continue
+        name = str(data.get("name") or path.stem)
+        description = str(data.get("description") or "")
+        spec = _spec_from_data(name, description, data.get("suggestion"))
+        specs.append(spec)
+    return specs
+
+
+def _spec_from_data(
+    name: str, description: str, suggestion: Any
+) -> CommandSpec:
+    if not isinstance(suggestion, dict):
+        return CommandSpec(name=name, description=description, eligible=False)
+    eligible = suggestion.get("eligible") is True
+    if not eligible:
+        return CommandSpec(
+            name=name,
+            description=description,
+            eligible=False,
+            rationale=str(suggestion.get("rationale") or ""),
+        )
+    floor = suggestion.get("confidence_floor")
+    floor_f: float | None
+    try:
+        floor_f = float(floor) if floor is not None else None
+    except (TypeError, ValueError):
+        floor_f = None
+    cooldown = suggestion.get("cooldown")
+    cooldown_s = str(cooldown) if cooldown is not None else None
+    return CommandSpec(
+        name=name,
+        description=description,
+        eligible=True,
+        trigger_description=str(suggestion.get("trigger_description") or ""),
+        trigger_context=str(suggestion.get("trigger_context") or ""),
+        confidence_floor=floor_f,
+        cooldown=cooldown_s,
+    )