@event4u/agent-config 1.13.0 → 1.14.0

package/scripts/check_compression.py

@@ -8,6 +8,8 @@ Checks that compression preserved structural integrity:
 - All code blocks preserved exactly
 - YAML frontmatter identical
 - Word count reduction within healthy range (10-60%)
+- Iron Law sections (## Iron Law / ### Iron Law / ## The Iron Law / Iron Laws / numbered)
+  preserved per `preservation-guard`: heading verbatim at original level, ≤ 15% reduction
 
 Exit codes: 0 = clean, 1 = issues found, 3 = internal error
 """
@@ -60,6 +62,103 @@ def extract_frontmatter(text: str) -> str:
     return m.group(1).strip() if m else ""
 
 
+# Matches `## Iron Law`, `## The Iron Law`, `## Iron Laws`, `### Iron Law — …`,
+# `## Iron Law 1 — …`, etc. Any heading level 2-6.
+IRON_LAW_HEADING = re.compile(r"^(#{2,6})\s+(The\s+)?Iron Laws?\b")
+
+LIST_ITEM_RE = re.compile(r"^(?:[-*+]|\d+\.)\s")
+INNER_HEADING_RE = re.compile(r"^#{1,6}\s")
+
+
+def count_iron_law_structure(body: str) -> dict:
+    """Count structural units in an Iron Law body.
+
+    Returns counts of paragraphs (blank-line-separated prose blocks),
+    list items (bullet + numbered), and fenced code blocks. Caveman
+    compression may shorten word count freely; what must NOT change is
+    the count of these structural units. Each represents a passage of
+    the law that the source decided to keep.
+
+    Multi-line list items (bullet text wrapped to indented continuation
+    lines, no blank line between) count as ONE list item, not as a
+    list item plus a paragraph.
+    """
+    paragraphs = 0
+    list_items = 0
+    code_blocks = 0
+    in_code = False
+    state = "blank"  # "blank" | "paragraph" | "list"
+    for line in body.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            if not in_code:
+                code_blocks += 1
+            in_code = not in_code
+            state = "blank"
+            continue
+        if in_code:
+            continue
+        if not stripped:
+            state = "blank"
+            continue
+        if LIST_ITEM_RE.match(stripped):
+            list_items += 1
+            state = "list"
+            continue
+        if INNER_HEADING_RE.match(stripped):
+            state = "blank"
+            continue
+        # Indented non-empty line right after a list item is a wrap
+        # continuation of that item, not a new paragraph.
+        if state == "list" and line.startswith((" ", "\t")):
+            continue
+        if state != "paragraph":
+            paragraphs += 1
+            state = "paragraph"
+    return {"paragraphs": paragraphs, "list_items": list_items, "code_blocks": code_blocks}
+
+
+def extract_iron_law_sections(text: str) -> list[tuple[str, int, str]]:
+    """Return [(heading, level, body)] for each Iron Law section.
+
+    Body is everything after the heading until the next heading at the same
+    or higher (numerically lower) level — fenced code blocks included verbatim.
+    """
+    lines = text.splitlines()
+    sections: list[tuple[str, int, str]] = []
+    i = 0
+    in_code = False
+    while i < len(lines):
+        line = lines[i]
+        if line.strip().startswith("```"):
+            in_code = not in_code
+            i += 1
+            continue
+        if not in_code:
+            m = IRON_LAW_HEADING.match(line)
+            if m:
+                heading = line.rstrip()
+                level = len(m.group(1))
+                body_lines: list[str] = []
+                j = i + 1
+                inner_code = False
+                while j < len(lines):
+                    jline = lines[j]
+                    if jline.strip().startswith("```"):
+                        inner_code = not inner_code
+                    if not inner_code:
+                        hm = re.match(r"^(#{1,6})\s", jline)
+                        if hm and len(hm.group(1)) <= level:
+                            break
+                    body_lines.append(jline)
+                    j += 1
+                sections.append((heading, level, "\n".join(body_lines)))
+                i = j
+                continue
+        i += 1
+    return sections
+
+
 def check_pair(rel_path: str, source: str, compressed: str) -> List[Issue]:
     """Compare source and compressed versions of a file."""
     issues: List[Issue] = []
@@ -96,6 +195,46 @@ def check_pair(rel_path: str, source: str, compressed: str) -> List[Issue]:
                 issues.append(Issue(rel_path, "modified_code_block", "error",
                                     f"Code block {i+1} content changed during compression"))
 
+    # Iron Law preservation — non-negotiable behavioral rules, see preservation-guard
+    src_laws = extract_iron_law_sections(source)
+    cmp_laws = extract_iron_law_sections(compressed)
+    cmp_law_map = {h: (lvl, body) for h, lvl, body in cmp_laws}
+    # Build a level-agnostic lookup so we can detect heading-level downgrades
+    # (`## Iron Law` → `### Iron Law`).
+    cmp_law_by_text = {h.lstrip("# ").strip(): (lvl, h, body)
+                       for h, lvl, body in cmp_laws}
+    for src_heading, src_level, src_body in src_laws:
+        src_text = src_heading.lstrip("# ").strip()
+        if src_heading not in cmp_law_map:
+            # Heading text may exist at a different level → downgrade
+            if src_text in cmp_law_by_text:
+                cmp_level, cmp_heading, _ = cmp_law_by_text[src_text]
+                if cmp_level != src_level:
+                    issues.append(Issue(rel_path, "iron_law_heading_downgrade", "error",
+                                        f"Iron Law heading level changed: "
+                                        f"{'#' * src_level} → {'#' * cmp_level} "
+                                        f"({src_heading.strip()})"))
+                    continue
+            issues.append(Issue(rel_path, "iron_law_missing", "error",
+                                f"Iron Law section removed during compression: "
+                                f"{src_heading.strip()}"))
+            continue
+        # Section exists at correct level — check structural-unit survival.
+        # Caveman compression is fine (drop articles, terse phrasing); what
+        # must NOT change is the count of paragraphs, list items, and code
+        # blocks. Each is a passage the source kept on purpose.
+        _, cmp_body = cmp_law_map[src_heading]
+        src_struct = count_iron_law_structure(src_body)
+        cmp_struct = count_iron_law_structure(cmp_body)
+        for kind, src_n in src_struct.items():
+            cmp_n = cmp_struct[kind]
+            if cmp_n < src_n:
+                issues.append(Issue(rel_path, "iron_law_passage_dropped", "error",
+                                    f"Iron Law section dropped "
+                                    f"{src_n - cmp_n} {kind} "
+                                    f"({src_n} → {cmp_n}): "
+                                    f"{src_heading.strip()}"))
+
     # Word count ratio
     src_words = len(source.split())
     cmp_words = len(compressed.split())

package/scripts/check_iron_law_prominence.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""
+Iron Law prominence checker — enforces that any rule file declaring an
+"Iron Law" places it at the top of the file at H2 level.
+
+Rules:
+  1. No heading at H3 or deeper may match "Iron Law(s)" — Iron Laws must
+     be H2 sections, never sub-sections.
+  2. If a file declares one or more Iron-Law H2 sections, at least one
+     of them must be among the first two H2 headings of the file.
+
+Files with no Iron-Law heading at all are exempt — they may legitimately
+reference Iron Laws from other rules in prose only.
+
+Code blocks are skipped to avoid false positives on quoted text.
+
+Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+HEADING_RE = re.compile(r"^(#{1,6})\s+(.+?)\s*$")
+IRON_LAW_RE = re.compile(r"\biron\s+laws?\b", re.IGNORECASE)
+FENCE_RE = re.compile(r"^\s*```")
+
+
+@dataclass
+class Violation:
+    file: str
+    line: int
+    kind: str        # "deep_iron_law" | "buried_iron_law"
+    detail: str
+
+
+def _parse_headings(text: str) -> list[tuple[int, int, str]]:
+    """Return (line_no, depth, title) for each heading outside code fences."""
+    headings: list[tuple[int, int, str]] = []
+    in_fence = False
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        if FENCE_RE.match(raw):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+        m = HEADING_RE.match(raw)
+        if not m:
+            continue
+        depth = len(m.group(1))
+        title = m.group(2).strip()
+        headings.append((lineno, depth, title))
+    return headings
+
+
+def scan_file(path: Path) -> list[Violation]:
+    text = path.read_text(encoding="utf-8")
+    headings = _parse_headings(text)
+
+    violations: list[Violation] = []
+
+    # Rule 1: no Iron Law at H3 or deeper
+    for lineno, depth, title in headings:
+        if depth >= 3 and IRON_LAW_RE.search(title):
+            violations.append(Violation(
+                file=str(path), line=lineno, kind="deep_iron_law",
+                detail=f"H{depth} heading `{title}` — promote to H2",
+            ))
+
+    # Rule 2: if any H2 Iron Law exists, it must be in first 2 H2 positions
+    h2 = [(ln, t) for ln, d, t in headings if d == 2]
+    iron_h2 = [(ln, t) for ln, t in h2 if IRON_LAW_RE.search(t)]
+    if iron_h2:
+        first_two_lines = {ln for ln, _ in h2[:2]}
+        if not any(ln in first_two_lines for ln, _ in iron_h2):
+            first_iron_ln, first_iron_title = iron_h2[0]
+            preceding = [t for ln, t in h2 if ln < first_iron_ln]
+            violations.append(Violation(
+                file=str(path), line=first_iron_ln, kind="buried_iron_law",
+                detail=(
+                    f"Iron Law H2 `{first_iron_title}` at line {first_iron_ln} "
+                    f"is preceded by {len(preceding)} non-Iron-Law H2 section(s): "
+                    f"{preceding}. Move Iron Law into the first 2 H2 positions."
+                ),
+            ))
+
+    return violations
+
+
+def _resolve_targets(paths: list[str]) -> list[Path]:
+    out: list[Path] = []
+    for raw in paths:
+        p = Path(raw)
+        if p.is_dir():
+            out.extend(sorted(p.rglob("*.md")))
+        elif p.suffix == ".md":
+            out.append(p)
+    return out
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "paths", nargs="*",
+        default=[".agent-src.uncompressed/rules"],
+        help="Files or directories to scan (default: .agent-src.uncompressed/rules)",
+    )
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    args = parser.parse_args()
+
+    targets = _resolve_targets(args.paths)
+    all_violations: list[Violation] = []
+    for path in targets:
+        if not path.exists():
+            print(f"⚠️  Not found: {path}", file=sys.stderr)
+            continue
+        all_violations.extend(scan_file(path))
+
+    if args.format == "json":
+        print(json.dumps([asdict(v) for v in all_violations], indent=2, ensure_ascii=False))
+    else:
+        if not all_violations:
+            print(f"✅  Iron Law prominence clean ({len(targets)} file(s) scanned).")
+        else:
+            print(f"❌  {len(all_violations)} Iron-Law prominence violation(s):\n")
+            for v in all_violations:
+                print(f"  {v.file}:{v.line} — {v.kind}")
+                print(f"    │ {v.detail}")
+
+    return 1 if all_violations else 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:  # noqa: BLE001
+        print(f"❌  Internal error: {exc}", file=sys.stderr)
+        sys.exit(3)

package/scripts/check_md_language.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""
+Markdown language checker — enforces language-and-tone § ".md files are ALWAYS English".
+
+Scans .md files for German content (umlauts, function words, quoted DE phrases)
+in body prose, skipping:
+- Fenced code blocks (``` ... ```)
+- Inline code (`...`)
+- Labeled DE: ... · EN: ... anchor blocks
+- URLs and file paths inside backticks
+
+Exit codes: 0 = clean, 1 = violations found, 3 = internal error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, asdict
+from pathlib import Path
+
+# Umlauts and German-only characters
+UMLAUT_RE = re.compile(r"[äöüÄÖÜß]")
+
+# German function words that almost never appear in English technical prose
+DE_WORDS = [
+    "für", "nicht", "dass", "wenn", "sollte", "werden", "arbeite",
+    "selbstständig", "jetzt", "einfach", "weiter", "lösche", "frag",
+    "schreib", "mach", "auch", "hier", "diese", "dieser", "dieses",
+    "vermutlich", "bitte", "kannst", "sollen", "müssen", "wäre",
+]
+DE_WORD_RE = re.compile(
+    r"\b(" + "|".join(re.escape(w) for w in DE_WORDS) + r")\b",
+    re.IGNORECASE,
+)
+
+# Labeled bilingual anchor: lines starting with "DE:" or "- DE:" (and same for EN)
+DE_ANCHOR_RE = re.compile(r"^\s*[-*]?\s*(DE|EN):\s", re.IGNORECASE)
+
+# Inline code spans
+INLINE_CODE_RE = re.compile(r"`[^`]*`")
+
+# Per-line escape: append `<!-- md-language-check: ignore -->` to a line
+# to suppress findings on that line. For meta-documentation that quotes
+# German tokens as trigger examples (e.g. inside language-and-tone.md).
+IGNORE_RE = re.compile(r"<!--\s*md-language-check:\s*ignore\s*-->", re.IGNORECASE)
+
+
+@dataclass
+class Violation:
+    file: str
+    line: int
+    kind: str        # "umlaut" | "de_word"
+    match: str
+    context: str
+
+
+def _strip_inline_code(text: str) -> str:
+    return INLINE_CODE_RE.sub("", text)
+
+
+def scan_file(path: Path) -> list[Violation]:
+    violations: list[Violation] = []
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except (OSError, UnicodeDecodeError) as exc:
+        print(f"⚠️  Cannot read {path}: {exc}", file=sys.stderr)
+        return violations
+
+    in_fence = False
+    in_frontmatter = False
+    for lineno, raw in enumerate(lines, start=1):
+        stripped = raw.lstrip()
+
+        # YAML frontmatter at top of file
+        if lineno == 1 and stripped == "---":
+            in_frontmatter = True
+            continue
+        if in_frontmatter:
+            if stripped == "---":
+                in_frontmatter = False
+            continue
+
+        # Fenced code blocks
+        if stripped.startswith("```") or stripped.startswith("~~~"):
+            in_fence = not in_fence
+            continue
+        if in_fence:
+            continue
+
+        # Indented code blocks (4+ leading spaces, non-list)
+        if raw.startswith("    ") and not stripped.startswith(("-", "*", "+", "1", "2", "3", "4", "5", "6", "7", "8", "9")):
+            continue
+
+        # Labeled bilingual anchor — allowed location for DE prose
+        if DE_ANCHOR_RE.match(raw):
+            continue
+
+        # Per-line opt-out marker
+        if IGNORE_RE.search(raw):
+            continue
+
+        # Strip inline code spans before scanning
+        scan_text = _strip_inline_code(raw)
+
+        for m in UMLAUT_RE.finditer(scan_text):
+            violations.append(Violation(
+                file=str(path), line=lineno, kind="umlaut",
+                match=m.group(0), context=raw.rstrip(),
+            ))
+
+        for m in DE_WORD_RE.finditer(scan_text):
+            violations.append(Violation(
+                file=str(path), line=lineno, kind="de_word",
+                match=m.group(0), context=raw.rstrip(),
+            ))
+
+    return violations
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("paths", nargs="+", help="One or more .md files to scan")
+    parser.add_argument("--format", choices=["text", "json"], default="text")
+    args = parser.parse_args()
+
+    all_violations: list[Violation] = []
+    for raw_path in args.paths:
+        path = Path(raw_path)
+        if not path.exists():
+            print(f"⚠️  Not found: {path}", file=sys.stderr)
+            continue
+        if path.suffix != ".md":
+            print(f"⚠️  Skipping non-.md: {path}", file=sys.stderr)
+            continue
+        all_violations.extend(scan_file(path))
+
+    if args.format == "json":
+        print(json.dumps([asdict(v) for v in all_violations], indent=2, ensure_ascii=False))
+    else:
+        if not all_violations:
+            print("✅  No German content detected.")
+        else:
+            print(f"❌  {len(all_violations)} violation(s) found:\n")
+            for v in all_violations:
+                print(f"  {v.file}:{v.line} — {v.kind} `{v.match}`")
+                print(f"    │ {v.context}")
+
+    return 1 if all_violations else 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as exc:  # noqa: BLE001
+        print(f"❌  Internal error: {exc}", file=sys.stderr)
+        sys.exit(3)

package/scripts/check_portability.py

@@ -329,6 +329,42 @@ _CLI_INVOCATION_MAP: list[tuple[re.Pattern, str]] = [
         re.compile(r"bash\s+scripts/first-run\.sh\b"),
         "./agent-config first-run",
     ),
+    (
+        re.compile(r"(?:PYTHONPATH=\S+\s+)?python3\s+-m\s+work_engine\b"),
+        "./agent-config implement-ticket",
+    ),
+    (
+        re.compile(r"(?:PYTHONPATH=\S+\s+)?python3\s+-m\s+implement_ticket\b"),
+        "./agent-config implement-ticket",
+    ),
+    (
+        re.compile(r"python3\s+scripts/memory_lookup\.py\b"),
+        "./agent-config memory:lookup",
+    ),
+    (
+        re.compile(r"python3\s+scripts/memory_signal\.py\b"),
+        "./agent-config memory:signal",
+    ),
+    (
+        re.compile(r"python3\s+scripts/memory_hash\.py\b"),
+        "./agent-config memory:hash",
+    ),
+    (
+        re.compile(r"python3\s+scripts/check_memory_proposal\.py\b"),
+        "./agent-config memory:check-proposal",
+    ),
+    (
+        re.compile(r"python3\s+scripts/check_memory\.py\b"),
+        "./agent-config memory:check",
+    ),
+    (
+        re.compile(r"python3\s+scripts/check_proposal\.py\b"),
+        "./agent-config proposal:check",
+    ),
+    (
+        re.compile(r"python3\s+scripts/refine_ticket_detect\.py\b"),
+        "./agent-config refine-ticket:detect",
+    ),
 ]
 
 # Paths that legitimately document the raw invocations (e.g. the CLI's

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",
+]